feat(mysql)!: the statement layer, typed literals, and one introspect question per family

.github/workflows/test.yml

@@ -58,7 +58,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@release/v1.0.0.dev17"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@fix/column-constraint-gates"
 
       - name: Create and test database
         run: |
@@ -253,7 +253,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@release/v1.0.0.dev17"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@fix/column-constraint-gates"
 
       - name: Create and test database
         run: |
@@ -360,7 +360,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@release/v1.0.0.dev17"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@fix/column-constraint-gates"
 
       - name: Create and test database
         run: |

.gitignore

@@ -212,4 +212,9 @@ tests/config/mysql_scenarios.yml
 # Claude Code temporary files (local only)
 .claude/tmp/
 .claude/plans/
-.claude/plan/
+.claude/plan/
+# Worktrees for feature/* and fix/* branches. Never tracked: a `git add -A`
+# from the repo root would commit each branch's whole toolchain -- the venv, the
+# build directory and the test artifacts -- and the directory disappears when the
+# branch merges, so the history would keep a second copy of the source tree.
+.worktree/

README.md

@@ -41,11 +41,11 @@ from typing import ClassVar, Optional
 from rhosocial.activerecord.base import FieldProxy
 from rhosocial.activerecord.backend.impl.mysql.backend import MySQLBackend
 from rhosocial.activerecord.backend.impl.mysql.config import MySQLConnectionConfig
-from rhosocial.activerecord.backend.expression import CreateTableExpression
+from rhosocial.activerecord.backend.expression import CreateTableStatement
 from rhosocial.activerecord.backend.expression.statements import (
     ColumnConstraint,
-    ColumnConstraintType,
     ColumnDefinition,
+    ColumnPrimaryKeyConstraint,
 )
 from rhosocial.activerecord.backend.expression.types import IntegerType, VarCharType
 from rhosocial.activerecord.model import ActiveRecord
@@ -77,7 +77,7 @@ User.configure(
 # DDL is expressed, not stringified. Note that every node takes the dialect as
 # its first argument, and column types are DataType instances, not strings.
 dialect = User.__backend__.dialect
-create_users = CreateTableExpression(
+create_users = CreateTableStatement(
     dialect,
     "users",
     columns=[
@@ -86,8 +86,7 @@ create_users = CreateTableExpression(
             constraints=[
                 ColumnConstraint(
                     dialect,
-                    ColumnConstraintType.PRIMARY_KEY,
-                    is_auto_increment=True,
+                    branch=ColumnPrimaryKeyConstraint(dialect, is_auto_increment=True),
                 )
             ],
         ),

changelog.d/62.added.md

@@ -0,0 +1 @@
+The introspect CLI offers one type per catalogue question and derives the list from `_TYPE_CAPABILITIES`, so a family cannot be listed without a dialect switch behind it; `views NAME` answers for one view. Typed value nodes with MySQL's own literal spellings, and `SHOW` rendered through its own expressions.

changelog.d/62.changed.md

@@ -0,0 +1 @@
+Every catalogue question is a statement class plus a dialect `format_*_query_statement`, and the `SHOW` parameters are stored under their declared names. A `NAME` the type cannot use is refused with exit 2 instead of being ignored, and a missing required name exits 1.

changelog.d/62.fixed.md

@@ -0,0 +1 @@
+`introspect database` no longer crashes on a fresh session (the parser read a private version that no adaptation had set), the introspect command adapts after connecting, a non-boolean `unsigned` is refused where the type is rendered, and `LIKE` takes its operator enum rather than the SQL keyword.

changelog.d/62.internal.md

@@ -0,0 +1 @@
+The expression round-trip harness is vendored beside the matrix rather than imported from the test suite, the expression area runs in parallel, and CI installs core from `release/v1.0.0.dev30` now that core #127 has merged. The test suite stays on its own branch reference until that branch merges.

docs/en_US/ddl/README.md

@@ -6,14 +6,14 @@ The MySQL backend supports the same type-safe DDL expressions as the core librar
 
 | Operation | MySQL Support | Notes |
 |----------|--------------|-------|
-| `CreateTableExpression` | ✅ Full | PRIMARY KEY, NOT NULL, UNIQUE, etc. |
-| `DropTableExpression` | ✅ Full | IF EXISTS support |
-| `AlterTableExpression` | ✅ Full | ADD/DROP COLUMN |
-| `CreateIndexExpression` | ✅ Full | Index types (BTREE, HASH) |
-| `DropIndexExpression` | ✅ Full | |
-| `CreateViewExpression` | ✅ Full | MySQL ALGORITHM options |
-| `DropViewExpression` | ✅ Full | |
-| `CreateTableExpression` | ✅ Full | Partition support (RANGE, LIST, HASH, KEY) |
+| `CreateTableStatement` | ✅ Full | PRIMARY KEY, NOT NULL, UNIQUE, etc. |
+| `DropTableStatement` | ✅ Full | IF EXISTS support |
+| `AlterTableStatement` | ✅ Full | ADD/DROP COLUMN |
+| `CreateIndexStatement` | ✅ Full | Index types (BTREE, HASH) |
+| `DropIndexStatement` | ✅ Full | |
+| `CreateViewStatement` | ✅ Full | MySQL ALGORITHM options |
+| `DropViewStatement` | ✅ Full | |
+| `CreateTableStatement` | ✅ Full | Partition support (RANGE, LIST, HASH, KEY) |
 | `PartitionByRange` | ✅ Full | RANGE and RANGE COLUMNS partitioning |
 | `PartitionByList` | ✅ Full | LIST and LIST COLUMNS partitioning |
 | `PartitionByHash` | ✅ Full | HASH and LINEAR HASH partitioning |
@@ -39,7 +39,7 @@ partition = MySQLPartitionByRange(
     ],
 )
 
-create_table = CreateTableExpression(
+create_table = CreateTableStatement(
     dialect,
     table_name="orders",
     columns=[...],
@@ -54,7 +54,7 @@ MySQL views support ALGORITHM to control execution:
 ```python
 from rhosocial.activerecord.backend.expression import ViewOptions, ViewAlgorithm
 
-create_view = CreateViewExpression(
+create_view = CreateViewStatement(
     dialect,
     view_name="optimized_view",
     query=query,
@@ -67,7 +67,7 @@ create_view = CreateViewExpression(
 MySQL supports specifying storage engine:
 
 ```python
-create_table = CreateTableExpression(
+create_table = CreateTableStatement(
     dialect,
     table_name="users",
     columns=columns,

docs/en_US/mysql_specific_features/dialect.md

@@ -11,11 +11,11 @@ MySQL has some specific SQL syntax and functions. This section covers commonly u
 MySQL supports copying table structure using the `LIKE` clause. This is useful for creating table backups or test tables with identical structure.
 
 ```python
-from rhosocial.activerecord.backend.expression import CreateTableExpression
+from rhosocial.activerecord.backend.expression import CreateTableStatement
 from rhosocial.activerecord.backend.impl.mysql.dialect import MySQLDialect
 
 # Basic usage - copy table structure
-create_expr = CreateTableExpression(
+create_expr = CreateTableStatement(
     dialect=MySQLDialect(),
     table_name="users_copy",
     columns=[],
@@ -24,7 +24,7 @@ create_expr = CreateTableExpression(
 # Generates: CREATE TABLE `users_copy` LIKE `users`
 
 # With schema-qualified source table
-create_expr = CreateTableExpression(
+create_expr = CreateTableStatement(
     dialect=MySQLDialect(),
     table_name="users_copy",
     columns=[],
@@ -33,7 +33,7 @@ create_expr = CreateTableExpression(
 # Generates: CREATE TABLE `users_copy` LIKE `production`.`users`
 
 # With TEMPORARY and IF NOT EXISTS
-create_expr = CreateTableExpression(
+create_expr = CreateTableStatement(
     dialect=MySQLDialect(),
     table_name="temp_users",
     columns=[],
@@ -59,16 +59,16 @@ from rhosocial.activerecord.backend.expression.functions.datetime import (
     current_timestamp, now,
 )
 from rhosocial.activerecord.backend.expression.statements import (
-    ColumnDefinition, ColumnConstraint, ColumnConstraintType,
+    ColumnDefinition, ColumnConstraint, ColumnDefaultConstraint,
 )
 
 # Correct: Use factory functions for SQL:2003 niladic functions
 ColumnDefinition(
     name='created_at',
     data_type='TIMESTAMP',
     constraints=[
-        ColumnConstraint(ColumnConstraintType.DEFAULT,
-                         default_value=current_timestamp(dialect)),
+        ColumnConstraint(dialect,
+                         branch=ColumnDefaultConstraint(dialect, current_timestamp(dialect))),
         # Generates: `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP
         # (no parentheses — SQL:2003 niladic form)
     ],
@@ -79,8 +79,8 @@ ColumnDefinition(
     name='updated_at',
     data_type='DATETIME',
     constraints=[
-        ColumnConstraint(ColumnConstraintType.DEFAULT,
-                         default_value=now(dialect)),
+        ColumnConstraint(dialect,
+                         branch=ColumnDefaultConstraint(dialect, now(dialect))),
         # Generates: `updated_at` DATETIME DEFAULT NOW()
     ],
 )
@@ -90,7 +90,7 @@ ColumnDefinition(
     name='is_active',
     data_type='TINYINT(1)',
     constraints=[
-        ColumnConstraint(ColumnConstraintType.DEFAULT, default_value=1),
+        ColumnConstraint(dialect, branch=ColumnDefaultConstraint(dialect, 1)),
         # Generates: `is_active` TINYINT(1) DEFAULT 1
     ],
 )
@@ -100,7 +100,7 @@ ColumnDefinition(
     name='status',
     data_type='VARCHAR(20)',
     constraints=[
-        ColumnConstraint(ColumnConstraintType.DEFAULT, default_value='active'),
+        ColumnConstraint(dialect, branch=ColumnDefaultConstraint(dialect, 'active')),
         # Generates: `status` VARCHAR(20) DEFAULT 'active'
     ],
 )
@@ -111,7 +111,7 @@ ColumnDefinition(
 ```python
 # WRONG: Passing SQL keywords as Python strings
 # This would generate DEFAULT 'CURRENT_TIMESTAMP' (quoted, treated as string literal)
-ColumnConstraint(ColumnConstraintType.DEFAULT, default_value='CURRENT_TIMESTAMP')
+ColumnConstraint(dialect, branch=ColumnDefaultConstraint(dialect, 'CURRENT_TIMESTAMP'))
 ```
 
 **Common statement-level constants reference:**
@@ -176,32 +176,32 @@ class GroupConcat(FunctionExpression):
 
 ## Querying Runtime Functions and Constants
 
-MySQL supports querying runtime functions without a data source, such as `SELECT CURRENT_TIMESTAMP`, `SELECT NOW()`, `SELECT VERSION()`. Use `QueryExpression` without specifying `from_` to achieve this.
+MySQL supports querying runtime functions without a data source, such as `SELECT CURRENT_TIMESTAMP`, `SELECT NOW()`, `SELECT VERSION()`. Use `QueryStatement` without specifying `from_` to achieve this.
 
 ```python
-from rhosocial.activerecord.backend.expression import QueryExpression
+from rhosocial.activerecord.backend.expression import QueryStatement
 from rhosocial.activerecord.backend.expression.core import FunctionCall, Literal
 from rhosocial.activerecord.backend.expression.functions.datetime import (
     current_timestamp, now, current_date, current_time,
 )
 
 # SELECT CURRENT_TIMESTAMP (niladic — no parentheses)
-query = QueryExpression(
+query = QueryStatement(
     dialect=dialect,
     select=[current_timestamp(dialect)],
 )
 sql, params = query.to_sql()
 # Generates: SELECT CURRENT_TIMESTAMP
 
 # SELECT NOW()
-query = QueryExpression(
+query = QueryStatement(
     dialect=dialect,
     select=[now(dialect)],
 )
 # Generates: SELECT NOW()
 
 # SELECT CURRENT_DATE, CURRENT_TIME (niladic — no parentheses)
-query = QueryExpression(
+query = QueryStatement(
     dialect=dialect,
     select=[
         current_date(dialect),
@@ -211,7 +211,7 @@ query = QueryExpression(
 # Generates: SELECT CURRENT_DATE, CURRENT_TIME
 
 # Multi-function query with aliases
-query = QueryExpression(
+query = QueryStatement(
     dialect=dialect,
     select=[
         now(dialect).as_('current_time'),
@@ -222,7 +222,7 @@ query = QueryExpression(
 # Generates: SELECT NOW() AS `current_time`, DATABASE() AS `db_name`, VERSION() AS `db_version`
 
 # Function calls with arguments
-query = QueryExpression(
+query = QueryStatement(
     dialect=dialect,
     select=[
         FunctionCall(dialect, 'DATE_FORMAT',

docs/en_US/mysql_specific_features/introspection.md

@@ -457,8 +457,8 @@ Supports configuration via command-line arguments or environment variables:
 ### Querying Table Details
 
 ```bash
-# Get complete table info (columns, indexes, foreign keys)
-python -m rhosocial.activerecord.backend.impl.mysql introspect table users \
+# Describe one view
+python -m rhosocial.activerecord.backend.impl.mysql introspect views users_v \
   --database mydb --user root
 
 # Query only column information
@@ -484,16 +484,19 @@ python -m rhosocial.activerecord.backend.impl.mysql introspect triggers users \
 
 ### Introspection Types
 
-| Type | Description | Table Name Required |
-|------|-------------|---------------------|
-| `tables` | List all tables | No |
-| `views` | List all views | No |
-| `database` | Database information | No |
-| `table` | Complete table details (columns, indexes, foreign keys) | Yes |
-| `columns` | Column information | Yes |
-| `indexes` | Index information | Yes |
-| `foreign-keys` | Foreign key information | Yes |
-| `triggers` | Trigger information | Optional |
+| Type | Description | Name |
+|------|-------------|------|
+| `tables` | List all tables | not accepted |
+| `views` | List all views, or describe one | optional (view) |
+| `database` | Database information | not accepted |
+| `columns` | Column information | required (table) |
+| `indexes` | Index information | required (table) |
+| `foreign-keys` | Foreign key information | required (table) |
+| `triggers` | Trigger information | optional (table) |
+| `table-options` | Engine, row format, collation and byte sizes of one table | optional (table) |
+| `partitions` | One table's partitions | required (table) |
+
+A name the type cannot use is refused (exit 2) rather than ignored.
 
 ### Output Formats