@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/migrate/database.js

@@ -0,0 +1,247 @@
+/**
+ * The one connection a migration run holds, on each engine, and the lock that
+ * keeps two deploys from migrating at once.
+ *
+ * Not the adapters: those read, through pools, in read-only transactions.
+ * A migration writes DDL on one private connection and holds it for the run.
+ *
+ * - SQLite: node:sqlite, with foreign keys off as the SQLite manual's table
+ *   rebuild asks and as Flyway's driver leaves them; each migration's
+ *   transaction checks them before it commits instead. The lock is SQLite's
+ *   own: every step is a `BEGIN IMMEDIATE` that re-reads the history.
+ * - PostgreSQL: `pg`, a session advisory lock held for the run, on the number
+ *   Flyway derives from the same history table, so tablewalk and Flyway
+ *   exclude each other as well as themselves.
+ */
+import { existsSync } from 'node:fs';
+import { DatabaseSync } from 'node:sqlite';
+import { MYSQL_REFUSAL } from '../../adapters/connect.js';
+import { postgresPoolDefaults } from '../../adapters/postgresPool.js';
+import { pgConnectionOptions } from '../../adapters/postgresValues.js';
+import { product } from '../product.js';
+export const quoteIdent = (_dialect, name) => `"${name.replace(/"/g, '""')}"`;
+/** Java's String.hashCode, which Flyway's advisory lock number is built on. */
+function javaHash(text) {
+    let hash = 0;
+    for (let i = 0; i < text.length; i++)
+        hash = (Math.imul(hash, 31) + text.charCodeAt(i)) | 0;
+    return hash;
+}
+/** The advisory lock Flyway takes on PostgreSQL for this history table (PostgreSQLAdvisoryLockTemplate). */
+export function flywayLockNumber(schema, table) {
+    return 77431708279161n + BigInt(javaHash(`${quoteIdent('postgres', schema)}.${quoteIdent('postgres', table)}`));
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+/** How long a PostgreSQL migration's statement waits for a lock before its file is rolled back and tried again. */
+const MIGRATION_LOCK_TIMEOUT_MS = 5_000;
+/* What a migration needs from the session it runs on: its lock, held across
+   the steps' transactions, and the --schema path. */
+const SESSION_NEEDED = 'a migration holds a session lock, which a transaction-mode pooler does not keep; run it on a URL that reaches PostgreSQL directly or through a session-mode pool';
+export function dialectOf(url) {
+    if (/^postgres(ql)?:\/\//i.test(url))
+        return 'postgres';
+    if (/^(mysql|mariadb):\/\//i.test(url))
+        throw new Error(MYSQL_REFUSAL);
+    if (/^[a-z][\w+.-]*:\/\//i.test(url))
+        throw new Error(product() + ' migrate runs on SQLite and PostgreSQL; this connection is neither.');
+    return 'sqlite';
+}
+export const sqlitePath = (url) => url.replace(/^sqlite:(\/\/)?/i, '');
+/**
+ * Open the run's connection. `create` lets `up` start a SQLite file that is
+ * not there yet (a fresh database migrated from nothing); every other command
+ * refuses a path with nothing at it, which is a typo far more often.
+ * `schemas` is the run's scope: on PostgreSQL the first is where the history
+ * lives and the search path is set to them, as Flyway's `schemas` does.
+ */
+export async function openMigrationDb(url, schemas, create) {
+    const dialect = dialectOf(url);
+    if (dialect === 'sqlite') {
+        const path = sqlitePath(url);
+        if (!create && !existsSync(path))
+            throw new Error(`there is no SQLite database at ${path}`);
+        const db = new DatabaseSync(path, { enableForeignKeyConstraints: false, timeout: 60_000 });
+        return {
+            dialect,
+            home: undefined,
+            user: '',
+            async all(sql, params = []) {
+                return db.prepare(sql).all(...params);
+            },
+            async run(sql, params = []) {
+                db.prepare(sql).run(...params);
+            },
+            async script(sql) {
+                db.exec(sql);
+            },
+            async lock() {
+                /* Each step's BEGIN IMMEDIATE is the lock. */
+            },
+            async close() {
+                db.close();
+            },
+        };
+    }
+    const specifier = 'pg';
+    const pg = (await import(specifier).catch(() => {
+        throw new Error('PostgreSQL support needs the "pg" package. Install it with: npm install pg');
+    }));
+    const Client = pg.Client ?? pg.default?.Client;
+    if (!Client)
+        throw new Error('Could not find a Client export in the "pg" package.');
+    const client = new Client({ ...pgConnectionOptions(url), connectionTimeoutMillis: 15_000 });
+    // An idle connection that drops is an 'error' event; unheard it ends the process. The next statement rejects with the loss.
+    client.on('error', () => { });
+    await client.connect().catch(() => {
+        throw new Error('the PostgreSQL database could not be opened');
+    });
+    try {
+        const [{ current, user }] = (await client.query('SELECT current_schema() AS current, current_user AS user')).rows;
+        const home = schemas[0] ?? current;
+        if (!home)
+            throw new Error('the connection has no current schema (an empty search_path): name one with --schema');
+        /* Behind a transaction-mode pooler (`--pooler transaction`) a session
+           setting stays on whichever server connection the pooler lent and
+           follows it to the pooler's next client: the lock wait below would
+           reach the App's own statements. The serve-time readers of the
+           migration tables (the Console, governance, analytics provisioning)
+           set nothing there; what needs the session refuses. */
+        const pooled = postgresPoolDefaults().pooler === 'transaction';
+        if (schemas.length) {
+            if (pooled)
+                throw new Error(SESSION_NEEDED);
+            await client.query(`SET search_path TO ${schemas.map((schema) => quoteIdent('postgres', schema)).join(', ')}`);
+        }
+        /* A migration's DDL waits for the tables it changes, and while it waits
+           every App statement on those tables queues behind it: an ALTER TABLE
+           stuck behind one long transaction stops the App. So it gives up after
+           MIGRATION_LOCK_TIMEOUT_MS and tries again (runner.ts apply). */
+        if (!pooled)
+            await client.query(`SET lock_timeout = '${MIGRATION_LOCK_TIMEOUT_MS}ms'`);
+        let held;
+        const numbered = (sql) => {
+            let n = 0;
+            return sql.replace(/\?/g, () => `$${++n}`);
+        };
+        return {
+            dialect,
+            home,
+            user,
+            async all(sql, params = []) {
+                return (await client.query(numbered(sql), params)).rows;
+            },
+            async run(sql, params = []) {
+                await client.query(numbered(sql), params);
+            },
+            // The simple protocol: a script of many statements in one round trip.
+            async script(sql) {
+                await client.query(sql);
+            },
+            async lock(table, waitMs, waiting) {
+                if (pooled)
+                    throw new Error(SESSION_NEEDED);
+                const key = flywayLockNumber(home, table);
+                const started = Date.now();
+                let said = false;
+                for (;;) {
+                    const [{ locked }] = (await client.query('SELECT pg_try_advisory_lock($1::bigint) AS locked', [String(key)])).rows;
+                    if (locked) {
+                        held = key;
+                        return;
+                    }
+                    if (Date.now() - started > waitMs)
+                        throw new Error(`another migration of ${home}.${table} has held its lock for ${Math.round(waitMs / 1000)}s; try again when it has finished`);
+                    if (!said) {
+                        waiting();
+                        said = true;
+                    }
+                    await sleep(250);
+                }
+            },
+            async close() {
+                if (held !== undefined)
+                    await client.query('SELECT pg_advisory_unlock($1::bigint)', [String(held)]).catch(() => { });
+                await client.end().catch(() => { });
+            },
+        };
+    }
+    catch (error) {
+        await client.end().catch(() => { });
+        throw error;
+    }
+}
+/**
+ * A PostgreSQL script as its statements, for a file that must run outside a
+ * transaction: `CREATE INDEX CONCURRENTLY` refuses a multi-statement query,
+ * which PostgreSQL runs as one implicit transaction. Reads quotes, quoted
+ * names, dollar quotes and both kinds of comment, and cuts at the semicolons
+ * outside them.
+ */
+export function splitPostgres(sql) {
+    const out = [];
+    let start = 0;
+    let i = 0;
+    const n = sql.length;
+    while (i < n) {
+        const c = sql[i];
+        if (c === '-' && sql[i + 1] === '-') {
+            const end = sql.indexOf('\n', i);
+            i = end < 0 ? n : end + 1;
+            continue;
+        }
+        if (c === '/' && sql[i + 1] === '*') {
+            let depth = 1;
+            i += 2;
+            while (i < n && depth) {
+                if (sql[i] === '/' && sql[i + 1] === '*') {
+                    depth++;
+                    i += 2;
+                }
+                else if (sql[i] === '*' && sql[i + 1] === '/') {
+                    depth--;
+                    i += 2;
+                }
+                else
+                    i++;
+            }
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            const escaped = c === "'" && /[eE]/.test(sql[i - 1] ?? '') && !/\w/.test(sql[i - 2] ?? '');
+            i++;
+            while (i < n) {
+                if (escaped && sql[i] === '\\') {
+                    i += 2;
+                    continue;
+                }
+                if (sql[i] === c) {
+                    if (sql[i + 1] === c) {
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (c === '$') {
+            const tag = /^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(i));
+            if (tag && !/\w/.test(sql[i - 1] ?? '')) {
+                const end = sql.indexOf(tag[0], i + tag[0].length);
+                i = end < 0 ? n : end + tag[0].length;
+                continue;
+            }
+        }
+        if (c === ';') {
+            out.push(sql.slice(start, i));
+            start = i + 1;
+        }
+        i++;
+    }
+    out.push(sql.slice(start));
+    return out
+        .map((statement) => statement.trim())
+        .filter((statement) => statement && !/^(--[^\n]*\n?|\/\*[\s\S]*?\*\/|\s)*$/.test(statement));
+}

package/dist/server/migrate/desired.d.ts

@@ -0,0 +1,76 @@
+import { type MigrateTarget } from './runner.js';
+/** The pinned build. A new version is a new line here and new checksums, reviewed like any dependency. */
+export declare const ATLAS_VERSION = "v1.3.0";
+/** Where the binary lives: local to the project, ignored by git, named by its version so a bump fetches again. */
+export declare const atlasPath: (projectDir: string) => string;
+/** The desired schema, by default: `schema.sql` beside the migrations directory (`db/migrations` → `db/schema.sql`). */
+export declare const defaultSchemaFile: (migrationsDir: string) => string;
+/**
+ * The Atlas binary to run: `MISTRI_ATLAS` (`TABLEWALK_ATLAS` under the browser, product.ts) when set (an Atlas the team
+ * installed itself, taken as it is), else the pinned build, fetched once and
+ * checked against its sha256 before it is ever made executable.
+ */
+export declare function atlasBinary(projectDir: string, say: (line: string) => void, fetcher?: (url: string) => Promise<Uint8Array>, platform?: string, pins?: Readonly<Record<string, string>>): Promise<string>;
+/**
+ * A database URL as Atlas reads it, and the environment that carries its
+ * password: never on argv, where every user of the machine can read it in
+ * the process list. Atlas's PostgreSQL driver honours `PGPASSWORD` as libpq
+ * does. Scoped to one schema, so `--exclude` names tables and nothing else of
+ * a shared database is compared.
+ */
+export declare function atlasUrl(url: string, schema?: string): {
+    url: string;
+    env: Record<string, string>;
+};
+interface DesiredOptions {
+    /** The desired schema: `schema.sql` beside the migrations unless named. */
+    readonly schemaFile: string;
+    /** A PostgreSQL server where two scratch databases may be made and dropped; the connection's own by default. */
+    readonly devUrl?: string;
+    readonly atlas: string;
+}
+/**
+ * What the migrations still lack to reach `schema.sql`, as SQL: empty when
+ * they agree. tablewalk's own tables (`__mistri_*`, and the history table
+ * if it is named otherwise) are left out of the comparison: they move through
+ * tablewalk, not through schema.sql.
+ */
+export declare function pendingSql(target: MigrateTarget, options: DesiredOptions): Promise<string>;
+/**
+ * schema.sql as SQLite is to read it. PostgreSQL numbers a `serial` column
+ * from a sequence; SQLite takes any word as a type, so `id serial primary key`
+ * is accepted as a plain nullable column, Atlas writes it back as
+ * `` `id` serial NULL ``, and every new row's id is NULL. SQLite numbers only
+ * an `integer` primary key (the rowid's other name), so a serial primary key
+ * is read as one here, and one schema.sql serves both databases — the
+ * quickstart's and the home page's do. A serial column that is not declared
+ * the primary key on its own line has nothing on SQLite to number it, and is
+ * refused by name rather than left to come out NULL.
+ */
+export declare function sqliteDesired(text: string): string;
+/** The header a written migration carries: where it came from, and what a diff cannot know. */
+export declare const diffHeader: () => string;
+/**
+ * The first versioned migration: what an empty database lacks to reach
+ * `schema.sql` is `schema.sql`, so it is written as it stands — comments and
+ * all, as a squash writes it — and no diff tool is fetched for it. On SQLite
+ * it is schema.sql as SQLite reads it (`sqliteDesired`). `migrate up` is what
+ * proves it runs; the next `migrate diff` compares the two as any other does.
+ */
+export declare function firstMigration(schemaFile: string, dialect: string, schemas: readonly string[]): string;
+/** The header the first migration carries: it is schema.sql, not a diff. */
+export declare const firstHeader: () => string;
+/**
+ * Fold the versioned chain into one `V1__baseline.sql` holding `schema.sql`
+ * itself — comments and all, since the check has just shown the two build the
+ * same schema. Repeatable files stay. Only before a database worth keeping
+ * exists: one migrated with the old chain no longer matches its history.
+ * On SQLite it is schema.sql as SQLite reads it (`sqliteDesired`), so the
+ * baseline numbers its ids as the diff's files did. Returns the files
+ * removed and the one written.
+ */
+export declare function squashInto(dir: string, schemaFile: string, dialect?: string): {
+    removed: string[];
+    wrote: string;
+};
+export {};

package/dist/server/migrate/desired.js

@@ -0,0 +1,292 @@
+/**
+ * `tablewalk migrate diff | check | squash`: the schema a team wants, written
+ * once in `schema.sql`, and the versioned files that get a database there.
+ *
+ * tablewalk stays database-first: nothing here comes from the App's DSL. The
+ * person edits `schema.sql` the way they would write it by hand; `diff`
+ * writes the next `V<n>__<name>.sql` holding what the migrations so far lack,
+ * for review; `check` fails when the migrations and `schema.sql` disagree, so
+ * neither drifts from the other in a commit; `squash` folds the chain into
+ * one baseline before a database worth keeping exists.
+ *
+ * The comparison is Atlas's (the Apache-2.0 community build), not ours: a
+ * schema differ is a database tool, and tablewalk rides on the database
+ * rather than becoming one. It is fetched pinned — a version and a sha256 per
+ * platform — into `.mistri/bin` (`.tablewalk/bin` for the browser) beside the project, on the first `diff` or
+ * `check` and said aloud, never while serving, and run with its update check
+ * off. Stripe's pg-schema-diff was tried first and set aside: it cannot leave
+ * tablewalk's `__mistri_*` tables out (only whole schemas), so a diff would
+ * drop the migration history, and its plans use `CREATE INDEX CONCURRENTLY`
+ * and `SET SESSION`, which do not fit one transaction per file.
+ *
+ * Both sides are real databases: the migrations are applied to a scratch one
+ * by tablewalk's own runner (the runner a deploy uses, so the chain is judged
+ * as it will run), and Atlas reads `schema.sql` into a second, empty one. On
+ * PostgreSQL both are created on the connection's server (or `--dev-url`'s)
+ * and dropped after, which needs `CREATEDB`; on SQLite one is a temporary file
+ * and the other is in memory. Neither is the connection's own database.
+ */
+import { execFile } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { RUNTIME_TABLE_PREFIXES } from '../../shared/runtimeTables.js';
+import { dialectOf, openMigrationDb, quoteIdent, sqlitePath } from './database.js';
+import { readMigrations } from './files.js';
+import { migrateUp } from './runner.js';
+import { envName, product, productEnv } from '../product.js';
+/** The pinned build. A new version is a new line here and new checksums, reviewed like any dependency. */
+export const ATLAS_VERSION = 'v1.3.0';
+const ATLAS_SHA256 = {
+    'darwin-arm64': '4e5ffdc10b2b4fd3a06074aba72848150907d5316cacad7b19bae6c6ae3db991',
+    'darwin-amd64': '650981a024301775ec964e5134e2d5712b7ef1b25fec4b2ec54bad762b4bdf6f',
+    'linux-amd64': '10d7913e3dce43ab99b8d71534a4cbadaf11a16dc293adf3b91d10e83a0ac70b',
+    'linux-arm64': '082188c57a53439596a3ee52173b12e785aa83ec718505674e2052db0fec0c4c',
+};
+/** Where the binary lives: local to the project, ignored by git, named by its version so a bump fetches again. */
+export const atlasPath = (projectDir) => join(projectDir, `.${product()}`, 'bin', `atlas-${ATLAS_VERSION}`);
+/** The desired schema, by default: `schema.sql` beside the migrations directory (`db/migrations` → `db/schema.sql`). */
+export const defaultSchemaFile = (migrationsDir) => join(dirname(resolve(migrationsDir)), 'schema.sql');
+/**
+ * The Atlas binary to run: `MISTRI_ATLAS` (`TABLEWALK_ATLAS` under the browser, product.ts) when set (an Atlas the team
+ * installed itself, taken as it is), else the pinned build, fetched once and
+ * checked against its sha256 before it is ever made executable.
+ */
+export async function atlasBinary(projectDir, say, fetcher = download, platform = `${process.platform}-${process.arch === 'x64' ? 'amd64' : process.arch}`, pins = ATLAS_SHA256) {
+    const own = productEnv('ATLAS');
+    if (own)
+        return own;
+    const path = atlasPath(projectDir);
+    const want = pins[platform];
+    if (!want)
+        throw new Error(`there is no pinned Atlas build for ${platform}. Install Atlas ${ATLAS_VERSION} (community edition) and set ${envName('ATLAS')} to its path.`);
+    /* Checked again on every run, not only when fetched: the file sits in the project, where anything that writes there
+       (a dependency's install script, a checkout of someone's branch) could replace what this then executes. */
+    if (existsSync(path)) {
+        if (createHash('sha256').update(readFileSync(path)).digest('hex') === want)
+            return path;
+        say(`The Atlas binary in ${join(`.${product()}`, 'bin')} is not the pinned build; fetching it again.`);
+        rmSync(path, { force: true });
+    }
+    const url = `https://release.ariga.io/atlas/atlas-community-${platform}-${ATLAS_VERSION}`;
+    say(`Fetching Atlas community ${ATLAS_VERSION} (${platform}, about 40 MB) into ${join(`.${product()}`, 'bin')}, once.`);
+    const bytes = await fetcher(url);
+    const got = createHash('sha256').update(bytes).digest('hex');
+    if (got !== want)
+        throw new Error(`the Atlas download from ${url} is not the pinned build (sha256 ${got}); nothing was installed.`);
+    mkdirSync(dirname(path), { recursive: true });
+    const part = `${path}.part`;
+    writeFileSync(part, bytes);
+    chmodSync(part, 0o755);
+    renameSync(part, path);
+    /* An older pin's binary is dead weight once the version moves. */
+    for (const old of readdirSync(dirname(path)))
+        if (old.startsWith('atlas-') && old !== `atlas-${ATLAS_VERSION}`)
+            rmSync(join(dirname(path), old), { force: true });
+    return path;
+}
+async function download(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`could not fetch Atlas from ${url}: HTTP ${response.status}.`);
+    return new Uint8Array(await response.arrayBuffer());
+}
+/**
+ * A database URL as Atlas reads it, and the environment that carries its
+ * password: never on argv, where every user of the machine can read it in
+ * the process list. Atlas's PostgreSQL driver honours `PGPASSWORD` as libpq
+ * does. Scoped to one schema, so `--exclude` names tables and nothing else of
+ * a shared database is compared.
+ */
+export function atlasUrl(url, schema) {
+    if (dialectOf(url) === 'sqlite') {
+        const path = sqlitePath(url);
+        return { url: path.startsWith('file:') || path.includes('?') ? `sqlite://${path}` : `sqlite://${resolve(path)}`, env: {} };
+    }
+    const parsed = new URL(url);
+    const password = parsed.password ? decodeURIComponent(parsed.password) : undefined;
+    parsed.password = '';
+    parsed.protocol = 'postgres:';
+    /* node-postgres speaks plain TCP unless told otherwise; Atlas would insist on TLS. Keep the connection's choice. */
+    if (!parsed.searchParams.has('sslmode'))
+        parsed.searchParams.set('sslmode', 'disable');
+    if (schema !== undefined)
+        parsed.searchParams.set('search_path', schema);
+    return { url: parsed.toString(), env: password !== undefined ? { PGPASSWORD: password } : {} };
+}
+/** Run Atlas, its update check off, its edition notice dropped; resolves to stdout, rejects with what it said. */
+function runAtlas(binary, args, env = {}) {
+    return new Promise((done, fail) => {
+        execFile(binary, args, { env: { ...process.env, ...env, ATLAS_NO_UPDATE_NOTIFIER: '1' }, maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (!error)
+                return done(stdout);
+            const said = String(stderr)
+                .replace(/^Notice: This Atlas[\s\S]*?docs#installation\s*/m, '')
+                .trim();
+            fail(new Error(error.code === 'ENOENT'
+                ? `Atlas is not at ${binary}${productEnv('ATLAS') ? ` (${envName('ATLAS')})` : ''}.`
+                : `Atlas: ${said || error.message}`));
+        });
+    });
+}
+/** Two throwaway databases beside the connection's (or `devUrl`'s) server, never the connection's own. */
+async function scratch(url, devUrl) {
+    const dialect = dialectOf(url);
+    if (devUrl !== undefined && dialectOf(devUrl) !== dialect)
+        throw new Error(`--dev-url must be the same kind of database as the connection (${dialect}).`);
+    if (dialect === 'sqlite') {
+        const dir = mkdtempSync(join(tmpdir(), 'tablewalk-schema-'));
+        return {
+            built: join(dir, 'built.db'),
+            dev: 'sqlite://dev?mode=memory',
+            drop: async () => rmSync(dir, { recursive: true, force: true }),
+        };
+    }
+    const server = devUrl ?? url;
+    const stem = `tablewalk_schema_${process.pid}_${randomBytes(3).toString('hex')}`;
+    const names = [`${stem}_built`, `${stem}_dev`];
+    const admin = await openMigrationDb(server, [], false);
+    const at = (name) => {
+        const parsed = new URL(server);
+        parsed.pathname = `/${name}`;
+        return parsed.toString();
+    };
+    const made = [];
+    const drop = async () => {
+        for (const name of made)
+            await admin.run(`DROP DATABASE IF EXISTS ${quoteIdent('postgres', name)} WITH (FORCE)`).catch(() => { });
+        await admin.close();
+    };
+    try {
+        for (const name of names) {
+            await admin.run(`CREATE DATABASE ${quoteIdent('postgres', name)}`);
+            made.push(name);
+        }
+    }
+    catch (error) {
+        await drop();
+        throw new Error(`could not create a scratch database on that server (${error.message}). The role needs CREATEDB, or name a server where it has it with --dev-url.`);
+    }
+    return { built: at(names[0]), dev: at(names[1]), drop };
+}
+/**
+ * What the migrations still lack to reach `schema.sql`, as SQL: empty when
+ * they agree. tablewalk's own tables (`__mistri_*`, and the history table
+ * if it is named otherwise) are left out of the comparison: they move through
+ * tablewalk, not through schema.sql.
+ */
+export async function pendingSql(target, options) {
+    if (!existsSync(options.schemaFile))
+        throw new Error(`there is no ${options.schemaFile}: write the schema you want there, or name it with --schema-file.`);
+    if (target.schemas.length > 1)
+        throw new Error(`migrate diff compares one schema, and this run owns ${target.schemas.join(', ')}: name one with --schema.`);
+    const dialect = dialectOf(target.url);
+    const db = await scratch(target.url, options.devUrl);
+    try {
+        const built = { ...target, url: db.built };
+        const result = await migrateUp(built);
+        if (result.refused)
+            throw new Error(result.refused);
+        if (result.status.plan.problems.length)
+            throw new Error(result.status.plan.problems.join(' '));
+        if (result.failure)
+            throw new Error(`${result.failure.file.script} failed on a scratch database: ${result.failure.message}`);
+        const schema = dialect === 'postgres' ? (target.schemas[0] ?? 'public') : undefined;
+        /* Atlas reads schema.sql into the scoped schema of the dev database, and will not make it. */
+        if (schema !== undefined && schema !== 'public') {
+            const dev = await openMigrationDb(db.dev, [], false);
+            try {
+                await dev.run(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent('postgres', schema)}`);
+            }
+            finally {
+                await dev.close();
+            }
+        }
+        const from = atlasUrl(db.built, schema);
+        const dev = dialect === 'postgres' ? atlasUrl(db.dev, schema) : { url: db.dev, env: {} };
+        /* SQLite reads a copy with PostgreSQL's serial primary keys in its own spelling; the file itself when nothing changed. */
+        let to = resolve(options.schemaFile);
+        if (dialect === 'sqlite') {
+            const text = readFileSync(to, 'utf8');
+            const read = sqliteDesired(text);
+            if (read !== text)
+                writeFileSync((to = join(dirname(db.built), 'schema.sql')), read);
+        }
+        const excludes = [...new Set([...RUNTIME_TABLE_PREFIXES.map((prefix) => `${prefix}*`), target.table])].flatMap((pattern) => [
+            '--exclude',
+            pattern,
+        ]);
+        const sql = await runAtlas(options.atlas, ['schema', 'diff', '--from', from.url, '--to', `file://${to}`, '--dev-url', dev.url, ...excludes, '--format', '{{ sql . "  " }}'], { ...from.env, ...dev.env });
+        return sql.trim();
+    }
+    finally {
+        await db.drop();
+    }
+}
+/**
+ * schema.sql as SQLite is to read it. PostgreSQL numbers a `serial` column
+ * from a sequence; SQLite takes any word as a type, so `id serial primary key`
+ * is accepted as a plain nullable column, Atlas writes it back as
+ * `` `id` serial NULL ``, and every new row's id is NULL. SQLite numbers only
+ * an `integer` primary key (the rowid's other name), so a serial primary key
+ * is read as one here, and one schema.sql serves both databases — the
+ * quickstart's and the home page's do. A serial column that is not declared
+ * the primary key on its own line has nothing on SQLite to number it, and is
+ * refused by name rather than left to come out NULL.
+ */
+export function sqliteDesired(text) {
+    const read = text.replace(/\b(?:small|big)?serial(\s+(?:not\s+null\s+)?primary\s+key)\b/gi, 'integer$1');
+    const bare = read.replace(/--[^\n]*|\/\*[\s\S]*?\*\//g, '');
+    /* Not before `(`: that is a table or an index named serial, not a column's type. */
+    const left = /([A-Za-z_][\w$]*|"[^"]+"|`[^`]+`)\s+((?:small|big)?serial)\b(?!\s*\()/i.exec(bare);
+    if (left)
+        throw new Error(`${left[1]} is ${left[2]}, which SQLite does not number. On SQLite only the primary key is numbered: write it \`${left[1]} ${left[2]} primary key\` (read as integer primary key), or give it another type.`);
+    return read;
+}
+/** The header a written migration carries: where it came from, and what a diff cannot know. */
+export const diffHeader = () => '-- Written by ' +
+    product() +
+    ' migrate diff from schema.sql. Review it before committing:\n' +
+    '-- a rename comes out as DROP and ADD, and a backfill or data step is not here.\n';
+/**
+ * The first versioned migration: what an empty database lacks to reach
+ * `schema.sql` is `schema.sql`, so it is written as it stands — comments and
+ * all, as a squash writes it — and no diff tool is fetched for it. On SQLite
+ * it is schema.sql as SQLite reads it (`sqliteDesired`). `migrate up` is what
+ * proves it runs; the next `migrate diff` compares the two as any other does.
+ */
+export function firstMigration(schemaFile, dialect, schemas) {
+    if (!existsSync(schemaFile))
+        throw new Error(`there is no ${schemaFile}: write the schema you want there, or name it with --schema-file.`);
+    if (schemas.length > 1)
+        throw new Error(`migrate diff compares one schema, and this run owns ${schemas.join(', ')}: name one with --schema.`);
+    const text = readFileSync(schemaFile, 'utf8');
+    return dialect === 'sqlite' ? sqliteDesired(text) : text;
+}
+/** The header the first migration carries: it is schema.sql, not a diff. */
+export const firstHeader = () => '-- Written by ' + product() + ' migrate diff: schema.sql as it stands, the first migration. Review it before committing.\n';
+/**
+ * Fold the versioned chain into one `V1__baseline.sql` holding `schema.sql`
+ * itself — comments and all, since the check has just shown the two build the
+ * same schema. Repeatable files stay. Only before a database worth keeping
+ * exists: one migrated with the old chain no longer matches its history.
+ * On SQLite it is schema.sql as SQLite reads it (`sqliteDesired`), so the
+ * baseline numbers its ids as the diff's files did. Returns the files
+ * removed and the one written.
+ */
+export function squashInto(dir, schemaFile, dialect) {
+    const { files } = readMigrations(dir);
+    const versioned = files.filter((file) => file.kind === 'versioned');
+    const removed = [];
+    for (const file of versioned) {
+        rmSync(file.path);
+        if (existsSync(`${file.path}.conf`))
+            rmSync(`${file.path}.conf`);
+        removed.push(file.script);
+    }
+    const text = readFileSync(schemaFile, 'utf8');
+    const wrote = join(dir, 'V1__baseline.sql');
+    writeFileSync(wrote, `-- The migrations up to here, squashed by ${product()} migrate squash: the schema.sql they built.\n${dialect === 'sqlite' ? sqliteDesired(text) : text}`);
+    return { removed, wrote };
+}

package/dist/server/migrate/files.d.ts

@@ -0,0 +1,34 @@
+export interface MigrationFile {
+    readonly kind: 'versioned' | 'repeatable';
+    /** Flyway's spelling of the version: the name's digits, `_` read as `.`. Absent for a repeatable. */
+    readonly version?: string;
+    /** The name after `__`, underscores as spaces: what the history's description says. */
+    readonly description: string;
+    /** The path under the directory, `/`-separated: the history's script. */
+    readonly script: string;
+    readonly path: string;
+    readonly sql: string;
+    readonly checksum: number;
+    /** False only where the file's `.conf` says `executeInTransaction=false`. */
+    readonly transactional: boolean;
+}
+export interface MigrationDirectory {
+    readonly dir: string;
+    readonly files: readonly MigrationFile[];
+    /** Files that look meant as migrations and are not (`V1_add.sql`): said, never run. */
+    readonly ignored: readonly string[];
+}
+/** Flyway's checksum of a script's text. */
+export declare function flywayChecksum(text: string): number;
+/** Flyway's order of versions: dotted parts compared as numbers, a missing part as 0. */
+export declare function compareVersions(a: string, b: string): number;
+/** Every migration under `dir`, versioned ones in version order, then the repeatables by description. */
+export declare function readMigrations(dir: string): MigrationDirectory;
+/**
+ * Write the next migration's file, empty but for a line that says what the
+ * runner will do with it. The version is one past the highest the directory
+ * holds, in the directory's own style: a team that numbers by timestamp gets a
+ * timestamp. `body` is the file's text when something already wrote it
+ * (`migrate diff`).
+ */
+export declare function newMigration(dir: string, name: string, repeatable: boolean, now?: Date, body?: string): string;