neoorm 0.9.6 → 0.9.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (217) hide show
  1. package/dist/bin/neoorm.d.ts.map +1 -1
  2. package/dist/bin/neoorm.js +83 -141
  3. package/dist/bin/neoorm.js.map +1 -1
  4. package/dist/codegen/column-ts.d.ts.map +1 -1
  5. package/dist/codegen/column-ts.js +5 -2
  6. package/dist/codegen/column-ts.js.map +1 -1
  7. package/dist/codegen/diff-manifest.js +1 -1
  8. package/dist/codegen/diff-manifest.js.map +1 -1
  9. package/dist/codegen/emit-includes.d.ts.map +1 -1
  10. package/dist/codegen/emit-includes.js +11 -8
  11. package/dist/codegen/emit-includes.js.map +1 -1
  12. package/dist/codegen/emit-models.d.ts.map +1 -1
  13. package/dist/codegen/emit-models.js +9 -8
  14. package/dist/codegen/emit-models.js.map +1 -1
  15. package/dist/codegen/emit-query-types.d.ts.map +1 -1
  16. package/dist/codegen/emit-query-types.js +53 -16
  17. package/dist/codegen/emit-query-types.js.map +1 -1
  18. package/dist/codegen/generate.d.ts +1 -0
  19. package/dist/codegen/generate.d.ts.map +1 -1
  20. package/dist/codegen/generate.js +8 -1
  21. package/dist/codegen/generate.js.map +1 -1
  22. package/dist/codegen/manifest-relations.d.ts.map +1 -1
  23. package/dist/codegen/manifest-relations.js +2 -1
  24. package/dist/codegen/manifest-relations.js.map +1 -1
  25. package/dist/codegen/schema-to-manifest.d.ts.map +1 -1
  26. package/dist/codegen/schema-to-manifest.js +174 -8
  27. package/dist/codegen/schema-to-manifest.js.map +1 -1
  28. package/dist/codegen/ts-syntax.d.ts +12 -0
  29. package/dist/codegen/ts-syntax.d.ts.map +1 -0
  30. package/dist/codegen/ts-syntax.js +24 -0
  31. package/dist/codegen/ts-syntax.js.map +1 -0
  32. package/dist/codegen/validation/emit-elysia.d.ts.map +1 -1
  33. package/dist/codegen/validation/emit-elysia.js +5 -4
  34. package/dist/codegen/validation/emit-elysia.js.map +1 -1
  35. package/dist/codegen/validation/emit-typebox.d.ts.map +1 -1
  36. package/dist/codegen/validation/emit-typebox.js +5 -4
  37. package/dist/codegen/validation/emit-typebox.js.map +1 -1
  38. package/dist/codegen/validation/emit-zod.d.ts.map +1 -1
  39. package/dist/codegen/validation/emit-zod.js +5 -4
  40. package/dist/codegen/validation/emit-zod.js.map +1 -1
  41. package/dist/codegen/validation/from-manifest.d.ts.map +1 -1
  42. package/dist/codegen/validation/from-manifest.js +37 -10
  43. package/dist/codegen/validation/from-manifest.js.map +1 -1
  44. package/dist/config.d.ts.map +1 -1
  45. package/dist/config.js +8 -1
  46. package/dist/config.js.map +1 -1
  47. package/dist/dialect/mariadb.test.js +28 -1
  48. package/dist/dialect/mariadb.test.js.map +1 -1
  49. package/dist/dialect/mysql-family.js +6 -6
  50. package/dist/dialect/mysql-family.js.map +1 -1
  51. package/dist/dialect/mysql.test.js +33 -1
  52. package/dist/dialect/mysql.test.js.map +1 -1
  53. package/dist/dialect/postgres.js +1 -1
  54. package/dist/dialect/postgres.js.map +1 -1
  55. package/dist/dialect/sqlite.js +1 -1
  56. package/dist/dialect/sqlite.js.map +1 -1
  57. package/dist/dialect/sqlite.test.js +9 -0
  58. package/dist/dialect/sqlite.test.js.map +1 -1
  59. package/dist/dialect/types.d.ts +1 -1
  60. package/dist/dialect/types.d.ts.map +1 -1
  61. package/dist/init/prompt.d.ts.map +1 -1
  62. package/dist/init/prompt.js +14 -3
  63. package/dist/init/prompt.js.map +1 -1
  64. package/dist/init/scaffold.d.ts.map +1 -1
  65. package/dist/init/scaffold.js +31 -4
  66. package/dist/init/scaffold.js.map +1 -1
  67. package/dist/init/templates.d.ts +5 -0
  68. package/dist/init/templates.d.ts.map +1 -1
  69. package/dist/init/templates.js +33 -6
  70. package/dist/init/templates.js.map +1 -1
  71. package/dist/init/validate.d.ts +3 -1
  72. package/dist/init/validate.d.ts.map +1 -1
  73. package/dist/init/validate.js +61 -4
  74. package/dist/init/validate.js.map +1 -1
  75. package/dist/introspect/mysql/to-manifest.d.ts.map +1 -1
  76. package/dist/introspect/mysql/to-manifest.js +2 -1
  77. package/dist/introspect/mysql/to-manifest.js.map +1 -1
  78. package/dist/introspect/pull.d.ts +5 -0
  79. package/dist/introspect/pull.d.ts.map +1 -1
  80. package/dist/introspect/pull.js +186 -35
  81. package/dist/introspect/pull.js.map +1 -1
  82. package/dist/introspect/sqlite/to-manifest.d.ts.map +1 -1
  83. package/dist/introspect/sqlite/to-manifest.js +2 -1
  84. package/dist/introspect/sqlite/to-manifest.js.map +1 -1
  85. package/dist/introspect/table-map.d.ts +9 -0
  86. package/dist/introspect/table-map.d.ts.map +1 -0
  87. package/dist/introspect/table-map.js +21 -0
  88. package/dist/introspect/table-map.js.map +1 -0
  89. package/dist/introspect/to-manifest.d.ts.map +1 -1
  90. package/dist/introspect/to-manifest.js +2 -1
  91. package/dist/introspect/to-manifest.js.map +1 -1
  92. package/dist/migrate/dev-workflow.d.ts +36 -0
  93. package/dist/migrate/dev-workflow.d.ts.map +1 -0
  94. package/dist/migrate/dev-workflow.js +96 -0
  95. package/dist/migrate/dev-workflow.js.map +1 -0
  96. package/dist/migrate/runner.d.ts +4 -1
  97. package/dist/migrate/runner.d.ts.map +1 -1
  98. package/dist/migrate/runner.js +140 -29
  99. package/dist/migrate/runner.js.map +1 -1
  100. package/dist/runtime/client.d.ts.map +1 -1
  101. package/dist/runtime/client.js +2 -0
  102. package/dist/runtime/client.js.map +1 -1
  103. package/dist/runtime/client.test.js +43 -0
  104. package/dist/runtime/client.test.js.map +1 -1
  105. package/dist/runtime/driver-sqlite.test.js +186 -0
  106. package/dist/runtime/driver-sqlite.test.js.map +1 -1
  107. package/dist/runtime/driver.d.ts +8 -0
  108. package/dist/runtime/driver.d.ts.map +1 -1
  109. package/dist/runtime/driver.js +76 -125
  110. package/dist/runtime/driver.js.map +1 -1
  111. package/dist/runtime/error-codes.d.ts +3 -0
  112. package/dist/runtime/error-codes.d.ts.map +1 -1
  113. package/dist/runtime/error-codes.js +3 -0
  114. package/dist/runtime/error-codes.js.map +1 -1
  115. package/dist/runtime/error-hints.d.ts.map +1 -1
  116. package/dist/runtime/error-hints.js +19 -15
  117. package/dist/runtime/error-hints.js.map +1 -1
  118. package/dist/runtime/errors.d.ts +6 -0
  119. package/dist/runtime/errors.d.ts.map +1 -1
  120. package/dist/runtime/errors.js +60 -21
  121. package/dist/runtime/errors.js.map +1 -1
  122. package/dist/runtime/executor.d.ts.map +1 -1
  123. package/dist/runtime/executor.js +16 -17
  124. package/dist/runtime/executor.js.map +1 -1
  125. package/dist/runtime/mariadb-driver.d.ts.map +1 -1
  126. package/dist/runtime/mariadb-driver.js +12 -15
  127. package/dist/runtime/mariadb-driver.js.map +1 -1
  128. package/dist/runtime/mysql-driver.d.ts.map +1 -1
  129. package/dist/runtime/mysql-driver.js +17 -16
  130. package/dist/runtime/mysql-driver.js.map +1 -1
  131. package/dist/runtime/mysql-family-pool.test.js +107 -1
  132. package/dist/runtime/mysql-family-pool.test.js.map +1 -1
  133. package/dist/runtime/mysql-placeholders.d.ts.map +1 -1
  134. package/dist/runtime/mysql-placeholders.js +12 -0
  135. package/dist/runtime/mysql-placeholders.js.map +1 -1
  136. package/dist/runtime/mysql-placeholders.test.js +15 -0
  137. package/dist/runtime/mysql-placeholders.test.js.map +1 -1
  138. package/dist/runtime/pg-rollback.test.js +42 -0
  139. package/dist/runtime/pg-rollback.test.js.map +1 -1
  140. package/dist/runtime/query/compile-where.d.ts.map +1 -1
  141. package/dist/runtime/query/compile-where.js +26 -1
  142. package/dist/runtime/query/compile-where.js.map +1 -1
  143. package/dist/runtime/query/find-or-create.test.js +19 -0
  144. package/dist/runtime/query/find-or-create.test.js.map +1 -1
  145. package/dist/runtime/query/table-index.d.ts +1 -1
  146. package/dist/runtime/query/table-index.d.ts.map +1 -1
  147. package/dist/runtime/query/table-index.js +2 -1
  148. package/dist/runtime/query/table-index.js.map +1 -1
  149. package/dist/runtime/query/update.d.ts.map +1 -1
  150. package/dist/runtime/query/update.js +9 -1
  151. package/dist/runtime/query/update.js.map +1 -1
  152. package/dist/runtime/query/upsert.d.ts.map +1 -1
  153. package/dist/runtime/query/upsert.js +12 -3
  154. package/dist/runtime/query/upsert.js.map +1 -1
  155. package/dist/runtime/regex-guard.d.ts +28 -0
  156. package/dist/runtime/regex-guard.d.ts.map +1 -0
  157. package/dist/runtime/regex-guard.js +124 -0
  158. package/dist/runtime/regex-guard.js.map +1 -0
  159. package/dist/runtime/regex-guard.test.d.ts +2 -0
  160. package/dist/runtime/regex-guard.test.d.ts.map +1 -0
  161. package/dist/runtime/regex-guard.test.js +63 -0
  162. package/dist/runtime/regex-guard.test.js.map +1 -0
  163. package/dist/runtime/sqlite-open.d.ts +5 -0
  164. package/dist/runtime/sqlite-open.d.ts.map +1 -1
  165. package/dist/runtime/sqlite-open.js +30 -7
  166. package/dist/runtime/sqlite-open.js.map +1 -1
  167. package/dist/runtime/sqlite-open.test.d.ts +2 -0
  168. package/dist/runtime/sqlite-open.test.d.ts.map +1 -0
  169. package/dist/runtime/sqlite-open.test.js +66 -0
  170. package/dist/runtime/sqlite-open.test.js.map +1 -0
  171. package/dist/runtime/transaction.d.ts +16 -0
  172. package/dist/runtime/transaction.d.ts.map +1 -1
  173. package/dist/runtime/transaction.js +50 -0
  174. package/dist/runtime/transaction.js.map +1 -1
  175. package/dist/runtime/transaction.test.js +50 -1
  176. package/dist/runtime/transaction.test.js.map +1 -1
  177. package/dist/schema/index.d.ts +1 -1
  178. package/dist/schema/index.d.ts.map +1 -1
  179. package/dist/schema/index.js.map +1 -1
  180. package/dist/schema/relation-types.d.ts +22 -1
  181. package/dist/schema/relation-types.d.ts.map +1 -1
  182. package/dist/sql/split-statements.d.ts +15 -0
  183. package/dist/sql/split-statements.d.ts.map +1 -0
  184. package/dist/sql/split-statements.js +132 -0
  185. package/dist/sql/split-statements.js.map +1 -0
  186. package/dist/studio/server.d.ts.map +1 -1
  187. package/dist/studio/server.js +1 -0
  188. package/dist/studio/server.js.map +1 -1
  189. package/dist/utils/case.js +1 -1
  190. package/dist/utils/case.js.map +1 -1
  191. package/dist/utils/dotenv.d.ts +5 -0
  192. package/dist/utils/dotenv.d.ts.map +1 -1
  193. package/dist/utils/dotenv.js +100 -24
  194. package/dist/utils/dotenv.js.map +1 -1
  195. package/dist/utils/dotenv.test.js +73 -2
  196. package/dist/utils/dotenv.test.js.map +1 -1
  197. package/dist/utils/inflect.d.ts.map +1 -1
  198. package/dist/utils/inflect.js +12 -0
  199. package/dist/utils/inflect.js.map +1 -1
  200. package/dist/utils/load-ts.d.ts.map +1 -1
  201. package/dist/utils/load-ts.js +4 -3
  202. package/dist/utils/load-ts.js.map +1 -1
  203. package/dist/utils/load-ts.test.d.ts +2 -0
  204. package/dist/utils/load-ts.test.d.ts.map +1 -0
  205. package/dist/utils/load-ts.test.js +17 -0
  206. package/dist/utils/load-ts.test.js.map +1 -0
  207. package/docs/cli.md +3 -3
  208. package/docs/configuration.md +2 -2
  209. package/docs/getting-started.md +1 -1
  210. package/docs/mariadb.md +2 -1
  211. package/docs/migrate-dev-workflow.md +84 -0
  212. package/docs/migrations.md +6 -1
  213. package/docs/mysql.md +2 -1
  214. package/docs/sqlite.md +4 -2
  215. package/docs/transactions.md +1 -1
  216. package/llms-full.txt +106 -12
  217. package/package.json +1 -1
@@ -33,7 +33,7 @@ await db.$transaction(fn, {
33
33
 
34
34
  ## Nested transactions
35
35
 
36
- Uses database savepoints on the same connection. A nested failure rolls back only that block; the outer transaction can continue.
36
+ Uses database savepoints on the same connection. A nested failure rolls back only that block; the outer transaction can continue. If that rollback succeeds but `RELEASE SAVEPOINT` fails, the savepoint is still open, so the outer transaction is aborted instead of committing. The nested block's original error is preserved.
37
37
 
38
38
  ```ts
39
39
  await db.$transaction(async (tx) => {
package/llms-full.txt CHANGED
@@ -18,7 +18,7 @@ cp .env.example .env
18
18
  bunx neoorm migrate dev
19
19
  ```
20
20
 
21
- The CLI loads `.env` automatically. You do not need to export `DATABASE_URL` in the shell first.
21
+ The CLI and the generated client both load `.env` automatically. You do not need to export `DATABASE_URL` in the shell first. Editing `.env` is enough for the next process that creates a client; you do not need to regenerate.
22
22
 
23
23
  Browse and edit data with Studio:
24
24
 
@@ -2317,7 +2317,7 @@ await db.$transaction(fn, {
2317
2317
 
2318
2318
  ## Nested transactions
2319
2319
 
2320
- Uses database savepoints on the same connection. A nested failure rolls back only that block; the outer transaction can continue.
2320
+ Uses database savepoints on the same connection. A nested failure rolls back only that block; the outer transaction can continue. If that rollback succeeds but `RELEASE SAVEPOINT` fails, the savepoint is still open, so the outer transaction is aborted instead of committing. The nested block's original error is preserved.
2321
2321
 
2322
2322
  ```ts
2323
2323
  await db.$transaction(async (tx) => {
@@ -2378,6 +2378,9 @@ After the transaction commits or rolls back, `query_only` is turned off so later
2378
2378
 
2379
2379
  Migration names are slugified (`Add Users` → `add_users`, capped at 50 chars) and prefixed with a timestamp so folders sort in apply order. `--name` is only needed when a migration is created: the CLI prompts on a TTY at that point (after pending migrations are applied in `dev`) and errors in non-interactive runs. Runs with no schema changes (client regeneration only) and pending-apply-only `dev` runs succeed without `--name` and never prompt. Older `*_migration` folders still apply in order.
2380
2380
 
2381
+ `migrate dev` holds its lock from before pending reconciliation through the optional name prompt, generation, and post-generation reconciliation/application.
2382
+ For the implementation ordering and regression coverage, see [the workflow guide](migrate-dev-workflow.md).
2383
+
2381
2384
  When migration is blocked, the CLI explains why — for example unsupported type casts (`alter_column_type_manual`), enum value changes, or destructive drops. Re-run with `--accept-data-loss` to include destructive DDL:
2382
2385
 
2383
2386
  ```bash
@@ -2408,7 +2411,9 @@ neoorm migrate diff --json
2408
2411
  | MySQL | `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy connection |
2409
2412
  | MariaDB | `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy connection |
2410
2413
 
2411
- 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.
2414
+ The ledger table `_neoorm_migrations` stores `name`, a SHA-256 `checksum` of `migration.sql`, and `down_checksum` for `down.sql`. Deploy refuses a missing `migration.sql`, a null checksum, or a checksum that does not match the file. It also refuses a pending migration that sorts before one already applied, so an earlier file cannot run after a later one. `migrate down` runs `down.sql` only when its checksum matches the value stored at apply time.
2415
+
2416
+ PostgreSQL and SQLite apply pending files inside the deploy lock transaction: if a later statement fails, none of that run's new ledger rows remain. MySQL and MariaDB cannot roll back InnoDB DDL (`CREATE TABLE`, `ALTER`, `CREATE INDEX`) — each statement autocommits. A failed file can leave tables without a matching `_neoorm_migrations` row. Recover locally with `neoorm migrate reset --force`, or in development with `neoorm migrate dev` catch-up. `GET_LOCK` is session-scoped and still serializes concurrent deploys; migration SQL does not run under a savepoint.
2412
2417
 
2413
2418
  ## Status
2414
2419
 
@@ -2593,9 +2598,9 @@ On a TTY, `neoorm init` opens a Clack wizard (provider, database URL, schema pat
2593
2598
 
2594
2599
  Options:
2595
2600
  - `--provider <provider>` — `postgresql` (default), `sqlite`, `mysql`, or `mariadb`. `postgres` and `pg` are aliases of `postgresql`. If omitted on a TTY, prompts to choose.
2596
- - `--database-url <url>` — override database URL / file path (default: `postgresql://postgres:postgres@localhost:5432/myapp` for postgres, `./dev.db` for sqlite, `mysql://root@localhost:3306/myapp` for mysql, `mariadb://root@localhost:3306/myapp` for mariadb)
2597
- - `--schema <path>` — schema file path (default: `./schema.ts`). Must end in `.ts`, `.mts`, or `.cts`.
2598
- - `--out <dir>` — generated output directory (default: `./neoorm`). Cannot be the same path as the schema file.
2601
+ - `--database-url <url>` — override database URL / file path (default: `postgresql://postgres:postgres@localhost:5432/myapp` for postgres, `./dev.db` for sqlite, `mysql://root@localhost:3306/myapp` for mysql, `mariadb://root@localhost:3306/myapp` for mariadb). Control characters are rejected. Quotes, whitespace, and backslashes are escaped in `neoorm.config.ts` and `.env.example`. When the provider is sqlite, a non-SQLite `scheme://` URL is rejected.
2602
+ - `--schema <path>` — schema file path (default: `./schema.ts`). Must end in `.ts`, `.mts`, or `.cts`, stay inside the project directory, and must not be `neoorm.config.ts`.
2603
+ - `--out <dir>` — generated output directory (default: `./neoorm`). Must stay inside the project directory, and cannot be the project directory, the schema file, or `neoorm.config.ts`.
2599
2604
  - `--force` — overwrite existing scaffold files without confirming
2600
2605
 
2601
2606
  ## `neoorm generate`
@@ -2815,7 +2820,7 @@ export default defineConfig({
2815
2820
  });
2816
2821
  ```
2817
2822
 
2818
- CLI commands load `.env` from the project directory before evaluating this file, so `process.env.DATABASE_URL` is set after `cp .env.example .env`. Variables already present in the environment are not overwritten. The generated client does not load `.env` at query time — use your runtime or a loader such as `node --env-file=.env`.
2823
+ CLI commands load `.env` from the project directory before evaluating this file, so `process.env.DATABASE_URL` is set after `cp .env.example .env`. `createNeoOrmClient` (including the generated `db`) does the same from `process.cwd()` before it picks a connection URL, so a later `.env` edit is used without regenerating. Variables already present in the environment are not overwritten. The URL stored on the manifest / `snapshot.json` is only the fallback when `DATABASE_URL` is unset.
2819
2824
 
2820
2825
  ## Options
2821
2826
 
@@ -2839,7 +2844,7 @@ Set `generate.zod` to write `out/zod.ts`, `generate.typebox` to write `out/typeb
2839
2844
 
2840
2845
  ### SQLite
2841
2846
 
2842
- Set `provider: "sqlite"` and `url` to a file path or `":memory:"`:
2847
+ Set `provider: "sqlite"` and `url` to a file path, a `file:` or `sqlite:` URI, or `":memory:"`. A `postgresql://`, `mysql://`, or other connection URL is rejected so it is not opened as a filename or silently dropped:
2843
2848
 
2844
2849
  ```ts
2845
2850
  datasource: {
@@ -2876,7 +2881,7 @@ If none is available, creating a client throws: `No SQLite driver available. Pro
2876
2881
 
2877
2882
  ## Configuration
2878
2883
 
2879
- Set `provider: "sqlite"` and point `url` at a file path or `:memory:`:
2884
+ Set `provider: "sqlite"` and point `url` at a file path, a `file:` or `sqlite:` URI, or `:memory:`. A `postgresql://`, `mysql://`, or other connection URL is rejected:
2880
2885
 
2881
2886
  ```ts
2882
2887
  // neoorm.config.ts
@@ -2920,6 +2925,8 @@ const db = createNeoOrmClient(manifest, {
2920
2925
 
2921
2926
  `busyTimeout` can also be a millisecond wait (`sqlite: { busyTimeout: 10_000 }`).
2922
2927
 
2928
+ SQLite runs `search`/`REGEXP` patterns in-process as JavaScript `RegExp`, so a catastrophic-backtracking pattern (e.g. `(a+)+$`) could freeze the whole process. neoorm rejects patterns that nest unbounded quantifiers; pass `sqlite: { unsafeAllowRegex: true }` to allow them anyway.
2929
+
2923
2930
  ### Custom driver
2924
2931
 
2925
2932
  Pass any object implementing `prepare(sql)`, `exec(sql)`, and `close()` — the `node:sqlite` and `bun:sqlite` APIs both match. Useful for sandboxed runtimes or existing database handles:
@@ -2955,7 +2962,7 @@ bunx neoorm migrate status
2955
2962
  bunx neoorm migrate reset --force
2956
2963
  ```
2957
2964
 
2958
- - The migration ledger table is `_neoorm_migrations` (`id INTEGER PRIMARY KEY AUTOINCREMENT`, `name`, `checksum`, `applied_at`). `migrate deploy` wraps the run in `BEGIN IMMEDIATE` and refuses an edited `migration.sql` whose checksum no longer matches the ledger.
2965
+ - The migration ledger table is `_neoorm_migrations` (`id INTEGER PRIMARY KEY AUTOINCREMENT`, `name`, `checksum`, `down_checksum`, `applied_at`). `migrate deploy` wraps the run in `BEGIN IMMEDIATE` and refuses an edited `migration.sql` or `down.sql` whose checksum no longer matches the ledger.
2959
2966
  - `migrate reset` drops all non-`sqlite_` tables (there is no schema concept).
2960
2967
  - `db pull` introspects `sqlite_master` back into a schema file.
2961
2968
 
@@ -3071,7 +3078,8 @@ bunx neoorm migrate status
3071
3078
  bunx neoorm migrate reset --force
3072
3079
  ```
3073
3080
 
3074
- - Deploy lock is `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy transaction.
3081
+ - Deploy lock is `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy connection.
3082
+ - InnoDB DDL autocommits. A failed `migrate deploy` can leave tables without a ledger row — use `migrate reset --force` locally or `migrate dev` catch-up. See [Migrations](migrations.md).
3075
3083
  - `migrate reset` sets `FOREIGN_KEY_CHECKS=0`, drops all tables in the current database, then re-enables checks and re-applies migrations.
3076
3084
  - `db pull` introspects `information_schema` back into a schema file.
3077
3085
 
@@ -3208,7 +3216,8 @@ bunx neoorm migrate status
3208
3216
  bunx neoorm migrate reset --force
3209
3217
  ```
3210
3218
 
3211
- - Deploy lock is `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy transaction.
3219
+ - Deploy lock is `GET_LOCK('neoorm.migrate.<db>', timeout)` / `RELEASE_LOCK` on the deploy connection.
3220
+ - InnoDB DDL autocommits. A failed `migrate deploy` can leave tables without a ledger row — use `migrate reset --force` locally or `migrate dev` catch-up. See [Migrations](migrations.md).
3212
3221
  - `migrate reset` sets `FOREIGN_KEY_CHECKS=0`, drops all tables in the current database, then re-enables checks and re-applies migrations.
3213
3222
  - `db pull` introspects `information_schema`. MariaDB `JSON` columns are often `LONGTEXT` plus a `json_valid()` CHECK; NeoOrm maps those back to `jsonb()`.
3214
3223
 
@@ -3387,6 +3396,91 @@ Each entry barrel starts with:
3387
3396
  - Document generated client output under `neoorm/client`.
3388
3397
  - Add runtime behavior changes alongside docstrings.
3389
3398
 
3399
+ ## `migrate dev` Workflow
3400
+
3401
+ This guide records the workflow contract and the implementation changes behind `neoorm migrate dev`. The refactor preserves the command's migration order and user-visible output timing.
3402
+
3403
+ ## Runtime contract
3404
+
3405
+ `runMigrateDev` derives `migrationsDir` from `outDir` and runs the complete sequence inside `withMigrateDevLock`:
3406
+
3407
+ 1. Read the snapshot, compile the target schema, reconcile pending `CREATE TABLE` migrations against the live database, then apply remaining pending migrations.
3408
+ 2. Generate from the current schema. If generation fails with the existing missing-migration-name error, no explicit name was supplied, and the CLI provided an interactive prompt callback, ask once and retry once. Other errors propagate unchanged. If generation needs no migration, it does not prompt.
3409
+ 3. Emit the generation summary and warnings, then reconcile a newly written migration against existing tables or apply it when reconciliation did not record it.
3410
+ 4. Return whether destructive changes were blocked; the CLI sets `process.exitCode` after the workflow completes.
3411
+
3412
+ The lock covers snapshot reading, both reconciliation/deployment phases, generation, and the optional prompt. Progress events keep the CLI output at the same stage as before: pending-migration output precedes a possible prompt, while generation output precedes post-generation reconciliation/application.
3413
+
3414
+ ## File-by-file changes
3415
+
3416
+ ### `src/migrate/dev-workflow.ts`
3417
+
3418
+ - **Before:** The ordered `migrate dev` sequence had no dedicated workflow module; the CLI path coordinated it.
3419
+ - **After:** `runMigrateDev` owns snapshot reading, initial reconciliation/deployment, generation, the optional one-shot prompt/retry, and post-generation reconciliation/deployment. A typed progress-event union reports completed stages, while existing migration and code-generation helpers remain responsible for their work. The migration directory is derived from `outDir`.
3420
+ - **Why it is useful:** The lock scope and ordering have one owner, and the workflow can be tested through a small interface without a CLI/TTY harness.
3421
+
3422
+ ### `src/bin/neoorm.ts`
3423
+
3424
+ - **Before:** The CLI command path contained the `migrate dev` orchestration alongside the separate `migrate deploy` path.
3425
+ - **After:** `migrate dev` calls `runMigrateDev`, adapts its progress events to the existing console output, supplies the prompt callback only for interactive runs, and handles the returned destructive-blocked status. `migrate deploy` remains on its separate path.
3426
+ - **Why it is useful:** Terminal interaction and presentation stay in the CLI, while moving orchestration does not delay or reorder output around the prompt.
3427
+
3428
+ ### `src/codegen/generate.ts`
3429
+
3430
+ - **Before:** The missing-migration-name predicate lived in the CLI even though both regular `generate` and `migrate dev` use it.
3431
+ - **After:** The same predicate lives beside `missingMigrationNameError` in the code-generation module and is shared by both callers.
3432
+ - **Why it is useful:** There is one definition of the narrow prompt-eligibility check; its error conditions are unchanged, not broadened into general error handling.
3433
+
3434
+ ### `test/migrate-dev-workflow.test.ts`
3435
+
3436
+ - **Before:** Existing tests covered migration, generation, and lock helpers separately, but not their ordering at the workflow boundary.
3437
+ - **After:** Real in-memory SQLite tests verify that a pending migration is applied and the lock remains held when the controlled name prompt runs, and that an unchanged schema completes without prompting or creating another migration.
3438
+ - **Why it is useful:** The regression coverage checks observable database state and timing rather than mocked helper forwarding or CLI wiring.
3439
+
3440
+ ### `docs/migrations.md`
3441
+
3442
+ - **Before:** The migration guide described command behavior but did not state the full `migrate dev` lock interval.
3443
+ - **After:** It documents that the lock starts before pending reconciliation and remains held through the optional name prompt, generation, and post-generation reconciliation/application; it links to this implementation guide.
3444
+ - **Why it is useful:** Readers can reason about concurrency and prompt timing from the documented contract.
3445
+
3446
+ ### `llms-full.txt`
3447
+
3448
+ - **Before:** The generated documentation aggregate did not include the updated lock-lifetime note or this guide.
3449
+ - **After:** Regeneration mirrors the migration-guide update and includes the new workflow page.
3450
+ - **Why it is useful:** The aggregate stays aligned with the source documentation instead of presenting stale workflow details.
3451
+
3452
+ ### `examples/blog/seed.ts`
3453
+
3454
+ - **Before:** The schema was imported as a runtime value even though it was used only for a type.
3455
+ - **After:** The import is type-only.
3456
+ - **Why it is useful:** TypeScript erases the import from emitted JavaScript, and lint no longer reports the type-only usage.
3457
+
3458
+ ### `docs/migrate-dev-workflow.md`
3459
+
3460
+ - **Before:** There was no durable, file-by-file record of the workflow ownership, preserved behavior, and verification.
3461
+ - **After:** This page records the execution contract, concrete before/after changes, and their rationale.
3462
+ - **Why it is useful:** Future maintenance can distinguish an ownership refactor from an intended behavior change.
3463
+
3464
+ ## Preserved behavior and scope
3465
+
3466
+ - Pending migrations are reconciled and applied before a missing name can be requested.
3467
+ - The prompt is limited to the existing missing-name condition and is attempted at most once; unchanged schemas do not prompt.
3468
+ - The migrate-dev lock remains held during the prompt and until post-generation reconciliation/application finishes.
3469
+ - The existing second schema compilation remains; this change does not optimize it.
3470
+ - `migrate deploy` keeps its separate execution path.
3471
+
3472
+ ## Verification
3473
+
3474
+ The implementation verification below was recorded before this documentation continuation; it was not rerun as part of the documentation-only changes:
3475
+
3476
+ - `bun run build` — passed.
3477
+ - `bun run test` — 128 files passed, 4 skipped; 1,215 tests passed, 42 skipped.
3478
+ - `bun run typecheck` and `bun run lint` — passed; lint was clean.
3479
+ - Focused migration suites — 4 files and 34 tests passed.
3480
+ - CLI fixture smoke — `migrate dev --name initial`, a no-name no-op `migrate dev`, and a no-op `migrate deploy` each exited 0; the SQLite database had the expected table and one applied ledger entry.
3481
+
3482
+ The generated documentation is refreshed with `bun run docs:llms` after editing this page.
3483
+
3390
3484
  ## Seeding
3391
3485
 
3392
3486
  `neoorm seed` runs a seed script against the database inside a single transaction. Any failure rolls the whole seed back, so failed runs are safe to retry.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "neoorm",
3
- "version": "0.9.6",
3
+ "version": "0.9.8",
4
4
  "description": "TypeScript-first PostgreSQL, SQLite, MySQL, and MariaDB ORM with schema DSL, codegen, and typed relations",
5
5
  "license": "MIT",
6
6
  "repository": {