From f6cf287bb8acf0ed545aab113ec70847785c81a1 Mon Sep 17 00:00:00 2001 From: arhimede Date: Fri, 4 Sep 2026 21:49:13 +0300 Subject: [PATCH] Raise documented MariaDB minimum to 11.4 LTS in v7 docs MariaDB byte-swaps UUID storage and only stopped for UUIDv6+ in 10.10; 11.4 is the oldest LTS series where every patch release stores the project's UUIDv7 ids natively. Adds 12.3 LTS, drops 10.7 and 10.11. Signed-off-by: arhimede --- .../v7/introduction/server-requirements.md | 60 +++++++++++++------ .../discovery-phase.md | 6 +- 2 files changed, 46 insertions(+), 20 deletions(-) diff --git a/docs/book/v7/introduction/server-requirements.md b/docs/book/v7/introduction/server-requirements.md index 48648af..118d1a2 100644 --- a/docs/book/v7/introduction/server-requirements.md +++ b/docs/book/v7/introduction/server-requirements.md @@ -2,7 +2,7 @@ ## Summary -What Dotkernel API v7 needs to run: a Linux host in production (Windows via WSL2 for development), Apache with `mod_rewrite` or an Nginx equivalent, PHP 8.3, 8.4 or 8.5 with the `gd`, `json` and `mbstring` extensions and CLI SAPI, Composer 2.0 or newer, and MariaDB or PostgreSQL — MySQL is not supported because it lacks native UUID types. +What Dotkernel API v7 needs to run: a Linux host in production (Windows via WSL2 for development), Apache with `mod_rewrite` or an Nginx equivalent, PHP 8.3, 8.4 or 8.5 with the `gd`, `json` and `mbstring` extensions and CLI SAPI, Composer 2.0 or newer, and MariaDB 11.4 LTS or newer or PostgreSQL 13 or newer — MySQL is not supported because it lacks native UUID types. Recommended extensions and baseline server hardening are listed as well. ## Details @@ -71,17 +71,6 @@ public const string DEFAULT_HEADERS = 'default'; The project will not even parse on PHP 8.2. -Beyond that, Dotkernel API leverages these modern PHP features: - -- Typed Class Constants (8.3): Constants carry a declared type -- Readonly Classes (8.2): Immutable value objects such as the deprecation attributes -- Enums (8.1): Roles and statuses are backed enums rather than class constants -- Attributes (8.0): Metadata for dependency injection and OpenAPI documentation -- Named Arguments (8.0): Clearer function calls, used when creating problem-details exceptions -- Match Expressions (8.0): More readable than switch statements -- Constructor Property Promotion (8.0): Cleaner code -- Union Types (8.0) and the Nullsafe Operator (8.0): Better type safety and safer null handling - ## Required Settings and Modules & Extensions These extensions are declared in the `require` section of `composer.json` as `ext-gd` and @@ -106,14 +95,48 @@ Also required: ### MariaDB +**MariaDB 11.4 LTS is the minimum supported version.** + Tested with: -- MariaDB 10.7 -- MariaDB 10.11 LTS (Long-Term Support) -- MariaDB 11.4 LTS +- MariaDB 11.4 LTS (Long-Term Support) - MariaDB 11.8 LTS +- MariaDB 12.3 LTS + +All three are LTS releases, which we recommend for stability and security updates. + +#### Why 11.4 is the minimum + +Dotkernel API stores every entity identifier in a MariaDB `UUID` column and generates the value as a +**UUIDv7** in PHP, via `Ramsey\Uuid\Uuid::uuid7()`. UUIDv7 is time-ordered by design, so sequential +inserts land next to each other in the index. + +MariaDB, however, does not always store a `UUID` in the order it was given. It rearranges the value +internally into an index-friendly layout that assumes a UUIDv1 — where the node comes first and the +timestamp second. Applied to a UUIDv7, that rearrangement scrambles exactly the ordering the type +was chosen for. + +MariaDB 10.10 changed this: from that release on, UUIDv6 and later are stored in their native order, +with no byte-swapping. The change did not reach the older maintenance series until 10.10.7 and +10.11.6, so "MariaDB 10.11" is only correct from 10.11.6 onward. + +11.4 LTS is therefore the earliest LTS series in which *every* patch release stores UUIDv7 natively, +which is why it is the published floor. + +> On MariaDB 10.7, or on 10.11.0 - 10.11.5, the application still runs: inserts and reads succeed. +> The identifiers are simply stored in scrambled order, so you lose the insert locality UUIDv7 exists +> to provide. It is a silent performance problem rather than an error, which is what makes it worth +> stating explicitly. + +For the background on why identifiers are generated as UUIDv7 in PHP rather than delegated to the +database, see +[Version 7 adds PostgreSQL, native UUID and PHP 8.5](https://www.dotkernel.com/headless-platform/version-7-adds-postgresql-native-uuid-and-php-8-5/). +Generating them in the application keeps full control over which UUID version is used and avoids +depending on a database extension or a particular server version to produce the value. -> It's recommended to use LTS versions for stability and security updates. +> That article cites MariaDB 10.7 as the minimum, which is the release that introduced the `UUID` +> data type. 11.4 is the floor documented here because of the byte-swapping behaviour described +> above, which 10.7 does not have fixed. ### PostgreSQL @@ -162,8 +185,9 @@ MariaDB and PostgreSQL both do. **Q: Which database versions are tested?** -A: MariaDB 10.7, 10.11 LTS, 11.4 LTS and 11.8 LTS, and PostgreSQL 13 and above. -LTS releases are recommended for stability and security updates. +A: MariaDB 11.4 LTS, 11.8 LTS and 12.3 LTS, and PostgreSQL 13 and above. +MariaDB 11.4 is also the minimum: earlier releases byte-swap `UUID` values and destroy the ordering +of the UUIDv7 identifiers this project uses. See "Why 11.4 is the minimum" above. **Q: What collation should I create the database with?** diff --git a/docs/book/v7/transition-from-api-tools/discovery-phase.md b/docs/book/v7/transition-from-api-tools/discovery-phase.md index 159664d..2c6740d 100644 --- a/docs/book/v7/transition-from-api-tools/discovery-phase.md +++ b/docs/book/v7/transition-from-api-tools/discovery-phase.md @@ -14,7 +14,8 @@ To transition a system built using api-tools to Dotkernel API, we need to analyz - which is the connection to a database - which library is used for database interaction (laminas-db, doctrine 2, eloquent, or else)? -> Dotkernel API version 7 is tested only with MariaDB version 10.7, 10.11 LTS, 11.4 LTS, 11.8 LTS, and PostgreSQL version 13 and above. +> Dotkernel API version 7 is tested only with MariaDB version 11.4 LTS, 11.8 LTS, 12.3 LTS, and PostgreSQL version 13 and above. +> MariaDB 11.4 is the minimum supported version — see [Server requirements](../introduction/server-requirements.md). ## Authentication and Authorization @@ -57,7 +58,8 @@ See [Doctrine ORM](../installation/doctrine-orm.md). **Q: Which database versions can I target?** -A: Dotkernel API version 7 is tested with MariaDB 10.7, 10.11 LTS, 11.4 LTS and 11.8 LTS, and with PostgreSQL 13 and above. +A: Dotkernel API version 7 is tested with MariaDB 11.4 LTS, 11.8 LTS and 12.3 LTS, and with PostgreSQL 13 and above. +MariaDB 11.4 is the minimum, because earlier releases byte-swap `UUID` values and lose the ordering of the UUIDv7 identifiers the project generates. See [Server requirements](../introduction/server-requirements.md). **Q: My api-tools API uses HTTP Basic authentication. What is the equivalent?**