neoorm 0.8.1 → 0.8.2

package/docs/elysia.md

@@ -0,0 +1,131 @@
+# Elysia schemas
+
+`neoorm generate` can print Select, Create, and Update **scalar** Elysia `t` schemas next to the typed client. Codegen maps your schema to a validator-neutral IR first; this printer emits `import { t } from "elysia"` so the objects drop into route `body:` / `query:` the same way as hand-written `t.Object({ title: t.String() })`.
+
+Generated schemas match the TypeScript shapes of row / insert / update scalars — not nested relation writes (`connect`, `create`, `set`). Those stay TypeScript-only.
+
+This is the printer to use with **Elysia 1.x**. [TypeBox 1.x](typebox.md) (`import Type from "typebox"`) is a different package and will not type-check as Elysia `body:`.
+
+## Enable
+
+Install Elysia in the app, then opt in:
+
+```bash
+bun add elysia
+```
+
+```ts
+// neoorm.config.ts
+import { defineConfig } from "neoorm";
+
+export default defineConfig({
+  schema: "./schema.ts",
+  out: "./neoorm",
+  datasource: {
+    provider: "postgresql",
+    url: process.env.DATABASE_URL!,
+  },
+  generate: {
+    elysia: true,
+  },
+});
+```
+
+Re-run `neoorm generate` (or `neoorm migrate dev`). Output:
+
+- `out/elysia.ts` — generated schemas
+- `out/client.ts` re-exports them
+
+Disable `generate.elysia` and generate again to remove `elysia.ts`.
+
+`elysia` is an optional peer of NeoOrm. The generated file imports `elysia` directly; NeoOrm does not bundle it. If `generate.elysia` is on and `elysia` is not installed, `neoorm generate` still writes `elysia.ts` and prints a warning (`bun add elysia`).
+
+When Zod or TypeBox 1.x is also enabled, `client.ts` keeps those as documented and re-exports Elysia as `export * as elysia from "./elysia.js"` so names do not collide. Import from `./elysia.js` (or `elysia.UserCreateSchema`) in that case.
+
+## Usage
+
+```ts
+import { Elysia } from "elysia";
+import { db, UserCreateSchema, UserUpdateSchema } from "./neoorm/client.js";
+
+new Elysia()
+  .post("/users", ({ body }) => db.users.create({ data: body }), {
+    body: UserCreateSchema,
+  })
+  .patch("/users/:id", ({ params, body }) =>
+    db.users.update({
+      where: { id: params.id },
+      data: body,
+    }), {
+      body: UserUpdateSchema,
+    },
+  )
+  .listen(3000);
+```
+
+Elysia validates `body` against the `t.Object` schema. `t.Date()` accepts ISO-8601 strings, `Date` values, and epoch numbers, and decodes to `Date`.
+
+Per table (accessor `users` → model `User`):
+
+| Export | Shape |
+|--------|--------|
+| `UserSchema` / `UserSelect` | Select row (default query output: no `.hidden()`, includes `timestamps()`) |
+| `UserCreateSchema` / `UserCreate` | Insert scalars (no primary / serial / `timestamps()`; defaults optional; includes `.hidden()`) |
+| `UserUpdateSchema` / `UserUpdate` | Update scalars (no primary / `timestamps()`; all optional; includes `.hidden()`) |
+
+`UserSelect` / `UserCreate` / `UserUpdate` are `typeof Schema.static` aliases. They are named that way so they do not collide with the model type `User` from `models.ts`. Hoisted enums also get a type (`PostStatus` from `PostStatusSchema`).
+
+`schemas.users.select` / `.create` / `.update` are the same objects.
+
+`.hidden()` columns (for example `password`) are omitted from select schemas so they match default query results. They stay on create and update so login/register and password-change payloads can still be parsed. Use `includeHidden: true` on the query when the app needs those fields internally.
+
+`createdAt` and `updatedAt` from `timestamps()` (and any `timestamp().defaultNow()` / `.updatedAt()` column) are ORM-managed. They appear on select schemas only — create and update parsers reject them so API clients cannot stamp those fields. A plain `timestamp()` without `defaultNow` stays on create/update.
+
+Create with `author: { connect: { id } }` is not in `PostCreateSchema`. Pass the FK scalar (`authorId`) or keep nested writes in TypeScript.
+
+## Junction (M2M) tables
+
+Many-to-many through tables (auto `posts_tags` from `tags: many("tags")`, or an explicit `through` table) are not ordinary entities. Both FK columns are usually the composite primary key, so a naive Create/Update export would be `t.Object({})`.
+
+Codegen treats them as **link** tables:
+
+| Export | Shape |
+|--------|--------|
+| `{Model}Schema` / `{Model}Select` | Junction row (both FK ids, plus extras like `priority`) |
+| `{Model}LinkCreateSchema` / `{Model}LinkCreate` | Both FK ids required; extra create-allowed columns |
+| `{Model}CreateSchema` / `{Model}Create` | Alias of `LinkCreateSchema` |
+| `{Model}UpdateSchema` | Extra scalar columns only. **Omitted** when the junction has no updatable fields |
+
+Generated comments point at nested writes on the parent (`db.posts.update({ data: { tags: { connect: [{ id }] } } })`). Direct `db.posts_tags.create` is rarely needed. `schemas.posts_tags` has `select` and `create`; `update` is present only when the through table has extra columns.
+
+Prefer validating parent payloads in TypeScript (`tags: { connect, set, … }`). Junction Elysia schemas are for the rare case you insert a link row yourself.
+
+## Types and constraints
+
+`t.BigInt()` and `Buffer` still match generated models, not JSON. Wrap those fields if the payload is a JSON number/string.
+
+Typed schema helpers map into Elysia `t`:
+
+| Schema | Elysia |
+|--------|--------|
+| `.minLength()` / `.maxLength()` / `.notEmpty()` | `t.String({ minLength, maxLength })` |
+| `email` / `*Email` column names, or `.email()` on `text` / `citext` | `t.String({ format: "email" })` |
+| `url` / `*Url` column names, or `.url()` on `text` / `citext` | `t.String({ format: "uri" })` |
+| `.min()` / `.max()` / `.positive()` on int/serial | `t.Integer({ minimum, maximum, exclusiveMinimum: 0 })` |
+| same helpers on `bigint` | `t.BigInt({ minimum, maximum, exclusiveMinimum: 0n })` |
+| same helpers on `decimal()` | `t.Transform(t.String()).Decode(...)` |
+| `enumType([...])` | hoisted `t.UnionEnum` |
+| `json()` / `jsonb()` with no type arg | `t.Record(t.String(), t.Unknown())` |
+| `jsonb<Record<string, unknown>>()` | `t.Record(t.String(), t.Unknown())` |
+| `jsonb<{ featured: boolean }>()` (inline object type) | `t.Object({ featured: t.Boolean(), … })` |
+| `json()` / `jsonb()` with `.schema()` validation IR | same as IR (`t.Object`, nested `t.Record`, …); wins over generics |
+| `timestamp()` | `t.Date()` (ISO string / Date / epoch → `Date`) |
+| `bytea()` | `t.Transform(t.Any())` + `Buffer.isBuffer` |
+| nullable / optional | `t.Nullable` / `t.Optional` |
+
+Raw `.check("sql")` is not mapped. With `generate.elysia: true` (or Zod/TypeBox), codegen reads inline `json()` / `jsonb()` type arguments from `schema.ts`. Type aliases and imported types are not resolved yet — use an inline type or `.schema()` for those.
+
+```ts
+metadata: jsonb<{ featured: boolean; category?: string }>(),
+// → metadata: t.Nullable(t.Object({ featured: t.Boolean(), category: t.Optional(t.String()) }))
+```

package/docs/errors.md

@@ -48,7 +48,7 @@ Type guards (`isUniqueViolation`, `isQueryCompileError`, `isNeoOrmError`, …) a
 
 ## Query error codes
 
-Codes are **dialect-agnostic** — the same `unique_violation` code is used for PostgreSQL and SQLite.
+Codes are **dialect-agnostic** — the same `unique_violation` code is used for PostgreSQL, SQLite, MySQL, and MariaDB.
 
 | Code | Subclass | Typical HTTP | When |
 |------|----------|--------------|------|

package/docs/examples.md

@@ -369,7 +369,7 @@ await db.$transaction(async (tx) => {
 
 ## Raw SQL
 
-Use `db.sql` when you need full SQL control. It uses the same compiler as `neoorm/sql` (`sql`, `sqlId`, nested fragments). `sqlBuilder` is select/join/group/order only — interpolate `.compile()` into `db.sql` for WHERE, LIMIT, or bound params.
+Use `db.sql` when you need full SQL control. It uses the same compiler as `neoorm/sql` (`sql`, `sqlId`, nested fragments). `sqlBuilder` covers select/join/where/group/order/limit with bound params — interpolate `.compile()` into `db.sql` for HAVING or other raw tails.
 
 ```ts
 import { sql, sqlBuilder, sqlId } from "neoorm/sql";
@@ -391,7 +391,9 @@ const grouped = sqlBuilder
   .selectFrom("users")
   .leftJoin("posts", "posts.author_id", "users.id")
   .select(["users.id", "users.email"])
+  .where("users.email", "=", email)
   .groupBy("users.id", "users.email")
+  .limit(10)
   .compile();
 const dashboard = await db.sql`${grouped} HAVING count(posts.id) > ${0}`;
 ```
@@ -459,7 +461,7 @@ const db = createNeoOrmClient(manifest, {
 });
 ```
 
-See [SQLite](sqlite.md) for type mapping and limitations.
+See [SQLite](sqlite.md), [MySQL](mysql.md), and [MariaDB](mariadb.md) for type mapping and limitations.
 
 Log compiled SQL:
 

package/docs/getting-started.md

@@ -89,11 +89,12 @@ export default defineConfig({
 bunx neoorm generate
 ```
 
-To emit Zod or TypeBox Select/Create/Update schemas, install the library and set `generate.zod` / `generate.typebox` in config:
+To emit Zod, TypeBox, or Elysia Select/Create/Update schemas, install the library and set `generate.zod` / `generate.typebox` / `generate.elysia` in config:
 
 ```bash
 bun add zod
 bun add typebox
+bun add elysia
 ```
 
 ```ts
@@ -107,11 +108,12 @@ export default defineConfig({
   generate: {
     zod: true,
     typebox: true,
+    elysia: true,
   },
 });
 ```
 
-`neoorm generate` / `neoorm migrate dev` then writes `out/zod.ts` and/or `out/typebox.ts` (re-exported from `out/client.ts`). See [Zod schemas](zod.md) and [TypeBox schemas](typebox.md). `neoorm init` leaves this commented in `neoorm.config.ts`.
+`neoorm generate` / `neoorm migrate dev` then writes `out/zod.ts`, `out/typebox.ts`, and/or `out/elysia.ts` (re-exported from `out/client.ts`). See [Zod schemas](zod.md), [TypeBox schemas](typebox.md), and [Elysia schemas](elysia.md). `neoorm init` leaves this commented in `neoorm.config.ts`.
 
 ## SQLite
 
@@ -134,7 +136,7 @@ const db = createNeoOrmClient(manifest, {
 });
 ```
 
-See [SQLite](sqlite.md).
+See [SQLite](sqlite.md), [MySQL](mysql.md), and [MariaDB](mariadb.md).
 
 ## Tenant-specific schemas
 
@@ -145,7 +147,7 @@ const tenantDb = createNeoOrmClient(manifest, {
 });
 ```
 
-Raw `db.sql` uses the same compiler as `neoorm/sql`. `db.sql` / `db.execute` are not rewritten for tenant `schema` — qualify identifiers yourself.
+Raw `db.sql` uses the same compiler as `neoorm/sql`. With PostgreSQL `schema: "tenant_acme"`, `db.sql` / `db.execute` qualify unqualified table names from your manifest (`FROM users` → `"tenant_acme"."users"`). `db.sqlId("users")` is schema-qualified; column `sqlId`s are not. Explicit `schema.table` refs are left alone.
 
 Reuse an existing `pg` pool with `createNeoOrmClientFromPool(manifest, pool)`, or an existing SQLite handle with `createNeoOrmClientFromSqlite(manifest, database)`. `$disconnect()` does not close a borrowed pool or database — close it yourself when every consumer is done.
 

package/docs/mariadb.md

@@ -0,0 +1,149 @@
+# MariaDB
+
+MariaDB 10.11 LTS is a first-class dialect via the optional official `mariadb` connector. Schema DSL, codegen, migrations, and the query client work the same way as PostgreSQL, with the storage and SQL differences below.
+
+MariaDB versions below 10.11, GIS, Galera, and MaxScale specifics are out of scope. MySQL 8 uses a **separate** dialect and the `mysql2` driver — see [MySQL](mysql.md).
+
+## Requirements
+
+Install the driver next to NeoOrm:
+
+```bash
+bun add neoorm mariadb
+```
+
+If `mariadb` is missing, creating a client throws: `mariadb is not installed. Run: bun add mariadb`.
+
+## Configuration
+
+Set `provider: "mariadb"` and a MariaDB 10.11 connection URL:
+
+```ts
+// neoorm.config.ts
+import { defineConfig } from "neoorm";
+
+export default defineConfig({
+  schema: "./schema.ts",
+  out: "./neoorm",
+  datasource: {
+    provider: "mariadb",
+    url: process.env.DATABASE_URL ?? "mariadb://root@localhost:3306/myapp",
+  },
+});
+```
+
+`datasource.schema` is ignored (the database comes from the URL). `datasource.enum: "native"` is allowed and emits column `ENUM('a','b')` — there is no `CREATE TYPE`.
+
+## Runtime client
+
+```ts
+import { createNeoOrmClient } from "neoorm";
+import { manifest } from "./neoorm/manifest.js";
+
+const db = createNeoOrmClient(manifest, {
+  provider: "mariadb",
+  connectionString: process.env.MARIADB_URL,
+});
+```
+
+Wrap an existing `mariadb` pool with `createNeoOrmClientFromMariadb(manifest, pool)`. `$disconnect()` does not call `pool.end()` in that case — you own the pool.
+
+Data queries use connector `execute()` (prepared statements, `prepareCacheLength` 256). Transaction control stays on `query()`. Pools you wrap without `execute` fall back to `query()`.
+
+Owned pools from `createNeoOrmClient` accept the same `pool` object as PostgreSQL for shared fields (`max`, idle timeout, keep-alive). Default `max` is 10. Pipelining is enabled (commands are still awaited in order). PostgreSQL-only keys such as `statement_timeout` are ignored.
+
+```ts
+const db = createNeoOrmClient(manifest, {
+  provider: "mariadb",
+  connectionString: process.env.MARIADB_URL,
+  pool: {
+    max: 10,
+    idleTimeoutMillis: 10_000,
+    keepAlive: true,
+  },
+});
+```
+
+Standalone `neoorm/sql` (`sqlId`) stays ANSI-quoted (`"users"`). Use `db.sql` with `db.sqlId("users")` so identifiers are backticks on MariaDB.
+
+`mariadbDialect` is exported from `neoorm` for `dbPush`, migrate helpers, and custom executor wiring.
+
+## CLI
+
+```bash
+bunx neoorm init --provider mariadb
+bunx neoorm migrate deploy
+bunx neoorm db push
+bunx neoorm db pull
+bunx neoorm migrate status
+bunx neoorm migrate reset --force
+```
+
+- Deploy lock is `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy transaction.
+- `migrate reset` sets `FOREIGN_KEY_CHECKS=0`, drops all tables in the current database, then re-enables checks and re-applies migrations.
+- `db pull` introspects `information_schema`. MariaDB `JSON` columns are often `LONGTEXT` plus a `json_valid()` CHECK; NeoOrm maps those back to `jsonb()`.
+
+## Type mapping
+
+| Schema builder | MariaDB storage |
+|----------------|-----------------|
+| `id()`, unique/PK `text` | `VARCHAR(191)` (InnoDB index prefix; `TEXT` cannot be a unique key) |
+| `text()` otherwise | `TEXT`, or `VARCHAR(n)` with `.maxLength()` |
+| `uuid()` | `CHAR(36)` |
+| `bool()` | `TINYINT(1)` |
+| `int()` | `INT` |
+| `bigint()` | `BIGINT` |
+| `real()` / `float()` | `FLOAT` |
+| `double()` | `DOUBLE` |
+| `serial()` | `INT NOT NULL AUTO_INCREMENT` |
+| `timestamp()` | `DATETIME(6)` + `CURRENT_TIMESTAMP(6)` |
+| `date()` | `DATE` |
+| `time()` | `TIME` |
+| `json()` / `jsonb()` | `JSON` (LONGTEXT + `json_valid()` CHECK under the hood) |
+| `decimal()` | `DECIMAL(p,s)` |
+| `money()` | `DECIMAL(19,4)` |
+| `xml()` | `LONGTEXT` |
+| `bytea()` | `BLOB` |
+| arrays / `citext()` | `JSON` / `VARCHAR` + `utf8mb4_uca1400_ai_ci` |
+| `interval()`, `inet()`, `cidr()`, ranges | rejected at schema compile |
+| `enum: "check"` | `VARCHAR` + `CHECK` |
+| `enum: "native"` | column `ENUM('a','b')` |
+
+## Differences from MySQL 8
+
+| Feature | MySQL 8 | MariaDB 10.11 |
+|---------|---------|----------------|
+| Driver | `mysql2` | official `mariadb` package |
+| `upsert` | `INSERT … AS new ON DUPLICATE KEY UPDATE` | `ON DUPLICATE KEY UPDATE col = VALUES(col)` |
+| `search` | `REGEXP_LIKE` | `col REGEXP $n` (`(?i)` for insensitive) |
+| `citext` collation | `utf8mb4_0900_ai_ci` | `utf8mb4_uca1400_ai_ci` |
+| CHECK drop | `DROP CHECK` | `DROP CONSTRAINT` |
+| CHECK errno | 3819 | 4025 (`ER_CONSTRAINT_FAILED`) |
+| JSON storage | native JSON | JSON as LONGTEXT + `json_valid()` |
+| `RETURNING` | none | INSERT/DELETE RETURNING exist, but UPDATE does not; NeoOrm uses follow-up `SELECT` for all writes |
+
+## Differences from PostgreSQL
+
+| Feature | PostgreSQL | MariaDB |
+|---------|------------|---------|
+| Identifier quoting | `"users"` | `` `users` `` |
+| `RETURNING` | native | follow-up `SELECT` (or `insertId` for serial) |
+| `upsert` | `ON CONFLICT … DO UPDATE` | `ON DUPLICATE KEY UPDATE` + `VALUES(col)` |
+| `skipDuplicates` | `ON CONFLICT DO NOTHING` | `INSERT IGNORE` |
+| `findOrCreate` | `xmax = 0` | SELECT → INSERT → retry on unique violation |
+| `in` / `notIn` | array bind | `JSON_TABLE` |
+| `search` | POSIX `~` | `REGEXP` |
+| `ilike` | `ILIKE` | `LOWER(col) LIKE LOWER(?)` |
+| JSON operators | `@>`, `?`, `#>` | `JSON_CONTAINS` / `JSON_EXTRACT` / `JSON_CONTAINS_PATH` |
+| Nested includes | `json_agg … FILTER` | JOIN `JSON_ARRAYAGG` when possible; otherwise batched `IN` queries (no `LATERAL`) |
+| `distinct` (`DISTINCT ON`) | supported | throws |
+| Partial indexes `index({ where })` | supported | rejected at schema compile |
+| PostGIS | supported | rejected |
+| `interval` / `inet` / `cidr` / range types | supported | rejected at schema compile |
+| `datasource.schema` | multi-schema | ignored (URL database) |
+
+MariaDB has no `LATERAL`, so correlated `JSON_ARRAYAGG` derived tables (the MySQL 8 / Postgres inline has-many subquery) cannot see outer columns such as `` `users`.`id` ``. Those includes are loaded with a follow-up `WHERE fk IN (…)` query instead.
+
+`createManyAndReturn` for serial primary keys uses `LAST_INSERT_ID()` plus row count inside a transaction and assumes consecutive autoincrement values.
+
+Everything else — relations, nested writes, cursor pagination, aggregates, `groupBy`, savepoint-based nested transactions — behaves the same as on PostgreSQL.

package/docs/migrations.md

@@ -10,7 +10,7 @@
 | `neoorm migrate deploy` | Apply pending migrations |
 | `neoorm migrate status` | List applied vs pending migrations |
 | `neoorm migrate down [--steps N]` | Roll back the last N applied migrations (default 1) |
-| `neoorm migrate reset --force` | Drop the `public` schema (PostgreSQL) or all tables (SQLite) and re-apply migrations (local dev) |
+| `neoorm migrate reset --force` | Drop the `public` schema (PostgreSQL) or all tables (SQLite / MySQL / MariaDB) and re-apply migrations (local dev) |
 | `neoorm db push` | Push the current `schema.ts` to the database (no migration file) |
 | `neoorm db pull` | Introspect the database into a schema file |
 
@@ -38,7 +38,9 @@ neoorm generate --accept-data-loss
 | Dialect | Lock |
 |---------|------|
 | PostgreSQL | `pg_advisory_xact_lock` on the deploy transaction |
-| SQLite | `BEGIN IMMEDIATE` around the whole deploy |
+| SQLite | `BEGIN IMMEDIATE` around the whole deploy (after `PRAGMA foreign_keys = OFF`) |
+| MySQL | `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy connection |
+| MariaDB | `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy connection |
 
 The ledger table `_neoorm_migrations` stores `name` and `checksum`. Editing an already-applied `migration.sql` is rejected (`migration_guard`) — restore the original file or add a new migration. Pending migrations in one deploy run apply in that locked transaction; if a later statement fails, none of that run's new ledger rows remain.
 
@@ -56,7 +58,7 @@ Shows applied migrations (with timestamps), pending folders on disk, and warning
 neoorm migrate reset --force
 ```
 
-Drops the `public` schema (PostgreSQL) or all tables (SQLite) and re-applies all migrations from disk. Requires `--force`. Use `--skip-apply` to only drop without re-applying.
+Drops the `public` schema (PostgreSQL) or all tables (SQLite, MySQL, and MariaDB) and re-applies all migrations from disk. Requires `--force`. Use `--skip-apply` to only drop without re-applying.
 
 PostgreSQL reset recreates the schema owned by the connecting role. It does not `GRANT ALL ON SCHEMA … TO PUBLIC`.
 

package/docs/mysql.md

@@ -0,0 +1,134 @@
+# MySQL
+
+MySQL 8.0+ is a first-class dialect via the optional `mysql2` driver. Schema DSL, codegen, migrations, and the query client work against MySQL the same way they do against PostgreSQL, with the storage and SQL differences below.
+
+PlanetScale, MySQL 5.7, and GIS/PostGIS are out of scope.
+
+## Requirements
+
+Install the driver next to NeoOrm:
+
+```bash
+bun add neoorm mysql2
+```
+
+If `mysql2` is missing, creating a client throws: `mysql2 is not installed. Run: bun add mysql2`.
+
+## Configuration
+
+Set `provider: "mysql"` and a MySQL 8 connection URL:
+
+```ts
+// neoorm.config.ts
+import { defineConfig } from "neoorm";
+
+export default defineConfig({
+  schema: "./schema.ts",
+  out: "./neoorm",
+  datasource: {
+    provider: "mysql",
+    url: process.env.DATABASE_URL ?? "mysql://root@localhost:3306/myapp",
+  },
+});
+```
+
+`datasource.schema` is ignored (the database comes from the URL). `datasource.enum: "native"` is allowed and emits column `ENUM('a','b')` — there is no `CREATE TYPE`.
+
+## Runtime client
+
+```ts
+import { createNeoOrmClient } from "neoorm";
+import { manifest } from "./neoorm/manifest.js";
+
+const db = createNeoOrmClient(manifest, {
+  provider: "mysql",
+  connectionString: process.env.MYSQL_URL,
+});
+```
+
+Wrap an existing `mysql2/promise` pool with `createNeoOrmClientFromMysql(manifest, pool)`. `$disconnect()` does not call `pool.end()` in that case — you own the pool.
+
+Data queries use mysql2 `execute()` (binary prepared statements, cached per connection). Transaction control (`START TRANSACTION`, `COMMIT`, `SAVEPOINT`) stays on `query()`. Pools you wrap without `execute` fall back to `query()`.
+
+Owned pools from `createNeoOrmClient` accept the same `pool` object as PostgreSQL for shared fields (`max`, idle timeout, keep-alive). Default `max` is 10 (`connectionLimit`). PostgreSQL-only keys such as `statement_timeout` are ignored.
+
+```ts
+const db = createNeoOrmClient(manifest, {
+  provider: "mysql",
+  connectionString: process.env.MYSQL_URL,
+  pool: {
+    max: 10,
+    idleTimeoutMillis: 10_000,
+    keepAlive: true,
+  },
+});
+```
+
+Standalone `neoorm/sql` (`sqlId`) stays ANSI-quoted (`"users"`). Use `db.sql` with `db.sqlId("users")` so identifiers are backticks on MySQL.
+
+`mysqlDialect` is exported from `neoorm` for `dbPush`, migrate helpers, and custom executor wiring.
+
+## CLI
+
+```bash
+bunx neoorm init --provider mysql
+bunx neoorm migrate deploy
+bunx neoorm db push
+bunx neoorm db pull
+bunx neoorm migrate status
+bunx neoorm migrate reset --force
+```
+
+- Deploy lock is `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy transaction.
+- `migrate reset` sets `FOREIGN_KEY_CHECKS=0`, drops all tables in the current database, then re-enables checks and re-applies migrations.
+- `db pull` introspects `information_schema` back into a schema file.
+
+## Type mapping
+
+| Schema builder | MySQL storage |
+|----------------|---------------|
+| `id()`, unique/PK `text` | `VARCHAR(191)` (InnoDB index prefix; `TEXT` cannot be a unique key) |
+| `text()` otherwise | `TEXT`, or `VARCHAR(n)` with `.maxLength()` |
+| `uuid()` | `CHAR(36)` |
+| `bool()` | `TINYINT(1)` |
+| `int()` | `INT` |
+| `bigint()` | `BIGINT` |
+| `real()` / `float()` | `FLOAT` |
+| `double()` | `DOUBLE` |
+| `serial()` | `INT NOT NULL AUTO_INCREMENT` |
+| `timestamp()` | `DATETIME(6)` + `CURRENT_TIMESTAMP(6)` |
+| `date()` | `DATE` |
+| `time()` | `TIME` |
+| `json()` / `jsonb()` | `JSON` |
+| `decimal()` | `DECIMAL(p,s)` |
+| `money()` | `DECIMAL(19,4)` |
+| `xml()` | `LONGTEXT` |
+| `bytea()` | `BLOB` |
+| arrays / `citext()` | `JSON` / `VARCHAR` + `utf8mb4_0900_ai_ci` |
+| `interval()`, `inet()`, `cidr()`, ranges | rejected at schema compile |
+| `enum: "check"` | `VARCHAR` + `CHECK` (8.0.16+) |
+| `enum: "native"` | column `ENUM('a','b')` |
+
+## Differences from PostgreSQL
+
+| Feature | PostgreSQL | MySQL |
+|---------|------------|--------|
+| Identifier quoting | `"users"` | `` `users` `` |
+| `RETURNING` | native | follow-up `SELECT` (or `insertId` for serial) |
+| `upsert` | `ON CONFLICT … DO UPDATE` | `INSERT … AS new ON DUPLICATE KEY UPDATE` |
+| `skipDuplicates` | `ON CONFLICT DO NOTHING` | `INSERT IGNORE` |
+| `findOrCreate` | `xmax = 0` | SELECT → INSERT → retry on unique violation |
+| `in` / `notIn` | array bind | `JSON_TABLE` |
+| `search` | POSIX `~` | `REGEXP_LIKE` |
+| `ilike` | `ILIKE` | `LOWER(col) LIKE LOWER(?)` |
+| JSON operators | `@>`, `?`, `#>` | `JSON_CONTAINS` / `JSON_EXTRACT` / `JSON_CONTAINS_PATH` |
+| Nested includes | `json_agg … FILTER` | `JSON_ARRAYAGG(CASE WHEN …)` |
+| `distinct` (`DISTINCT ON`) | supported | throws |
+| Partial indexes `index({ where })` | supported | rejected at schema compile |
+| PostGIS | supported | rejected |
+| `interval` / `inet` / `cidr` / range types | supported | rejected at schema compile |
+| `datasource.schema` | multi-schema | ignored (URL database) |
+
+`createManyAndReturn` for serial primary keys uses `LAST_INSERT_ID()` plus row count inside a transaction and assumes consecutive autoincrement values.
+
+Everything else — relations, nested writes, cursor pagination, aggregates, `groupBy`, savepoint-based nested transactions — behaves the same as on PostgreSQL.

package/docs/plugins.md

@@ -48,7 +48,7 @@ users: table({
 
 See the plugin registry source for `ColumnTypePlugin` and `NeoOrmPlugin` interfaces.
 
-Column types may implement `columnValidation(col)` returning a validator-neutral IR node (`{ kind: "string" }`, `{ kind: "enum", values }`, GeoJSON `object` / `union`, and so on). Zod and TypeBox codegen print that IR. Omit the hook to fall back to `unknown`.
+Column types may implement `columnValidation(col)` returning a validator-neutral IR node (`{ kind: "string" }`, `{ kind: "enum", values }`, GeoJSON `object` / `union`, and so on). Zod, TypeBox, and Elysia codegen print that IR. Omit the hook to fall back to `unknown`.
 
 To type `where` operators, augment `PluginColumnWhereOperators` on `neoorm/schema` with your column kind:
 

package/docs/queries.md

@@ -30,7 +30,7 @@ await db.users.findFirst({
 const user = await db.users.findUnique({ where: { slug: "hello" } });
 ```
 
-Unique `where` (`findUnique`, `upsert`, `findOrCreate`, singular `update`/`delete`) is scalar equality per unique field — `{ email: "a@b.com" }`, not a filter. `{ equals: value }` is accepted and unwrapped to the scalar. Other operators (`contains`, `in`, `mode: "insensitive"`) throw `unique_where_invalid`.
+Unique `where` (`findUnique`, `upsert`, `findOrCreate`, singular `update`/`delete`) is scalar equality per unique field — `{ email: "a@b.com" }`, not a filter. `{ equals: value }` is accepted and unwrapped to the scalar. Other operators (`contains`, `in`, `mode: "insensitive"`) throw `unique_where_invalid`. Partial unique indexes are valid targets: pass the indexed columns; the index `WHERE` is applied automatically so the lookup stays unique.
 
 ## Create
 
@@ -73,7 +73,7 @@ Unknown keys in `data` fail at compile time (`unknown_column`), same as `where`.
 
 ## Update
 
-Singular `update` requires a unique `where` (primary key, `@unique` column, or composite unique index), same as `findUnique`. Use `updateMany` when the filter can match multiple rows.
+Singular `update` requires a unique `where` (primary key, `@unique` column, composite unique index, or partial unique index), same as `findUnique`. Use `updateMany` when the filter can match multiple rows.
 
 ```ts
 // Returns {} on success, null if no row matched
@@ -181,7 +181,7 @@ Atomically insert a row or return an existing one when a unique constraint match
 
 Postgres issues `INSERT … ON CONFLICT DO UPDATE` with a no-op assignment so `RETURNING` always includes the row — including when a concurrent session already inserted it. `created` is `(xmax = 0)` (inserted vs existing). A no-op update can fire `UPDATE` triggers; column values are not changed.
 
-Under `SERIALIZABLE` (and sometimes `REPEATABLE READ`), a concurrent insert can still abort the transaction with a serialization failure. Retry the whole `$transaction`. SQLite uses find-then-insert and retries the find after a unique violation.
+Under `SERIALIZABLE` (and sometimes `REPEATABLE READ`), a concurrent insert can still abort the transaction with a serialization failure. Retry the whole `$transaction`. SQLite, MySQL, and MariaDB use find-then-insert and retry the find after a unique violation.
 
 ```ts
 const { record, created } = await db.tags.findOrCreate({
@@ -219,11 +219,11 @@ Unknown column names and operators fail at compile time (`unknown_column`, with
 | PostGIS (`geometry`, `geography`, `point`) | `intersects`, `within`, `dWithin` |
 | All nullable | `isNull`, `isNotNull` |
 
-`contains`, `startsWith`, `endsWith`, and `equals` compile to `LIKE` / `=`. Pass sibling `mode: "insensitive"` for case-folding (`ILIKE` on Postgres, `LOWER(col) LIKE LOWER($n)` on SQLite). SQLite `LIKE` is ASCII case-insensitive even in default mode. `%` and `_` in the search string are matched literally (`ESCAPE '\'`).
+`contains`, `startsWith`, `endsWith`, and `equals` compile to `LIKE` / `=`. Pass sibling `mode: "insensitive"` for case-folding (`ILIKE` on Postgres, `LOWER(col) LIKE LOWER($n)` on SQLite/MySQL/MariaDB). SQLite `LIKE` is ASCII case-insensitive even in default mode. `%` and `_` in the search string are matched literally (`ESCAPE '\'` on Postgres/SQLite, `ESCAPE '\\'` on MySQL/MariaDB).
 
-`search` is POSIX regex (`~`, or `~*` with `mode: "insensitive"`). It is PostgreSQL-only; SQLite throws.
+`search` is POSIX regex on PostgreSQL (`~`, or `~*` with `mode: "insensitive"`), `REGEXP_LIKE` on MySQL 8, `REGEXP` on MariaDB, and JavaScript `RegExp` (`REGEXP` / `regexp_i`) on SQLite.
 
-JSON operators on PostgreSQL use `@>`, `?`, and `#>` / `#>>`. On SQLite they compile to `json_patch` (object containment), `json_each` (key existence), and `json_extract` (path).
+JSON operators on PostgreSQL use `@>`, `?`, and `#>` / `#>>`. On SQLite they compile to `json_patch` (object containment), `json_each` (key existence), and `json_extract` (path). On MySQL and MariaDB they compile to `JSON_CONTAINS`, `JSON_CONTAINS_PATH`, and `JSON_EXTRACT`.
 
 ```ts
 await db.posts.findMany({
@@ -321,7 +321,7 @@ await db.users.findMany({
 });
 ```
 
-Not supported on SQLite (`DISTINCT ON` is PostgreSQL-only) — it throws `distinct is not supported on SQLite`. Use `groupBy({ by: [...] })` or a raw `db.sql` query instead.
+Not supported on MySQL or MariaDB (`DISTINCT ON` is PostgreSQL-only; SQLite emulates it with `ROW_NUMBER()`). Use `groupBy({ by: [...] })` or a raw `db.sql` query instead.
 
 ## Eager loading with `with`
 
@@ -524,7 +524,7 @@ const byAuthor = await db.posts.groupBy({
 
 Star `_count: true` still works with `having: { _count: { gte: 5 } }` and `orderBy: { _count: "desc" }`.
 
-`where` filters rows before grouping. `having` filters groups (aggregates only). `by` alone lists distinct groups — useful on SQLite where `distinct` is not available.
+`where` filters rows before grouping. `having` filters groups (aggregates only). `by` alone lists distinct groups — useful when you need grouped aggregates rather than `findMany({ distinct })`.
 
 ## Count
 
@@ -545,7 +545,7 @@ const taken = await db.users.exists({ where: { email: "a@b.com" } });
 
 ## Raw SQL
 
-`db.sql` and `import { sql } from "neoorm/sql"` share one compiler. Interpolate values, `sqlId("table")`, nested `sql\`...\`` fragments, or `sqlBuilder.compile()`. `sqlBuilder` itself has no WHERE, LIMIT, or params — add those in the `db.sql` tag.
+`db.sql` and `import { sql } from "neoorm/sql"` share one compiler. Interpolate values, `sqlId("table")`, nested `sql\`...\`` fragments, or `sqlBuilder.compile()`. `sqlBuilder` covers select/join/where/group/order/limit with bound params; use `db.sql` for HAVING and other raw tails.
 
 ```ts
 import { sql, sqlBuilder, sqlId } from "neoorm/sql";
@@ -557,12 +557,15 @@ const rows = await db.sql`SELECT * FROM ${ident} WHERE ${filter}`;
 const grouped = sqlBuilder
   .selectFrom("users")
   .select(["id", "email"])
+  .where("email", "=", "a@b.com")
+  .orWhere(sql`role = ${"admin"}`)
   .groupBy("id", "email")
+  .limit(10)
   .compile();
-await db.sql`${grouped} LIMIT ${10}`;
+await db.sql`${grouped} HAVING count(*) > ${0}`;
 ```
 
-`db.execute({ text, params })` runs already-compiled SQL. Raw SQL is not rewritten for tenant `schema` — qualify identifiers yourself.
+`db.execute({ text, params })` runs already-compiled SQL. With PostgreSQL tenant `schema`, `db.sql` / `db.execute` qualify unqualified manifest table names (same as `db.sqlId("users")`). Already-qualified `schema.table` identifiers are unchanged.
 
 ## Logging SQL