feat(mariadb): adapt to derived DDL and rework version boundaries

.github/workflows/test.yml

@@ -38,6 +38,8 @@
           - { python-version: '3.14', mariadb-version: '11.8', health-cmd: 'mariadb-admin ping -h 127.0.0.1 -u root -ppassword' }
           - { python-version: '3.14t', mariadb-version: '12.0', health-cmd: 'mariadb-admin ping -h 127.0.0.1 -u root -ppassword' }
           - { python-version: '3.14t', mariadb-version: '12.2', health-cmd: 'mariadb-admin ping -h 127.0.0.1 -u root -ppassword' }
+          - { python-version: '3.14t', mariadb-version: '12.3', health-cmd: 'mariadb-admin ping -h 127.0.0.1 -u root -ppassword' }
+          - { python-version: '3.14t', mariadb-version: '13.0', health-cmd: 'mariadb-admin ping -h 127.0.0.1 -u root -ppassword' }
 
     services:
       mariadb:
@@ -71,7 +73,7 @@
       - name: Install activerecord and testsuite
         run: |
           pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
-          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/activerecord-derived-ddl"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
 
       - name: Create MariaDB scenario config
         run: |
@@ -123,7 +125,8 @@
       matrix:
         include:
           - { python-version: '3.15.0-rc.2', mariadb-version: '12.3', freethreaded: false }
-          - { python-version: '3.15.0-rc.2', mariadb-version: '13.0-rc', freethreaded: true }
+          - { python-version: '3.15.0-rc.2', mariadb-version: '13.0', freethreaded: true }
+          - { python-version: '3.14', mariadb-version: '13.1-rc', freethreaded: false }
 
     services:
       mariadb:
@@ -158,7 +161,7 @@
       - name: Install activerecord and testsuite
         run: |
           pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
-          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/activerecord-derived-ddl"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
 
       - name: Create MariaDB scenario config
         run: |
@@ -178,5 +181,5 @@
 
       - name: Run tests
         run: |
-          export PYTHONPATH=src
+          export PYTHONPATH=src:tests
           python -m pytest tests/ --ignore=tests/rhosocial/activerecord/backend/mariadb --tb=short

CLAUDE.md

@@ -27,3 +27,9 @@ This project is under active development. Key features implemented:
 ## Version Control and Changelog
 
 This project adheres to the same version control, branching, commit message, and changelog management standards as the main `python-activerecord` project.
+
+## Search Scope
+
+- Use `rg` for repository searches; never use `grep`.
+- Limit searches to this `python-activerecord` repository and its related testsuite/backend directories.
+- Exclude `.git/`, `.venv*/`, `__pycache__/`, `build/`, `dist/`, and other cache directories.

README.md

@@ -155,23 +155,111 @@ User.insert_or_update(
 
 ## MariaDB Version Compatibility
 
+Server versions this backend is tested against in CI: **10.2, 10.3, 10.4, 10.5,
+10.6, 10.11, 11.4, 11.7, 11.8, 12.0, 12.2, 12.3, 13.0** (gating) and
+**13.1-rc** (experimental, non-gating).
+
 | Feature | Min Version | Notes |
 |---------|-------------|-------|
 | Basic operations | 10.2+ | Core functionality |
-| JSON | 10.2+ | `JSON` alias for LONGTEXT, JSON functions |
+| CHECK constraints | 10.2.1+ | Enforced |
 | Window functions | 10.2+ | ROW_NUMBER, RANK, etc. |
-| CTEs | 10.2+ | WITH clauses |
+| CTEs | 10.2+ | WITH clauses, incl. recursive |
 | Full-text search | 10.2+ | MATCH ... AGAINST |
 | Generated columns | 10.2+ | Virtual/Stored columns |
-| CHECK constraints | 10.2+ | Enforced |
-| DEFAULT expressions | 10.2+ | Expression defaults |
-| System versioning | 10.3+ | Temporal tables |
-| Sequences | 10.3+ | `CREATE SEQUENCE` |
-| GROUPING SETS | 10.3+ | Advanced grouping |
-| INET6 type | 10.5+ | Native IPv6 |
-| SKIP LOCKED | 10.6+ | Row-level locking control |
-
-**Recommended**: MariaDB 10.6+ for optimal feature support.
+| Spatial types | 10.2+ | GEOMETRY, POINT, spatial index |
+| `ST_AsGeoJSON()` | 10.2.3+ | |
+| JSON | 10.2.3+ | `JSON` alias for LONGTEXT, JSON functions |
+| INTERSECT / EXCEPT | 10.3+ | Set operations |
+| Sequences | 10.3+ | `CREATE SEQUENCE`, `NEXT VALUE FOR` |
+| System versioning | 10.3+ | `WITH SYSTEM VERSIONING` |
+| Invisible columns | 10.3+ | |
+| SKIP LOCKED / NOWAIT | 10.3+ | Row-level locking control |
+| `TRUNCATE ... WAIT` | 10.3+ | |
+| Triggers (FOLLOWS/PRECEDES) | 10.2.3+ | |
+| INSTEAD OF triggers | 10.4+ | View triggers |
+| RETURNING (INSERT/DELETE/REPLACE) | 10.5+ | |
+| `RENAME TABLE ... WAIT` | 10.3+ | |
+| `EXPLAIN FORMAT=JSON` / `ANALYZE` | 10.6+ | |
+| `ANALYZE TABLE ... PERSISTENT` | 10.5+ | |
+| `JSON_TABLE` | 10.6+ | |
+| `IS JSON` predicate | 12.3+ | |
+| `TO_DATE()` | 12.3+ | |
+| `UPDATE ... RETURNING` | 13.0+ | Single-table UPDATE only; pairs with `OLD_VALUE()` |
+| `DENY ... ON ... TO ...` | 13.1+ | Negative grants |
+| Native `->` / `->>` | 13.1+ | JSON **column** operands only; see JSON note below |
+
+Not implemented: `QUALIFY`, ordered-set aggregates (`WITHIN GROUP`),
+`LATERAL VIEW`, `ROW()` composite types, `MBR*` functions, `SOUNDEX`,
+`PARTITION BY SYSTEM_TIME`, packages, domains, `SET PATH`,
+`SET SESSION AUTHORIZATION`, cursors on prepared statements, optimizer hints
+(`/*+ ... */`), the `VECTOR` type, and the `XML` type.
+
+### JSON arrow operators
+
+`->` and `->>` are always rendered as the equivalent
+`JSON_EXTRACT(...)` / `JSON_UNQUOTE(JSON_EXTRACT(...))` calls, which behave
+identically on every supported version. MariaDB 13.1 added a native
+`column -> path` form, but it applies **only to a real JSON column** —
+`CAST(x AS JSON) -> '$'` is a syntax error even on 13.1 — so it is not used as
+the general-purpose rendering. `supports_json_arrow_operators_native()` reports
+whether it is available.
+
+### The `utf8` character set alias
+
+`utf8` is a server-side **alias** whose meaning changed in MariaDB 13.1
+(MDEV-30041): it resolved to `utf8mb3` on every release up to 13.0, and
+resolves to `utf8mb4` from 13.1, because `old_mode` no longer sets
+`UTF8_IS_UTF8MB3` by default.
+
+```sql
+CREATE TABLE t (s VARCHAR(50)) CHARACTER SET utf8
+-- MariaDB <= 13.0  ->  utf8mb3_uca1400_ai_ci   (4-byte characters rejected)
+-- MariaDB >= 13.1  ->  utf8mb4_uca1400_ai_ci   (4-byte characters accepted)
+```
+
+This backend resolves the alias to **`utf8mb3`** — the meaning it always had
+before 13.1 — before emitting it, so one DDL statement produces one schema on
+every supported server. Ask for `utf8mb4` explicitly if you want 4-byte
+storage.
+
+Note this affects the DDL context only: `SET NAMES utf8` already resolved to
+`utf8mb4` on every version tested, including 12.2.
+
+### Reserved words
+
+Identifiers are quoted by default. The reserved-word check is
+version-aware, because MariaDB adds reserved words in otherwise-minor
+releases — `conversion` and `to_date` became reserved in **12.3**, and `deny`
+in **13.1**. An unquoted identifier matching a reserved word emits an
+`IdentifierQuotingWarning`; it is a warning, not an error, so passing
+`need_quote=False` remains possible at your own risk.
+
+## Supported Versions Policy
+
+| Line | Status | Rationale |
+|------|--------|-----------|
+| **12.3** | **Recommended baseline** | LTS, maintained to June 2029 |
+| 13.0 | Supported, opt-in | GA (rolling, non-LTS) |
+| 13.1 | Not recommended for production | Release candidate; `utf8` alias change and `mariadb-dump` behaviour change need independent validation |
+| 11.8 | Supported | Previous LTS |
+| 10.2 – 11.7 | Supported | Older lines, CI-covered |
+
+**On unrecognised newer versions.** There is no upper bound: the backend does
+not reject a version it has not seen. It behaves as follows.
+
+- Feature gates resolve to "enabled" when the server is newer than a
+  feature's introduction version, so **new syntax is assumed available**.
+  If that assumption is wrong the server rejects the statement.
+- Removals are handled explicitly, per feature. For example
+  `supports_function_name("des_encrypt")` returns `False` on 13.0+, where the
+  function was removed.
+- Behaviour changes that are *not* new syntax cannot be detected from the
+  version alone. The `utf8` alias is handled by resolving the alias to an
+  unambiguous spelling rather than by branching on version.
+
+When bumping to a new major, check that release's "Incompatible Changes"
+section before assuming compatibility.
 
 ## Get Started with AI Code Agents
 

changelog.d/5.added.md

@@ -0,0 +1 @@
+Consolidate MariaDB version knowledge into `MARIADB_VERSION_BOUNDARIES` as the single source, allow a function to be gated by a version that removed it rather than only by an addition, support `UPDATE ... RETURNING` on MariaDB 13.0+, rewrite the compatibility table with an explicit support policy, and extend CI to MariaDB 12.3, 13.0 and 13.1-rc.

changelog.d/5.changed.md

@@ -0,0 +1 @@
+Adapt the MariaDB backend to derived DDL with typed table and column options: `MariaDBColumnDefinition`, `MariaDBCreateTableOptions` with typed `AUTO_INCREMENT` / `ROW_FORMAT` / `SYSTEM VERSIONING`, native partition expressions, `MariaDBAlterTableExpression` with a typed `check` enforcement option, typed `RENAME TABLE` and maintenance options, and a version-aware charset/collation/storage-engine protocol. Add a type-domain negative contract plus coverage for `DDLSource` collection, table inheritance, tablespace and inline-index rendering.

changelog.d/5.fixed.md

@@ -0,0 +1 @@
+Correct the MariaDB version boundaries: fix the collation version windows, version-gate the reserved-word set, and resolve the `utf8` charset alias to an explicit spelling. Implement `JSON_TABLE`, supported since MariaDB 10.6, and reject `YEAR(2)`, which MariaDB 13.0 removed.

changelog.d/5.internal.md

@@ -0,0 +1 @@
+Install core and testsuite from release branches in CI instead of the derived-DDL feature branch, repair TYPE_CHECKING imports broken by the expression namespace split, register the pytest markers the suite already uses, and stop the pre-commit hook from blocking commits on revisions that predate `scripts/preflight.sh`.

changelog.d/5.removed.md

@@ -0,0 +1 @@
+Remove the reserved `dialect_options` bag from data-type value objects and from the admin, routine and rename-index expressions, the generated DDL references, the legacy identity fields on column classes, and the dead version plumbing.

pyproject.toml

@@ -100,6 +100,9 @@ markers = [
     "requires_protocol: marks tests requiring specific backend protocol support",
     "requires_inner_join: marks tests requiring INNER JOIN support",
     "mariadb_json: marks MariaDB-specific JSON tests",
+    "feature: category label for feature-area tests; changes collection grouping only, not ordering",
+    "benchmark_relation: marks relation benchmarks; changes collection grouping only, not ordering",
+
 ]
 
 [tool.coverage.run]

scripts/install-git-hooks.sh

@@ -4,21 +4,42 @@
 # Installs an optional pre-commit hook that runs scripts/preflight.sh so a
 # broken import/lint is caught before the commit (and before a CI round-trip).
 # Bypass a single commit with: git commit --no-verify
+#
+# Re-run this after pulling, and re-run it from the repository root. To remove
+# the hook, delete .git/hooks/pre-commit (or the core.hooksPath directory).
 set -euo pipefail
 
 cd "$(dirname "$0")/.."
 
-HOOK=".git/hooks/pre-commit"
-if [ ! -d .git/hooks ]; then
-  echo "install-git-hooks: .git/hooks not found (not a git repo?)" >&2
-  exit 2
+# git ignores .git/hooks entirely once core.hooksPath is set, so a hook written
+# there would never run while this script still reported success.
+HOOKS_PATH="$(git config core.hooksPath || true)"
+if [ -n "$HOOKS_PATH" ]; then
+  echo "install-git-hooks: core.hooksPath is set to '$HOOKS_PATH'." >&2
+  echo "install-git-hooks: .git/hooks is ignored by git; writing the hook to" >&2
+  echo "                 '$HOOKS_PATH/pre-commit' instead." >&2
+  HOOK="$HOOKS_PATH/pre-commit"
+  mkdir -p "$HOOKS_PATH"
+else
+  HOOK=".git/hooks/pre-commit"
+  if [ ! -d .git/hooks ]; then
+    echo "install-git-hooks: .git/hooks not found (not a git repo?)" >&2
+    exit 2
+  fi
 fi
 
 cat > "$HOOK" <<'HOOK_BODY'
 #!/usr/bin/env bash
 # Installed by scripts/install-git-hooks.sh — runs the local pre-flight.
 # Skip with: git commit --no-verify
-exec "$(git rev-parse --show-toplevel)/scripts/preflight.sh"
+#
+# The guard below matters on older revisions: this hook is a local, untracked
+# artifact, so it survives a checkout of a commit that predates
+# scripts/preflight.sh. Without the guard, exec fails with a bare
+# "No such file or directory" and blocks the commit with nothing to act on.
+PREFLIGHT="$(git rev-parse --show-toplevel)/scripts/preflight.sh"
+[ -x "$PREFLIGHT" ] || exit 0
+exec "$PREFLIGHT"
 HOOK_BODY
 chmod +x "$HOOK"
 

src/rhosocial/activerecord/backend/impl/mariadb/__init__.py

@@ -21,7 +21,11 @@
 from .transaction import MariaDBTransactionManager, MariaDBTransactionMixin
 from .async_transaction import AsyncMariaDBTransactionManager
 from .config import MariaDBConnectionConfig
-from .collation import MariaDBCollation
+from .mixins.charset_collation import (
+    MariaDBCharset,
+    MariaDBCollation,
+    MariaDBStorageEngine,
+)
 from .types import MariaDBEnumType, MariaDBSetType
 from .explain import MariaDBExplainResult, MariaDBExplainRow, MariaDBExplainJsonResult, MariaDBExplainAnalyzeResult
 
@@ -130,6 +134,8 @@
     'MariaDBDialect',
     'MARIADB_VERSION_BOUNDARIES',
     'MariaDBCollation',
+    'MariaDBCharset',
+    'MariaDBStorageEngine',
 
     # Transaction - Sync and Async
     'MariaDBTransactionManager',

src/rhosocial/activerecord/backend/impl/mariadb/adapters.py

@@ -251,13 +251,13 @@ class MariaDBDatetimeAdapter(SQLTypeAdapter):
     """
 
     def __init__(self, mariadb_version: Optional[Tuple[int, int, int]] = None):
-        """Initialize adapter with MariaDB version info.
+        """Initialize the adapter.
 
         Args:
-            mariadb_version: MariaDB server version tuple (major, minor, patch).
-                             If None, defaults to (10, 5, 0).
+            mariadb_version: Accepted for call-site compatibility. Behaviour
+                does not currently vary by server version, so the value is
+                not retained.
         """
-        self._mariadb_version = mariadb_version or (10, 5, 0)
 
     @property
     def supported_types(self) -> Dict[Type, List[Any]]:

src/rhosocial/activerecord/backend/impl/mariadb/async_backend.py

@@ -239,10 +239,8 @@ async def get_server_version(self) -> tuple:
             version_row = await cursor.fetchone()
             version_str = version_row[0] if version_row else "10.5.0"
 
-            if '-MariaDB' in version_str:
-                version_clean = version_str.split('-')[0]
-            else:
-                version_clean = version_str.split('-')[0]
+            # Strip the vendor suffix: "13.1.1-MariaDB-ubu2604" -> "13.1.1".
+            version_clean = version_str.split('-')[0]
 
             version_parts = version_clean.split('.')