migrane 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eishexac <hexac@existin.space>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,425 @@
+# migrane
+
+A SQL migration runner that knows nothing about your application.
+
+It is handed a driver and a list of directories. That is all it knows — no ORM,
+no container, no module registry, no dependency it makes you adopt. The package
+itself has no runtime dependencies. Everything specific to an application lives
+in that application's config file.
+
+```sh
+pnpm add -D migrane
+pnpm add pg        # only if you use the bundled postgres driver
+```
+
+```ts
+// database/config.ts
+import { defineConfig } from 'migrane';
+import { pgDriver } from 'migrane/drivers/pg';
+
+export default defineConfig({
+  dirs: ['./migrations'],
+  seeds: './seeders',
+  manifest: './manifest.gen.ts', // only if you ship a container
+  driver: () => pgDriver(process.env.DATABASE_URL!),
+});
+```
+
+```sh
+migrane up | down | status
+migrane reset | fresh [unit]
+migrane seed <unit> | unseed <unit>
+migrane manifest [--out <path>]
+```
+
+Config is looked for at `database/config.ts`, then `migrate.config.{ts,js,mjs}`,
+or wherever `--config` points. Paths in it resolve against the config file, not
+the working directory, so the commands answer the same from anywhere in a
+repository.
+
+## Runtimes
+
+The published package is plain ES modules; the interesting question is who runs
+_your_ config and migrations, because both may be TypeScript and the CLI loads
+them with `import()`.
+
+The executable answers it without being told. Its shebang names `sh`, and the
+first line `exec`s the first of **node** then **bun** that is on `PATH` — so a
+machine holding only bun runs it, and a machine holding node behaves exactly as
+it always did.
+
+- **node ≥ 22.18** strips types natively — `migrane up` just works.
+- **bun** always ran TypeScript, and is taken when node is absent. To take it on
+  a machine that has both, name it per command with `migrane --runtime=bun up`,
+  or for the shell with `MIGRANE_RUNTIME=bun migrane up`. The flag wins, and
+  must come first — it is read by the executable before any of this package
+  runs, and never reaches the command surface.
+  Node is preferred by default because **bun loads `.env` from the working
+  directory and node does not** — and bun reads it from where you _ran_ the
+  command, while everything else here resolves against the config file. A
+  variable already set in the environment still wins, so in CI or a container
+  both runtimes reach the same database; the difference shows up on a laptop,
+  where `cd apps/api && migrane up` can pick up a different `.env` than the
+  repository root. `bun --no-env-file` turns that off, for a project that wants
+  bun without it.
+- **older node** works when the config is `.js` and the migrations are `.sql`.
+- **Windows** gets a `.cmd` shim that calls `sh`, which Git Bash provides.
+- **Any of them, without the executable:** `run()` is exported, and
+  `process.exit(await run(process.argv.slice(2)))` in a `scripts/db.ts` of your
+  own is the whole CLI under whatever runtime you like.
+
+## Writing a migration
+
+A migration is `<number>-<slug>.ts`, `<number>-<slug>.sql`, or a directory of
+that name. `001-initial` and `20260826143000-add-products` both work and can be
+mixed, because ordering compares the number itself — `9-` sorts before `10-`
+without anyone zero-padding.
+
+```ts
+import type { Part } from 'migrane';
+
+export const up: Part['up'] = async ({ sql }) => {
+  await sql`CREATE TABLE users (id uuid PRIMARY KEY, email text NOT NULL)`;
+};
+
+export const down: Part['down'] = async ({ sql }) => {
+  await sql`DROP TABLE users`;
+};
+```
+
+`down` is optional. A great many migrations have no honest reverse, and a
+required one only ever gets an empty body that lies about being reversible.
+
+### The `sql` tag
+
+Interpolations become **bind parameters**:
+
+```ts
+await sql`INSERT INTO users (email) VALUES (${email})`; // → $1
+```
+
+DDL is mostly things that cannot be parameters, so the escape is explicit and
+visible in a diff:
+
+|                       |                                                     |
+| --------------------- | --------------------------------------------------- |
+| `sql.raw(text)`       | splice verbatim                                     |
+| `sql.id(name)`        | quote an identifier — `sql.id('order')` → `"order"` |
+| `sql.join(fragments)` | a column list, a set of constraints                 |
+
+A template that interpolates **nothing** sends no parameters, and may therefore
+carry several statements separated by `;` — PostgreSQL only restricts a request
+to one statement once a bind parameter is present.
+
+### Directory migrations
+
+A directory is one migration made of parts. Two ways to order them, and the
+choice is per directory:
+
+**An `index.ts` is the migration.** The array it composes is the order, read top
+to bottom in one place, and the files need no prefixes:
+
+```
+001-initial/
+├── index.ts          compose([extensions, users, devices])
+├── pg/extensions.ts
+└── tables/users.ts, devices.ts
+```
+
+```ts
+export const { up, down } = compose([extensions, users, devices]);
+```
+
+Order is _data_ here, not import order — which is what makes it survive an IDE
+reordering the imports above it.
+
+**Without an index**, every `.ts`/`.sql` file under the directory is composed in
+path order, and the numbers carry the order:
+
+```
+001-initial/
+├── 010-pg/010-extensions.ts
+└── 020-tables/010-users.ts
+```
+
+Either way `up` runs forwards and `down` in reverse, so foreign keys hold in
+both directions — and either way the checksum covers **every file**, including
+parts only an index imports.
+
+### `.sql` migrations
+
+```sql
+-- migrate:up
+CREATE TABLE users (id uuid PRIMARY KEY);
+
+-- migrate:down
+DROP TABLE users;
+```
+
+Each section is sent as one statement. Splitting on `;` would be wrong the first
+time a function body or a quoted string contained one.
+
+## What it guarantees
+
+- **Each migration commits in a transaction with the row that records it.** A
+  failure can never leave DDL applied and the bookkeeping unwritten. Add
+  `export const transaction = false` for `CREATE INDEX CONCURRENTLY` and friends
+  — the runner says so on the line when it does.
+- **A session advisory lock spans the run**, taken before the bookkeeping is
+  read. Two containers starting at once is the ordinary case, not the exotic
+  one, and without this both see the same empty table and both run the same DDL.
+- **Editing an applied migration is refused**, by checksum, before anything
+  runs. A recorded migration that is no longer on disk is _not_ an error —
+  that is what squashing looks like from the database's side, and `status` says
+  `orphan` rather than failing.
+- **`status` never refuses.** An edited migration is the likeliest reason you
+  are running it, so it reports `changed` and finishes the report rather than
+  failing on the very thing you asked about. `up` and `down` still refuse, which
+  is where refusing belongs.
+
+## What it refuses to do
+
+`down`, `reset`, `fresh`, `seed` and `unseed` all rewrite data somebody may be
+using, so all five go through one guard (`safety.ts`) before they touch
+anything — on the functions themselves, so importing one directly does not walk
+around it.
+
+Two rules, and they are the **default policy** rather than the mechanism — a
+project that declares `guard` replaces both, see [Replacing it](#replacing-it):
+
+- **Never under `NODE_ENV=production`.** A production database is restored from
+  a backup, not from a flag. Nothing in `safety.ts` gets past this one.
+- **Never against a host that is not this machine.** `localhost`, `127.x`, `::1`
+  and a unix socket are this machine; a service name like `postgres` is not,
+  because on a droplet that is exactly what production is called.
+
+```
+reset drops every table, and db.example.com is not this machine.
+  If you mean that database, name it: DB_ALLOW_REMOTE=db.example.com <the same command>
+```
+
+The override names the host on purpose: an export left over from last week
+cannot answer for a database it was never about. The host comes off the driver
+rather than the environment, so the guard reads the connection that is about to
+be used and not a variable that resembles it.
+
+### Replacing it
+
+Both rules above are the **default**, not the mechanism. `guard` replaces them:
+
+```ts
+// database/config.ts
+import { defineConfig, refuse } from 'migrane';
+
+export default defineConfig({
+  // …
+  guard: async (driver, what) => {
+    const [row] = await driver.query<{ on: string | null }>(
+      `SELECT current_setting('migrane.disposable', true) AS on`,
+    );
+
+    if (row?.on === 'yes') return; // this database says it is disposable
+
+    refuse(driver, what); // otherwise, the default rules
+  },
+});
+```
+
+**Declaring nothing is not the same as declaring no policy.** Omit `guard` and
+`refuse` is what runs, so a project that has never thought about this gets the
+strict default rather than none at all. Declare one and it replaces both rules,
+`NODE_ENV=production` included — which is how a preview environment rebuilds its
+own fixtures from the image it is already running, instead of having a
+developer's database copied onto it.
+
+Put the permission on the database rather than in a shell:
+
+```sql
+ALTER DATABASE preview SET migrane.disposable = 'yes';
+```
+
+That survives a schema drop, needs ownership to set, and cannot be typed onto
+the wrong machine — unlike a host name, which in a compose stack is the same
+word on every machine you own.
+
+One policy, not a list. A guard yields a verdict, and combining verdicts needs
+an operator a config field cannot spell — so write the composition you mean, as
+above.
+
+## Hooks
+
+`before` runs once per `up`, on the pinned connection, ahead of anything
+pending — and **even when nothing is pending**, because whether a hook needs to
+run has nothing to do with whether a new migration was added.
+
+```ts
+before: [async ({ sql }) => void (await sql`CREATE EXTENSION IF NOT EXISTS pg_trgm`)],
+```
+
+It is the seam for anything you want true _before_ a migration but do not want
+to write as one — types synced from a registry, a search path, an extension. It
+is also the only place the runner will execute code it did not discover.
+`status` and `reset` do not run hooks; neither has business writing DDL.
+
+## Seeds
+
+Seed units are **alternatives, not increments** — one directory is one dataset
+and you run exactly one against a fresh database. A unit is recorded but never
+refused: editing a fixture set and running it again is how one is used, so the
+row moves rather than the insert failing.
+
+`status` reads that row back as `current`, `changed since`, or `unit is gone` —
+which answers _which fixtures is this database holding_, and is the only
+question the table exists for.
+
+Make a unit safe to run twice: `ON CONFLICT DO NOTHING`, `IF NOT EXISTS`, or
+truncate first. Nothing above it will stop a second run.
+
+## Shipping it in a container
+
+Discovery is a directory read and loading is `import(file)` or `readFileSync`;
+no bundler follows any of them, and an image has no directories. So the build
+generates a **manifest** — imports and two arrays, and nothing else:
+
+```sh
+migrane manifest            # writes where `manifest` in the config points
+migrane manifest --out gen/manifest.ts
+```
+
+Declare the destination rather than letting this package pick one — `entryFor`
+writes every specifier **relative to where the manifest lands**, so guessing
+where it goes would guess what is in it. With neither `manifest` nor `--out`,
+the command says so instead of inventing a path. It opens no database, which is
+what makes it a build step: nothing to connect to, and nothing it could reach.
+
+`entryFor` stays exported for a build that would rather call it directly.
+
+```ts
+// database/manifest.gen.ts — generated, gitignored, regenerated every build
+import * as m1_0 from '../migrations/002-backfill.ts';
+
+export const migrations = [
+  {
+    name: '001-initial',
+    sequence: 1,
+    checksum: 'ab12…',
+    parts: [{ sql: `…` }],
+  },
+  { name: '002-backfill', sequence: 2, checksum: '77aa…', parts: [m1_0] },
+];
+
+export const seeds = [];
+```
+
+A `.ts` part is imported, a `.sql` part is carried as text — the same split
+`load()` makes, because it is the same split. A project written entirely in SQL
+generates a manifest that imports nothing at all, which is to say: data.
+
+The lists are `discover()`'s and `unitsIn()`'s own output, so the image applies
+the same units in the same order and records the same hashes as the CLI. That
+agreement is the whole reason this lives in the library rather than in your
+build script.
+
+### The entry is yours
+
+The manifest calls nothing, so nothing worth reading lives where a linter, a
+checker and a test cannot reach it. What to do with the arrays is ordinary
+source in your repository, and the verbs are the ones you want:
+
+```ts
+// database/entry.ts
+import {
+  fromManifest,
+  planFrom,
+  reachable,
+  seedPlanFrom,
+  seed,
+  status,
+  up,
+  withDriver,
+} from 'migrane';
+import config from './config.ts';
+import { migrations, seeds } from './manifest.gen.ts';
+
+const [verb = 'up', unit] = process.argv.slice(2);
+
+process.exit(
+  await withDriver(config, async (driver) => {
+    try {
+      await reachable(driver);
+
+      const plan = planFrom(config, fromManifest(migrations));
+
+      if (verb === 'up') await up(driver, plan);
+      else if (verb === 'status') await status(driver, plan);
+      else if (verb === 'seed')
+        await seed(driver, seedPlanFrom(config, fromManifest(seeds)), unit!);
+      else throw new Error(`unknown command: ${verb}`);
+
+      return 0;
+    } catch (error) {
+      console.error(error);
+
+      return 1;
+    }
+  }),
+);
+```
+
+The exit code is the contract a deploy reads: a one-shot migrate container that
+exits non-zero holds the previous release in place rather than starting a server
+against a schema that never got written.
+
+Offering `down` or `reset` there is your call, not this package's — and either
+still goes through the guard above before it touches anything.
+
+## Writing a driver
+
+Three methods and a host, over a session that can lock and transact.
+`drivers/pg.ts` is the reference, and `pg` is an optional peer dependency —
+importing `migrane` does not reach it, only importing `migrane/drivers/pg`
+does.
+
+```ts
+import type { Driver, Session } from 'migrane';
+
+interface Driver {
+  readonly host: string; // where these coordinates point; '' for a unix socket
+  query(text, values?): Promise<Row[]>;
+  session<T>(run: (session: Session) => Promise<T>): Promise<T>;
+  close(): Promise<void>;
+}
+
+interface Session extends Queryable {
+  transaction<T>(run: (tx: Queryable) => Promise<T>): Promise<T>;
+  lock<T>(key: number, run: () => Promise<T>): Promise<T>;
+}
+```
+
+`host` is required rather than optional-with-a-default because the destructive
+commands refuse on it, and a driver that could leave it out would be a driver
+that silently opts out of the refusal. State it even when it is `'localhost'`.
+
+`session` pins one connection: a lock and a transaction are only meaningful on a
+connection that stays the same between statements, and a pool hands out
+whichever is free.
+
+`lock` is a **method rather than a statement the runner sends**, because taking
+a lock is a database-agnostic idea and `SELECT pg_advisory_lock($1)` is not —
+this package names no database, and that statement was the one place it did. It
+takes and releases around `run`, so no caller can forget to give a lock back,
+and it must block rather than fail: whoever holds it is applying the migrations
+this process wants applied, so waiting is the correct outcome. Where a database
+has nothing like one, a driver that runs one migrator at a time may implement it
+as `run()` and say so.
+
+One honest caveat: the core is agnostic by contract, PostgreSQL-first in
+dialect. The `sql` tag emits `$n` placeholders, the bookkeeping tables use
+`TIMESTAMPTZ`/`now()`, and `reset` speaks `DROP SCHEMA … CASCADE`. A driver for
+another database is absolutely writable — its `query` translates what its
+database spells differently — but that translation is the driver's job until a
+second first-party driver moves the seams here.
+
+## License
+
+[MIT](LICENSE)

package/bin/migrane.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env sh
+':' //; f=; case "$1" in --runtime=*) f=${1#--runtime=}; shift;; esac; for r in ${f:-${MIGRANE_RUNTIME:-node bun}}; do command -v "$r" >/dev/null 2>&1 && exec "$r" "$0" "$@"; done; echo 'migrane: needs node or bun on PATH' >&2; exit 1
+
+import { run } from '../dist/cli.js';
+
+/**
+ * The `migrane` executable. Argument handling lives in `src/cli.ts`; this file
+ * turns its answer into an exit code.
+ *
+ * Plain JavaScript rather than part of the build, because `cli.ts` is also a
+ * library export: an entrypoint runs on import, and what `index.ts` re-exports
+ * must never do that.
+ *
+ * ## Line 2 is sh and JavaScript at once
+ *
+ * `#!/usr/bin/env node` makes this package unusable on a bun-only machine — the
+ * kernel reads the shebang, so nothing of ours runs and no error of ours can
+ * explain why. Naming `sh` instead lets the line below pick a runtime and
+ * `exec` it on this same file.
+ *
+ * sh reads `:` called with the argument `//`, then a loop. JavaScript reads the
+ * string `':'` and a `//` comment swallowing the rest — which is why the whole
+ * dispatch has to stay on one line. Both runtimes strip a `#!` first line, so
+ * what arrives is a valid module.
+ *
+ * **`.prettierignore` names this file, and that is load-bearing.** Prettier
+ * reformats the line to `':'; //;`, which is still valid JavaScript and no
+ * longer valid sh: `:` loses its argument, the shell tries to run `//`, and
+ * every command prints `//: is a directory` before working.
+ *
+ * ## Which runtime, and why node first
+ *
+ * `migrane --runtime=bun up` names it per command, `MIGRANE_RUNTIME=bun` for
+ * the shell, and the flag wins. It must come first and use the `=` form: this
+ * line reads exactly one argument, because scanning the whole list would take
+ * more shell than fits in a JavaScript comment. It never reaches `run()`, which
+ * is why the usage `cli.ts` prints does not list it.
+ *
+ * Node is tried first as a compatibility promise, not a preference — a machine
+ * holding both behaved as node before this line existed. The two differ in one
+ * way that matters: bun loads `.env` from the *working directory*, while
+ * everything else here resolves against the config file, so `cd apps/api &&
+ * migrane up` can pick up a different `.env` than the repository root. A
+ * variable already set in the environment still wins, so CI and containers are
+ * unaffected. See the README for the full trade and `bun --no-env-file`.
+ *
+ * ## The cost is Windows
+ *
+ * npm writes the `.cmd` shim from this shebang, so it emits one calling `sh`:
+ * present under Git Bash, absent otherwise. `#!/bin/sh` would emit a literal
+ * path cmd.exe can never resolve, so the `env` form degrades rather than dies.
+ */
+
+process.exit(await run(process.argv.slice(2)));

package/dist/bundle.d.ts

@@ -0,0 +1,25 @@
+import type { Resolved } from './config.js';
+/**
+ * Writing the manifest a bundler can follow.
+ *
+ * Discovery is a directory read and loading is `import(file)` or
+ * `readFileSync`; no bundler follows any of them, and an image has no
+ * directories. So a build calls this and bundles what it writes. The lists come
+ * from `discover()` and `unitsIn()`, so an image applies the same units in the
+ * same order and records the same checksums as the CLI.
+ *
+ * **Data, not a program**: imports and two arrays, calling nothing. What to do
+ * with the arrays is the consumer's entry, which is ordinary source in their
+ * repository rather than generated text no linter reaches.
+ */
+export interface EntryOptions {
+    /** The resolved config. Read for its directories, never imported. */
+    config: Resolved;
+    /**
+     * Where the manifest will be written. Given one, every specifier is relative
+     * to it, so the file resolves the same on any machine; omitted, specifiers
+     * are absolute, which only suits a file going to a temporary directory.
+     */
+    to?: string;
+}
+export declare const entryFor: ({ config, to }: EntryOptions) => string;

package/dist/bundle.js

@@ -0,0 +1,70 @@
+import { readFileSync } from 'node:fs';
+import { dirname, extname, relative, sep } from 'node:path';
+import { discover } from './discover.js';
+import { unitsIn } from './seeds.js';
+/**
+ * POSIX separators unconditionally: `relative` answers with backslashes on
+ * Windows, and a backslash in an import specifier is an escape.
+ */
+const specifierFor = (file, to) => {
+    if (!to)
+        return file;
+    const path = relative(dirname(to), file).split(sep).join('/');
+    return path.startsWith('.') ? path : `./${path}`;
+};
+/**
+ * SQL carried as text rather than imported, because a `.sql` migration is
+ * loaded with `readFileSync` and never `import`. Inlining is what that becomes
+ * when there is no file to read, byte-for-byte, so the checksum still describes
+ * what the image runs.
+ *
+ * A template literal so newlines survive; three escapes make it reversible.
+ */
+const inlined = (file) => '`' +
+    readFileSync(file, 'utf8')
+        .replaceAll('\\', '\\\\')
+        .replaceAll('`', '\\`')
+        .replaceAll('${', '\\${') +
+    '`';
+/**
+ * One array's worth of entries: the imports its `.ts` parts need, and a row per
+ * unit naming its parts in run order.
+ *
+ * Parts stay an ordered list of either kind, because a directory without an
+ * index may hold both and the order is the dependency order. Composing them is
+ * `fromManifest`'s job, which keeps this file importing nothing from the runner.
+ */
+const emit = (found, prefix, to) => {
+    const imports = [];
+    const rows = [];
+    found.forEach((entry, index) => {
+        const parts = entry.run.map((file, part) => {
+            if (extname(file) === '.sql')
+                return `{ sql: ${inlined(file)} }`;
+            const binding = `${prefix}${index}_${part}`;
+            imports.push(`import * as ${binding} from ${JSON.stringify(specifierFor(file, to))};`);
+            return binding;
+        });
+        rows.push(`  { name: ${JSON.stringify(entry.name)}, sequence: ${entry.sequence}, checksum: ${JSON.stringify(entry.checksum)}, parts: [${parts.join(', ')}] },`);
+    });
+    return { imports, rows };
+};
+const arrayOf = (name, rows) => rows.length
+    ? [`export const ${name} = [`, ...rows, '];']
+    : [`export const ${name} = [];`];
+export const entryFor = ({ config, to }) => {
+    const migrations = emit(discover(config.dirs), 'm', to);
+    // A consumer with no seeds declares none, and gets an empty array rather than
+    // a missing export: an entry that destructures both should not have to know
+    // which of them this project happens to have.
+    const seeds = emit(config.seeds ? unitsIn(config.seeds) : [], 's', to);
+    return [
+        ...migrations.imports,
+        ...seeds.imports,
+        ...(migrations.imports.length || seeds.imports.length ? [''] : []),
+        ...arrayOf('migrations', migrations.rows),
+        '',
+        ...arrayOf('seeds', seeds.rows),
+        '',
+    ].join('\n');
+};

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The exit code is the contract a deploy reads: a one-shot migrate container
+ * that exits non-zero holds the previous release in place rather than starting
+ * a server against a schema that never got written.
+ */
+export declare const run: (argv: readonly string[], cwd?: string) => Promise<number>;