feat(mysql): MySQL and MariaDB query dialect, fuzzed on both (#53)

.changeset/mysql-dialect.md

@@ -0,0 +1,14 @@
+---
+"@maple-dev/effect-orm": minor
+---
+
+A new `/mysql` entry compiles the shared query builder for MySQL 8.0.17+ (`mysqlDialect`) and MariaDB 10.6+ (`mariadbDialect`), for `@effect/sql-mysql2` (#53). It writes backtick identifiers and positional `?` bindings (up to 65,535 per statement), escapes `\` in string literals, and writes `OFFSET` without `LIMIT` with MySQL's largest row count. It has MySQL column types and codecs for what mysql2 sends (`text`, `longtext`, `varchar(n)`, the integer types, `bigint` within 2^53, `double`, `decimal(p, s)` as exact text, `boolean`, `datetime` as `DATETIME(3)` in UTC, `date`, `blob`, `varbinary(n)`, `json(schema)`) and MySQL functions (`count`, `countDistinct`, `countIf`, `sum`, `avg`, `min`, `max`, `lower`, `upper`, `length`, `coalesce`), refused for another dialect in the type. `forUpdate` and `forShare` compile for MySQL, with MariaDB's `LOCK IN SHARE MODE`; the type refuses `forNoKeyUpdate` and `forKeyShare` there. RETURNING, ON CONFLICT, DISTINCT ON and ILIKE are refused at compile time. A transaction's isolation level and access mode go in the statement that starts it (`SET TRANSACTION …; START TRANSACTION READ ONLY`). `contains`, `startsWith` and `endsWith` compare bytes, so they stay case-sensitive under a case-insensitive collation. A JSON column is compared with `CAST(? AS JSON)` on MySQL. A selected small integer or numeric param is cast, as MySQL 8.4 can read it as an ORDER BY position inside a derived table. The fuzzer runs every property on MySQL 8.4 and MariaDB 11.4, over prepared statements and the text protocol Cloudflare Hyperdrive uses; see docs/mysql.md for what MySQL does differently.
+
+Breaking, for a custom `Dialect`:
+
+- `clauses.offsetRequiresLimit: true` is now `clauses.limitForOffset: "-1"`: the LIMIT to write, which MySQL needs to be its largest row count.
+- `clauses.locking` is a `LockingSupport` (`{ strengths, of, shareSyntax? }`), not `true`: Postgres's is every strength with `of`.
+- `likeIgnoresCase: true` is now `likeCase: "ascii-insensitive"`, beside `"sensitive"` (the default) and MySQL's `"collation"`.
+- `integerComparesFraction: true` is now `fractionComparableIntegers`, the integer column types that compare with a fraction (SQLite's is `["integer"]`).
+
+New optional `Dialect` fields: `castType` (the CAST target for a selected param's column type), `concat`, `comparisonCast` and `clauses.selectedNumberCast`. `MysqlOnly` and `LockingSupport` are exported from every dialect entry.

.github/workflows/ci.yml

@@ -43,3 +43,49 @@ jobs:
                   EFFECT_ORM_CLICKHOUSE_USER: maple
                   EFFECT_ORM_CLICKHOUSE_PASSWORD: maple
               run: bun run test:release
+
+    mysql:
+        name: Builder / MySQL 8.4, MariaDB 11.4
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+        services:
+            mysql:
+                image: mysql:8.4
+                env:
+                    MYSQL_ROOT_PASSWORD: maple
+                    MYSQL_DATABASE: maple
+                    MYSQL_USER: maple
+                    MYSQL_PASSWORD: maple
+                ports:
+                    - 3306:3306
+                options: >-
+                    --health-cmd "mysqladmin ping -h 127.0.0.1 -umaple -pmaple"
+                    --health-interval 5s
+                    --health-timeout 5s
+                    --health-retries 30
+            mariadb:
+                image: mariadb:11.4
+                env:
+                    MARIADB_ROOT_PASSWORD: maple
+                    MARIADB_DATABASE: maple
+                    MARIADB_USER: maple
+                    MARIADB_PASSWORD: maple
+                ports:
+                    - 3307:3306
+                options: >-
+                    --health-cmd "healthcheck.sh --connect --innodb_initialized"
+                    --health-interval 5s
+                    --health-timeout 5s
+                    --health-retries 30
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
+              with:
+                  persist-credentials: false
+            - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
+            - run: bun install --frozen-lockfile
+            - run: bun run build
+            - name: Live MySQL and MariaDB tests and fuzz properties
+              env:
+                  EFFECT_ORM_MYSQL_URL: mysql://maple:maple@127.0.0.1:3306/maple
+                  EFFECT_ORM_MARIADB_URL: mysql://maple:maple@127.0.0.1:3307/maple
+              run: bunx vitest run src/mysql tests/core.mysql.test.ts tests/fuzz -t "mysql|mariadb"

.github/workflows/fuzz.yml

@@ -53,3 +53,50 @@ jobs:
                   FUZZ_SCALE: ${{ inputs.scale || '20' }}
                   FUZZ_VERBOSE: "1"
               run: bun run fuzz
+
+    soak-mysql:
+        name: Soak / MySQL 8.4, MariaDB 11.4
+        runs-on: ubuntu-latest
+        timeout-minutes: 60
+        services:
+            mysql:
+                image: mysql:8.4
+                env:
+                    MYSQL_ROOT_PASSWORD: maple
+                    MYSQL_DATABASE: maple
+                    MYSQL_USER: maple
+                    MYSQL_PASSWORD: maple
+                ports:
+                    - 3306:3306
+                options: >-
+                    --health-cmd "mysqladmin ping -h 127.0.0.1 -umaple -pmaple"
+                    --health-interval 5s
+                    --health-timeout 5s
+                    --health-retries 30
+            mariadb:
+                image: mariadb:11.4
+                env:
+                    MARIADB_ROOT_PASSWORD: maple
+                    MARIADB_DATABASE: maple
+                    MARIADB_USER: maple
+                    MARIADB_PASSWORD: maple
+                ports:
+                    - 3307:3306
+                options: >-
+                    --health-cmd "healthcheck.sh --connect --innodb_initialized"
+                    --health-interval 5s
+                    --health-timeout 5s
+                    --health-retries 30
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
+              with:
+                  persist-credentials: false
+            - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
+            - run: bun install --frozen-lockfile
+            - name: Fuzz the MySQL and MariaDB targets
+              env:
+                  EFFECT_ORM_MYSQL_URL: mysql://maple:maple@127.0.0.1:3306/maple
+                  EFFECT_ORM_MARIADB_URL: mysql://maple:maple@127.0.0.1:3307/maple
+                  FUZZ_SCALE: ${{ inputs.scale || '20' }}
+                  FUZZ_VERBOSE: "1"
+              run: bun run fuzz -t "mysql|mariadb"

.github/workflows/release.yml

@@ -33,6 +33,34 @@ jobs:
                     --health-interval 5s
                     --health-timeout 5s
                     --health-retries 20
+            mysql:
+                image: mysql:8.4
+                env:
+                    MYSQL_ROOT_PASSWORD: maple
+                    MYSQL_DATABASE: maple
+                    MYSQL_USER: maple
+                    MYSQL_PASSWORD: maple
+                ports:
+                    - 3306:3306
+                options: >-
+                    --health-cmd "mysqladmin ping -h 127.0.0.1 -umaple -pmaple"
+                    --health-interval 5s
+                    --health-timeout 5s
+                    --health-retries 30
+            mariadb:
+                image: mariadb:11.4
+                env:
+                    MARIADB_ROOT_PASSWORD: maple
+                    MARIADB_DATABASE: maple
+                    MARIADB_USER: maple
+                    MARIADB_PASSWORD: maple
+                ports:
+                    - 3307:3306
+                options: >-
+                    --health-cmd "healthcheck.sh --connect --innodb_initialized"
+                    --health-interval 5s
+                    --health-timeout 5s
+                    --health-retries 30
         steps:
             - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
             - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
@@ -52,3 +80,5 @@ jobs:
                   EFFECT_ORM_CLICKHOUSE_URL: http://127.0.0.1:8123
                   EFFECT_ORM_CLICKHOUSE_USER: maple
                   EFFECT_ORM_CLICKHOUSE_PASSWORD: maple
+                  EFFECT_ORM_MYSQL_URL: mysql://maple:maple@127.0.0.1:3306/maple
+                  EFFECT_ORM_MARIADB_URL: mysql://maple:maple@127.0.0.1:3307/maple

README.md

@@ -4,13 +4,16 @@
 > **Alpha.** The API is still changing and minor releases may break it. Pin an exact version,
 > read the [changelog](./CHANGELOG.md) before upgrading, and expect rough edges.
 
-Type-safe ClickHouse, Postgres and SQLite queries, result decoding, and reproducible benchmarks for Effect and TypeScript.
+Type-safe ClickHouse, Postgres, SQLite and MySQL queries, result decoding, and reproducible benchmarks for Effect and TypeScript.
 
 Formerly `@maple-dev/effect-clickhouse`.
 
 SQLite and Cloudflare D1 use the same builder and row decoder through the new
 [`/sqlite` entry](./docs/sqlite.md), which also writes SQLite table DDL. `effect-orm generate` writes SQLite migrations; effect-orm does not apply them yet.
 
+MySQL 8 and MariaDB 10.6+ use it through the [`/mysql` entry](./docs/mysql.md), with
+`@effect/sql-mysql2`, fuzzed on MySQL 8.4 and MariaDB 11.4.
+
 [Read the documentation](https://effect-clickhouse.maple.dev) ·
 [Getting started](./docs/getting-started.md) · [Recipes](./docs/recipes.md) · [Coming from Drizzle or Prisma](./docs/coming-from-drizzle-prisma.md)
 

docs/README.md

@@ -108,6 +108,10 @@ The optional `@maple-dev/effect-orm/benchmark` entry point and bundled
 See [Benchmarking](./benchmarking.md) and the
 [agent playbook](./benchmark-agent.md). The SQL builders remain driver-free.
 
+## MySQL and MariaDB
+
+[MySQL and MariaDB](./mysql.md) covers `@maple-dev/effect-orm/mysql`: its codecs and functions, `@effect/sql-mysql2` wiring (including Cloudflare Hyperdrive's text protocol), collations and what MySQL does differently. Tables are query schemas only for now.
+
 ## SQLite and D1
 
 [SQLite and D1](./sqlite.md) covers `@maple-dev/effect-orm/sqlite`, its codecs and functions, table DDL, Effect SQL drivers, tenant checks and transaction limits. `effect-orm generate` writes SQLite migrations; effect-orm does not apply them yet.