@softure-ai/db 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+Newest first. Each version lists what changed for an app that uses `@softure-ai/db`. When an app has run a version in
+production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
+"Definition of done"). Versions before the first one below are described in their GitHub Releases (`db@x.y.z`).
+
+## 0.1.7
+
+- `createProcessDatabase(url, { schema, max })` returns `{ db, open, close, withDatabase, isOpen }`: a module-level,
+  synchronous `db` over the process-wide handle for the URL. A query before `open()` throws `Database is not open`;
+  `withDatabase(main)` opens, runs and closes for a script. `url` may be a function, read on `open()` (#313).
+- `findDriverError(error)` (`{ code, constraint, message }` of the Postgres error under drizzle's wrapper) and
+  `isConstraintViolation(error, { code, constraint })`, so apps and modules stop copying them (#313).
+- `closeSharedDatabase(url)` closes and forgets one shared handle.
+
+## 0.1.6
+
+- One database handle per process: `getConfiguredDatabase` opens the config's `database.handle` or URL once, and modules, health route and commands share it.
+- App migrations run around module migrations (`before` and `after` hooks).
+- Adoption: app baselines, `--adopt <module>@<version> --through <n>`, dependencies adopted first, and modules whose SQL references app tables (stub tables).
+- **Breaking:** `pg` and `@electric-sql/pglite` are optional peer dependencies, no longer dependencies. An app installs
+  the driver its `DATABASE_URL` uses and lists `"@softure-ai/db"` and that driver in `serverExternalPackages`
+  ([README §2](README.md#2-installation)); a URL whose driver is missing fails with a message naming the package.
+- A migrate bundle keeps drizzle's driver adapters external (`--external:drizzle-orm/pglite`,
+  `--external:drizzle-orm/node-postgres`).

package/README.md

@@ -1,16 +1,15 @@
 # @softure-ai/db
 
-**Status:** wave 0 · implemented in FD-4 (`db-migrator`), 0.1.5, prepared for its first release (the owner's tag, `scripts/release/README.md`).
-
 The database layer every SOFTURE module stands on. Standard:
-[docs/02-module-standard.md](../../docs/02-module-standard.md) §4. Sources in FIRE_TRACKER:
-`src/db/client.ts`, `src/db/test-db.ts`, `scripts/migrate.ts`, `docker/Dockerfile` (`migrate.cjs`).
+[docs/02-module-standard.md](../../docs/02-module-standard.md) §4.
 
 ## 1. What it provides
 
 A pg/PGlite client chosen by URL, a migrator that runs each module's SQL in the module's own
 Postgres schema (with a ledger, checksums, a lock, a dry run and adoption of existing tables),
-`createTestDatabase` for unit tests, and the `softure migrate` command.
+`createTestDatabase` for unit tests, the `softure migrate` command, a module-level process database
+(`createProcessDatabase`) and helpers that read the Postgres error behind a failed query
+(`findDriverError`, `isConstraintViolation`).
 
 ## 2. Installation
 
@@ -18,9 +17,49 @@ Postgres schema (with a ledger, checksums, a lock, a dry run and adoption of exi
 npm install @softure-ai/db drizzle-orm
 ```
 
-Node ≥ 22, ESM only. `drizzle-orm` (`^0.45.2`) is a peer dependency, so the app, the modules and
-this package share one drizzle. `pg` and `@electric-sql/pglite` come with the package and load
-only when used.
+Node ≥ 22, **ESM only**: module packages locate their migrations through `import.meta.url`, which a
+CJS bundle (esbuild `--format=cjs`) leaves empty, so `resolveMigrationsDir` throws naming the bundle
+format; the app script below also uses top-level await. Bundle migrate scripts with `--format=esm`.
+`drizzle-orm` (`^0.45.2`) is a peer dependency, so the app, the modules and
+this package share one drizzle.
+
+The drivers are optional peers: install the one the app's URL uses, and only that one goes into the
+app image. Each loads only when a URL needs it.
+
+```bash
+npm install pg                                   # postgres:// and postgresql://
+npm install @electric-sql/pglite                 # pglite:// (dev without a server)
+npm install -D @electric-sql/pglite              # a Postgres app's createTestDatabase, --adopt and baseline
+npm install -D @types/pg                         # only with skipLibCheck: false
+```
+
+| Needs | `pg` (`^8.11.0`) | `@electric-sql/pglite` (`^0.5.0`) |
+| --- | --- | --- |
+| `postgres://`, `postgresql://` | yes | no |
+| `pglite://` | no | yes |
+| `createTestDatabase` (`@softure-ai/db/testing`) | no | yes (dev) |
+| `softure migrate --adopt`, an app `baseline` (compare against a scratch PGlite) | URL's driver | yes |
+
+A URL whose driver is missing fails at the first connection: `createDatabase: postgres:// URLs need
+the "pg" package, which is not installed; …`, with Node's error as `cause`.
+
+**Next.js.** List this package and the driver in `serverExternalPackages`:
+
+```ts
+// next.config.ts
+const nextConfig: NextConfig = {
+  serverExternalPackages: ["@softure-ai/db", "pg"], // or "@electric-sql/pglite" for pglite://
+};
+```
+
+Bundled, the package's `import()` of each driver and drizzle adapter is resolved at build time, so
+`next build` fails with `Can't resolve '@electric-sql/pglite'` in an app without PGlite (drizzle's
+adapter imports it statically). External, it loads from `node_modules` at run time, and standalone
+output tracing follows the same imports, so `.next/standalone` carries the installed driver and
+drizzle and nothing else (the example app installs `pg` only:
+[`next.config.ts`](../../examples/next-app/next.config.ts)). The config and the shared handles live on `globalThis`, so this copy and the modules bundled next
+to it share them. Hiding the imports from the bundler instead (`turbopackIgnore`) builds, but
+tracing skips the driver and the image fails at the first query.
 
 ## 3. Configuration
 
@@ -42,11 +81,110 @@ await handle.close();
 ```
 
 - `DatabaseHandle` is `{ kind: "postgres", db, pool, close } | { kind: "pglite", db, client, close }`.
-- `Database` is the drizzle database of either driver; `Queryable` is a `Database` or an open
-  transaction, so one helper serves both (`db.transaction(async (tx) => helper(tx))`).
+- `Database<TSchema>` is the drizzle database of either driver; `Queryable<TSchema>` is a `Database`
+  or an open transaction, so one helper serves both (`db.transaction(async (tx) => helper(tx))`).
+  Without a type argument both accept any schema, so an app database made with
+  `drizzle({ client, schema })`, and its transactions, pass to module functions as they are.
 - An unsupported scheme throws, naming the scheme only; the URL (and its password) is never
   printed.
 
+### One handle per process
+
+Modules open their database through the config, never on their own: the app's handle when
+`database.handle` is set, otherwise one process-wide handle per URL (`getSharedDatabase(url)`). An
+app that also has its own client must make sure both are the same handle. A second handle is a second
+pool on Postgres; on `pglite://` it is a second PGlite instance on the same directory, which corrupts
+it without an error (the next open fails with `could not locate a valid checkpoint record`).
+
+**Either** hand the app's client to the config. The function is called on first use, never while the
+config is defined (a build does not connect), and must return the app's one handle:
+
+```ts
+// db/client.ts: the app's own client, memoized: `next dev` re-evaluates modules on every change
+import { PGlite } from "@electric-sql/pglite";
+import { createPgliteHandle, createPostgresHandle, type DatabaseHandle } from "@softure-ai/db";
+import pg from "pg";
+
+const cache = globalThis as typeof globalThis & { appDatabase?: Promise<DatabaseHandle> };
+
+export function getAppDatabase(url: string): Promise<DatabaseHandle> {
+  cache.appDatabase ??= url.startsWith("pglite://")
+    ? createPgliteHandle(new PGlite(url.slice("pglite://".length)))
+    : createPostgresHandle(new pg.Pool({ connectionString: url }).on("error", () => undefined));
+  return cache.appDatabase;
+}
+
+// softure.config.ts
+const url = process.env.DATABASE_URL ?? "";
+defineSoftureConfig({ database: { url, handle: () => getAppDatabase(url) }, /* … */ });
+```
+
+Every module adapter, the ops health route, `softure migrate` (and the app's migration hooks it
+runs), `softure-blog`, `softure-mail` and ops scripts then use that handle; a command closes it
+when it is done, which writes a `pglite://` directory back.
+
+**Or** build the app's typed drizzle instance over the shared handle, so there is nothing to hand
+over:
+
+```ts
+import { getSharedDatabase } from "@softure-ai/db";
+import { drizzle as drizzlePg } from "drizzle-orm/node-postgres";
+import { drizzle as drizzlePglite } from "drizzle-orm/pglite";
+import * as schema from "./schema";
+
+export async function getDb() {
+  const handle = await getSharedDatabase(config.database.url);
+  return handle.kind === "postgres" ? drizzlePg({ client: handle.pool, schema }) : drizzlePglite({ client: handle.client, schema });
+}
+```
+
+`getConfiguredDatabase(config.database)` is what modules call; app code that needs the database
+the modules use can call it too. A migration run on a PGlite handle the app shares keeps the app's
+session settings (`TimeZone`, `search_path`); only what the run changed is put back.
+
+### A module-level `db`
+
+An app whose code imports one `db` everywhere, instead of awaiting a handle in each function,
+creates it once with `createProcessDatabase`. `db` stands in for the shared handle's drizzle instance
+(the one `getSharedDatabase(url)` gives the modules, so there is still one pool); every entry point
+opens it first, and a query before that throws `Database is not open`:
+
+```ts
+// db/index.ts
+import { createProcessDatabase } from "@softure-ai/db";
+import * as schema from "./schema";
+
+// A function: read on open(), so a script may load its environment after importing this file.
+export const { db, open, close, withDatabase } = createProcessDatabase(() => process.env.DATABASE_URL ?? "", { schema });
+
+// instrumentation.ts (the server): open once at startup
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") await (await import("./db")).open();
+}
+
+// scripts/import.ts: opens, runs, closes (also when main throws)
+await withDatabase(async (db) => { /* … */ });
+```
+
+`open()` is idempotent; `close()` closes the shared handle for that URL, which the modules use too,
+so only a script's end calls it. With `schema`, `db.query.<table>` is typed and works.
+
+### Driver errors
+
+`findDriverError(error)` returns `{ code, constraint, message }` of the Postgres error behind a failed
+query (node-postgres and PGlite alike; drizzle wraps it as the `cause`), or `undefined`.
+`isConstraintViolation(error, { code, constraint })` answers whether it is that SQLSTATE on that
+constraint (any constraint when `constraint` is left out):
+
+```ts
+try {
+  await db.insert(articles).values(article);
+} catch (error) {
+  if (!isConstraintViolation(error, { code: "23505", constraint: "articles_slug_key" })) throw error;
+  return err("slug_taken");
+}
+```
+
 ## 4. Mounting
 
 Nothing to mount. Migrations run as a deploy step:
@@ -69,31 +207,117 @@ process.exitCode = await runMigrateCli({ config, argv: process.argv.slice(2) });
 # build stage: copy each module's SQL next to the bundle, then bundle the runner
 RUN npx tsx scripts/migrate.ts --export-migrations ./softure-migrations
 RUN npx esbuild scripts/migrate.ts --bundle --platform=node --format=esm --target=node22 \
-      --external:pg --external:@electric-sql/pglite --outfile=migrate.mjs
-# run stage (needs pg, and @electric-sql/pglite for --adopt)
+      --external:pg --external:@electric-sql/pglite \
+      --external:drizzle-orm/pglite --external:drizzle-orm/node-postgres --outfile=migrate.mjs
+# run stage (needs the URL's driver, and @electric-sql/pglite for --adopt or an app baseline)
 COPY --from=builder /app/migrate.mjs ./migrate.mjs
 COPY --from=builder /app/softure-migrations ./softure-migrations
 CMD ["node", "migrate.mjs", "--migrations-dir", "./softure-migrations"]
 ```
 
+A config that imports `server-only` throws under plain Node: run the export as
+`npx tsx --conditions=react-server scripts/migrate.ts --export-migrations …` and bundle with
+`--alias:server-only=./scripts/empty.mjs` (an empty file). Path aliases (`@/…`) need nothing extra: tsx and
+esbuild both read `paths` from `tsconfig.json`. The [ops container recipe](../../modules/ops/README.md#container-recipe)
+uses the same commands.
+
+The drivers and drizzle's two driver adapters stay external: bundled, the adapter of a driver the app
+does not install imports it at the top of `migrate.mjs`, which then fails at start. At run time they
+come from the standalone output, which carries the installed driver and its adapter.
+
 A bundle cannot find package folders (`import.meta.url` points at the bundle), hence
-`--export-migrations` at build time and `--migrations-dir` at run time. The ledger's own migration
+`--export-migrations` at build time and `--migrations-dir` at run time. The build stage needs no
+`DATABASE_URL`: the config accepts an empty `database.url` (`DATABASE_URL ?? ""`) and only a command that
+connects refuses it. The ledger's own migration
 ships as code.
 
+**The app's own migrations** run in the same step, through hooks. `before` runs ahead of the module
+files (app tables a module references, normally the app's whole history), `after` behind them (app
+migrations that reference a table a module creates). With drizzle, define them once and pass the same
+object to the migrate script and to `createTestDatabase`:
+
+```ts
+// db/app-migrations.ts
+import type { AppMigrations, DatabaseHandle } from "@softure-ai/db";
+
+async function runDrizzle(handle: DatabaseHandle, migrationsFolder: string): Promise<void> {
+  if (handle.kind === "postgres") {
+    const { migrate } = await import("drizzle-orm/node-postgres/migrator");
+    await migrate(handle.db, { migrationsFolder });
+  } else {
+    const { migrate } = await import("drizzle-orm/pglite/migrator");
+    await migrate(handle.db, { migrationsFolder });
+  }
+}
+
+export const appMigrations: AppMigrations = {
+  before: (handle) => runDrizzle(handle, "./drizzle"),
+  // only when an app migration needs a module table: a second drizzle folder
+  // after: (handle) => runDrizzle(handle, "./drizzle-after"),
+};
+
+// scripts/migrate.ts
+process.exitCode = await runMigrateCli({ config, argv: process.argv.slice(2), app: appMigrations });
+```
+
+- Order of a run: the ledger, `before`, the module files in dependency order, `after`. Everything
+  runs under the migration lock, after every module file passed its checks; nothing runs when a check
+  fails. The hooks run on every run, so they must skip what they already applied (drizzle does).
+- A hook that throws is reported as `db.app_migration_failed` with the error and its causes (drizzle
+  puts the Postgres message in `cause`). A failing `before` stops the run before any module file; a
+  failing `after` leaves the module files applied.
+- `--plan` runs no hook (it says so); `--adopt` without `--plan` runs `before` first, so the app
+  migration that moves a table into the module's schema and the adoption are one command.
+
+**A baseline: fresh databases after an adoption.** The app keeps its old migrations, so every fresh
+database (the unit-test template, an integration stack, a reset dev database) recreates the tables it
+moved into a module's schema before the module files run. `baseline` names, per module, the last module
+file the app's own history creates; `migrate` then adopts or migrates by itself, on every database:
+
+```ts
+export const appMigrations: AppMigrations = {
+  before: (handle) => runDrizzle(handle, "./drizzle"),
+  // the app's history creates auth's 0001 (users, sessions); 0002.. are new to it
+  baseline: { auth: 1 },
+};
+```
+
+- For a listed module the ledger has never seen, after `before` and after the modules it depends on:
+  an empty schema is migrated normally; otherwise the schema is compared with what files 1..n create
+  (as `--adopt` does), files 1..n are recorded as `adopted` and the later files are applied. A
+  difference stops the run (`db.schema_mismatch`, every difference printed); nothing of that module is
+  recorded and `after` does not run.
+- Once the module is in the ledger the entry has no effect, so the same command serves every deploy.
+  Keep the number when the module ships new files: it describes the app's history, which no longer
+  changes.
+- Only a prefix 1..n can be adopted (the ledger refuses a file numbered below an applied one): when the
+  app's tables already carry a later file's change, align them in the app's own migration or raise n.
+- A module that is not enabled, has no schema, or an n outside 1..files refuses the run before anything
+  runs. `--plan` marks the files a baseline may adopt (`adopted if its schema already holds objects`).
+- The comparison builds the reference on a scratch PGlite, only when a module is actually adopted,
+  with stubs of the app tables `before` created (section 5, adoption).
+- Under node-postgres a hook queries through the pool while the migrator holds one connection, so the
+  pool needs at least two (`createDatabase`'s default is 10).
+- The `softure` bin reads only the config; an app with its own migrations uses the script above.
+- In a bundle, the drizzle folder must be copied next to the bundle, as the module files are.
+
 **Options of `softure migrate`:**
 
 | Option | Effect |
 | --- | --- |
 | (none) | apply every pending migration |
 | `--plan` | print what would be applied (or adopted); change nothing |
-| `--adopt <module>@<version>` | record an existing schema as migrated after comparing it (section 5) |
+| `--adopt <module>@<version>` | record an existing schema as migrated after comparing it, after applying the pending migrations of its dependencies (section 5) |
+| `--through <n>` | with `--adopt`: adopt files 1..n only; the next migrate applies the rest |
 | `--migrations-dir <dir>` | read module files from `<dir>/<module id>/` |
 | `--export-migrations <dir>` | copy module files to `<dir>/<module id>/` and exit; needs no database; replaces older `.sql` copies and refuses a module folder holding anything else |
 
 Exit codes: 0 done, 1 a problem or failure (each printed on stderr), 2 a usage error.
 
-The same operations as functions: `migrate(handle, { modules, migrationsDir?, onApplied? })`,
-`planMigrations(handle, { modules })`, `adoptModule(handle, { modules, module, version, dryRun? })`,
+The same operations as functions: `migrate(handle, { modules, migrationsDir?, app?, onApplied?, onAdopted?, onAppMigrated? })`
+(`runAppMigrations(handle, app, phase)` runs one hook alone under the lock),
+`planMigrations(handle, { modules, app? })` (`pending`, and `baseline`: the pending files a baseline may adopt),
+`adoptModule(handle, { modules, module, version, through?, dryRun? })`,
 `exportMigrations(modules, dir)`. Each returns `{ ok: true, value } | { ok: false, error, problems }`;
 `describeProblem(problem)` gives the English line.
 
@@ -118,16 +342,16 @@ module_version, method ('applied' | 'adopted'), applied_at`, primary key `(modul
   `SET LOCAL search_path TO <schema>, public` first. Name other modules' tables with their schema
   (`REFERENCES notes.notes (id)`), and create extensions `WITH SCHEMA public`.
 
-**Each run:** modules in dependency order (`sortModulesByDependencies`), files in number order.
+**Each run:** the ledger, the app's `before` hook, modules in dependency order (`sortModulesByDependencies`), files in number order.
 Before anything runs, every file of every module is checked: an applied file that was edited or
 renamed (`db.migration_changed`), deleted (`db.migration_missing`), or a new file numbered below an
 applied one (`db.migration_out_of_order`) refuses the whole run. The run holds a session-level
 `pg_advisory_lock`, so a second runner waits, then finds nothing to do. A failing file is rolled
 back completely and stops the run; the files before it stay applied. The migration connection is
-closed after the run, never returned to the pool.
+closed after the run, never returned to the pool. The app's `after` hook runs last (section 4).
 
 **Refused modules:** the id `softure`; the schemas `softure`, `public`, `information_schema`,
-`pg_*` and names over 63 bytes; migrations without a `dbSchema`.
+`drizzle` (drizzle's ledger in every app), `pg_*` and names over 63 bytes; migrations without a `dbSchema`.
 
 **Adoption** ([docs/05](../../docs/05-adoption-playbook.md) step 3): after the app's own migration
 moved its tables into the module's schema, `--adopt <module>@<version>` (with `--plan` first)
@@ -136,14 +360,26 @@ one through `pg_catalog`: relations (and whether they are unlogged), columns (ty
 not null, default, identity, generated), sequences with their parameters, constraints and indexes
 (names and definitions), triggers, functions, and enum, domain, range and composite types. Only an
 exact match records the files as `adopted`; every difference is printed (`missing in database: …`,
-`unexpected in database: …`). The version must equal the enabled module's, the module must be new
-to the ledger, and the modules it depends on must be fully migrated or adopted first. Undo:
+`unexpected in database: …`). `--through <n>` compares with and adopts files 1..n only; the next
+migrate applies the rest. The version must equal the enabled module's and the module must be new to
+the ledger. The pending migrations of the modules it depends on are applied first (listed as
+`apply` lines; a dry run applies nothing); when one fails because its tables exist too, adopt that
+module first. Module SQL may reference the app's own tables (`REFERENCES public.app_users (id)`):
+the scratch database first gets stubs of every table outside the ledger, the enabled modules'
+schemas and `drizzle`, copied from the live database (columns with their types, primary keys,
+unique constraints, plain unique indexes and the enum types they use; no defaults, NOT NULL, checks
+or foreign keys). The tables must therefore exist when the comparison runs: `--adopt` and a baseline
+run `before` first, a `--plan` dry run reads only what is already there. A stub that cannot be
+created (a domain or extension type) is skipped, and named in the failure when the module needs it.
+For fresh databases of an app that adopted a module, declare a baseline (section 4). Undo:
 `DELETE FROM softure.migrations WHERE module = '<id>' AND method = 'adopted'`.
 
 **Tests:** `createTestDatabase(modules)` from `@softure-ai/db/testing` returns `{ db, client, close }`:
 an in-memory PGlite with the ledger and the listed modules migrated (list the module and the
 modules it depends on). Each module set is migrated once per test worker and copied per call; a
-broken migration throws naming the file.
+broken migration throws naming the file. An app with its own migrations passes the same hooks,
+`createTestDatabase(modules, { app: appMigrations })`, so module tables can reference app tables; the
+template is cached per hook object, so import the shared object rather than writing hooks inline.
 
 ```ts
 import { createTestDatabase } from "@softure-ai/db/testing";
@@ -187,4 +423,7 @@ No personal data. The ledger holds module ids, file names and checksums.
   transaction-mode PgBouncer.
 - Adoption does not compare grants, comments, column order, row-level security policies or view
   bodies, and needs PGlite installed where it runs (also in an image that otherwise uses `pg`).
+- The app table stubs of the reference carry no domains, extension types, views or functions: a
+  module whose SQL needs one of those from the app cannot be adopted (`db.adopt_reference_failed`
+  names the skipped stub objects).
 - No cached connection for Next.js dev reloads yet; the Next adapter (identity ID-1, FD-7) adds it.

package/dist/cli/run.d.ts

@@ -1,4 +1,5 @@
 import type { SoftureConfig } from "@softure-ai/core";
+import { type AppMigrations } from "../migrations/migrator.js";
 export interface CliOutput {
     readonly log: (line: string) => void;
     readonly error: (line: string) => void;
@@ -10,11 +11,17 @@ export interface RunMigrateCliOptions {
     /** Relative paths resolve against it. Default: `process.cwd()`. */
     readonly cwd?: string;
     readonly output?: CliOutput;
+    /**
+     * The app's own migrations: migrate runs `before`, the module files (adopting `baseline` where
+     * it applies), then `after`; `--adopt` (without `--plan`) runs `before` first; `--plan` runs no
+     * hook and marks the files a baseline may adopt.
+     */
+    readonly app?: AppMigrations;
 }
 export declare const EXIT_OK = 0;
 export declare const EXIT_FAILED = 1;
 export declare const EXIT_USAGE = 2;
-export declare const MIGRATE_USAGE = "Usage: softure migrate [options]\n\nApplies the SQL migrations of every enabled module, each in its own schema.\n\nOptions:\n  --plan                        show what would be applied (or adopted) and change nothing\n  --adopt <module>@<version>    record an existing schema as migrated, after comparing it\n  --migrations-dir <dir>        read module files from <dir>/<module id>/ (bundled runners)\n  --export-migrations <dir>     copy module files to <dir>/<module id>/ and exit (build stage)\n  --help                        show this help";
+export declare const MIGRATE_USAGE = "Usage: softure migrate [options]\n\nApplies the SQL migrations of every enabled module, each in its own schema.\n\nOptions:\n  --plan                        show what would be applied (or adopted) and change nothing\n  --adopt <module>@<version>    record an existing schema as migrated, after comparing it;\n                                applies the pending migrations of its dependencies first\n  --through <n>                 with --adopt: adopt files 1..n only, leave the rest to migrate\n  --migrations-dir <dir>        read module files from <dir>/<module id>/ (bundled runners)\n  --export-migrations <dir>     copy module files to <dir>/<module id>/ and exit (build stage)\n  --help                        show this help";
 /** Runs the command and returns the process exit code: 0 done, 1 failed, 2 usage error. */
 export declare function runMigrateCli(options: RunMigrateCliOptions): Promise<number>;
 //# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAOtD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;IAC7D,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,eAAO,MAAM,aAAa,oiBASqB,CAAC;AAehD,2FAA2F;AAC3F,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0ClF"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKtD,OAAO,EAA6C,KAAK,aAAa,EAAsB,MAAM,2BAA2B,CAAC;AAG9H,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;IAC7D,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,eAAO,MAAM,aAAa,+tBAWqB,CAAC;AAehD,2FAA2F;AAC3F,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClF"}

package/dist/cli/run.js

@@ -5,13 +5,15 @@
 //   import { runMigrateCli } from "@softure-ai/db/cli";
 //   import config from "../softure.config";
 //   process.exitCode = await runMigrateCli({ config, argv: process.argv.slice(2) });
+//
+// An app with its own migrations passes them as `app: { before, after }` (see MigrateOptions.app).
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { pathToFileURL } from "node:url";
-import { createDatabase } from "../client.js";
+import { openCommandDatabase } from "../configured.js";
 import { adoptModule } from "../migrations/adopt.js";
 import { exportMigrations } from "../migrations/export.js";
-import { migrate, planMigrations } from "../migrations/migrator.js";
+import { migrate, planMigrations, runAppMigrations } from "../migrations/migrator.js";
 import { describeProblem } from "../migrations/problems.js";
 export const EXIT_OK = 0;
 export const EXIT_FAILED = 1;
@@ -22,7 +24,9 @@ Applies the SQL migrations of every enabled module, each in its own schema.
 
 Options:
   --plan                        show what would be applied (or adopted) and change nothing
-  --adopt <module>@<version>    record an existing schema as migrated, after comparing it
+  --adopt <module>@<version>    record an existing schema as migrated, after comparing it;
+                                applies the pending migrations of its dependencies first
+  --through <n>                 with --adopt: adopt files 1..n only, leave the rest to migrate
   --migrations-dir <dir>        read module files from <dir>/<module id>/ (bundled runners)
   --export-migrations <dir>     copy module files to <dir>/<module id>/ and exit (build stage)
   --help                        show this help`;
@@ -52,22 +56,24 @@ export async function runMigrateCli(options) {
         result.value.forEach((step) => output.log(`exported ${formatStep(step)}`));
         return EXIT_OK;
     }
-    const url = options.config.database?.url;
-    if (url === undefined) {
+    const database = options.config.database;
+    if (database === null) {
         output.error("softure migrate: the config has no database; set database.url in softure.config");
         return EXIT_FAILED;
     }
-    let handle;
+    let opened;
     try {
-        handle = await createDatabase(url);
+        // The app's configured handle when it set one, so the app's hooks and the run share one instance.
+        opened = await openCommandDatabase(database);
     }
     catch (error) {
         output.error(`softure migrate: ${describeError(error)}`);
         return EXIT_FAILED;
     }
+    const { handle } = opened;
     try {
         const migrationsDir = command.migrationsDir === undefined ? undefined : pathToFileURL(`${resolve(cwd, command.migrationsDir)}/`);
-        return await runDatabaseCommand(handle, { command, modules: options.config.modules, migrationsDir, output });
+        return await runDatabaseCommand(handle, { command, modules: options.config.modules, migrationsDir, output, app: options.app ?? {} });
     }
     catch (error) {
         // Connection and driver errors: the message only, never a stack or the database URL.
@@ -75,34 +81,61 @@ export async function runMigrateCli(options) {
         return EXIT_FAILED;
     }
     finally {
-        await handle.close();
+        await opened.close();
     }
 }
 async function runDatabaseCommand(handle, input) {
-    const { command, modules, output } = input;
+    const { command, modules, output, app } = input;
     const dirOption = input.migrationsDir === undefined ? {} : { migrationsDir: input.migrationsDir };
+    const hasAppMigrations = app.before !== undefined || app.after !== undefined;
+    if (command.plan && hasAppMigrations) {
+        output.log("app migrations: not planned; the app runs them itself on migrate");
+    }
     if (command.kind === "adopt") {
-        const result = await adoptModule(handle, { modules, module: command.module, version: command.version, dryRun: command.plan, ...dirOption });
+        if (!command.plan) {
+            const before = await runAppMigrations(handle, app, "before");
+            if (!before.ok)
+                return reportFailure(output, before);
+            if (before.value.ran)
+                output.log("applied app migrations (before)");
+        }
+        const result = await adoptModule(handle, {
+            modules,
+            module: command.module,
+            version: command.version,
+            dryRun: command.plan,
+            ...(command.through === undefined ? {} : { through: command.through }),
+            ...dirOption,
+        });
         if (!result.ok)
             return reportFailure(output, result);
         const verb = command.plan ? "would" : "did";
-        result.value.ledger.forEach((step) => output.log(`${verb} apply ${formatStep(step)}`));
+        [...result.value.ledger, ...result.value.dependencies].forEach((step) => output.log(`${verb} apply ${formatStep(step)}`));
         result.value.adopted.forEach((step) => output.log(`${verb} adopt ${formatStep(step)}`));
-        output.log(`${command.module}@${command.version}: the schema matches its migrations${command.plan ? " (plan only, nothing written)" : "; adopted"}`);
+        const scope = command.through === undefined ? "" : ` through ${formatVersion(command.through)}`;
+        output.log(`${command.module}@${command.version}: the schema matches its migrations${scope}${command.plan ? " (plan only, nothing written)" : "; adopted"}`);
         return EXIT_OK;
     }
     if (command.plan) {
-        const result = await planMigrations(handle, { modules, ...dirOption });
+        const result = await planMigrations(handle, { modules, ...dirOption, app });
         if (!result.ok)
             return reportFailure(output, result);
-        result.value.pending.forEach((step) => output.log(`pending ${formatStep(step)}`));
+        const baseline = new Set(result.value.baseline);
+        result.value.pending.forEach((step) => output.log(`pending ${formatStep(step)}${baseline.has(step) ? " (adopted if its schema already holds objects)" : ""}`));
         output.log(result.value.pending.length === 0 ? "nothing to apply" : `${result.value.pending.length} migration(s) to apply`);
         return EXIT_OK;
     }
-    const result = await migrate(handle, { modules, ...dirOption, onApplied: (step) => output.log(`applied ${formatStep(step)}`) });
+    const result = await migrate(handle, {
+        modules,
+        ...dirOption,
+        app,
+        onApplied: (step) => output.log(`applied ${formatStep(step)}`),
+        onAdopted: (step) => output.log(`adopted ${formatStep(step)}`),
+        onAppMigrated: (phase) => output.log(`applied app migrations (${phase})`),
+    });
     if (!result.ok)
         return reportFailure(output, result);
-    output.log(result.value.applied.length === 0 ? "nothing to apply" : `${result.value.applied.length} migration(s) applied`);
+    output.log(formatSummary(result.value.applied.length, result.value.adopted.length));
     return EXIT_OK;
 }
 function parseCommand(argv) {
@@ -113,6 +146,7 @@ function parseCommand(argv) {
             options: {
                 plan: { type: "boolean" },
                 adopt: { type: "string" },
+                through: { type: "string" },
                 "migrations-dir": { type: "string" },
                 "export-migrations": { type: "string" },
                 help: { type: "boolean" },
@@ -128,26 +162,42 @@ function parseCommand(argv) {
         return { kind: "help" };
     const exportDir = values["export-migrations"];
     if (exportDir !== undefined) {
-        const others = ["plan", "adopt", "migrations-dir"].filter((name) => values[name] !== undefined);
+        const others = ["plan", "adopt", "through", "migrations-dir"].filter((name) => values[name] !== undefined);
         return others.length > 0 ? `--export-migrations cannot be combined with --${others.join(", --")}` : { kind: "export", targetDir: exportDir };
     }
     const plan = values.plan === true;
     const migrationsDir = values["migrations-dir"];
     if (values.adopt === undefined) {
-        return { kind: "migrate", plan, migrationsDir };
+        return values.through === undefined ? { kind: "migrate", plan, migrationsDir } : "--through needs --adopt <module>@<version>";
     }
     const match = ADOPT_TARGET.exec(values.adopt);
     if (match?.[1] === undefined || match[2] === undefined) {
         return `--adopt expects <module>@<x.y.z>, e.g. auth@0.1.0, got "${values.adopt}"`;
     }
-    return { kind: "adopt", plan, module: match[1], version: match[2], migrationsDir };
+    const through = values.through === undefined ? undefined : parseThrough(values.through);
+    if (through === null) {
+        return `--through expects a positive whole number, got "${values.through ?? ""}"`;
+    }
+    return { kind: "adopt", plan, module: match[1], version: match[2], through, migrationsDir };
+}
+/** A positive whole number written in digits, or null. */
+function parseThrough(text) {
+    return /^[1-9]\d*$/.test(text) ? Number(text) : null;
 }
 function reportFailure(output, failure) {
     failure.problems.forEach((problem) => output.error(describeProblem(problem)));
     return EXIT_FAILED;
 }
 function formatStep(step) {
-    return `${step.module} ${String(step.version).padStart(4, "0")}_${step.name}.sql`;
+    return `${step.module} ${formatVersion(step.version)}_${step.name}.sql`;
+}
+function formatVersion(version) {
+    return String(version).padStart(4, "0");
+}
+function formatSummary(applied, adopted) {
+    if (applied === 0 && adopted === 0)
+        return "nothing to apply";
+    return adopted === 0 ? `${applied} migration(s) applied` : `${applied} migration(s) applied, ${adopted} adopted`;
 }
 function describeError(error) {
     return error instanceof Error ? error.message : String(error);