@bockit/sequel 0.0.0-stage → 0.2.0

package/dist/generator/types.js

@@ -0,0 +1,216 @@
+import { singleQuoted } from './strings.js';
+const INTERVAL = '{ years?: number; months?: number; days?: number; hours?: number; minutes?: number; seconds?: number; milliseconds?: number }';
+const POINT = '{ x: number; y: number }';
+const CIRCLE = '{ x: number; y: number; radius: number }';
+const text = (rowArray = ['string']) => ({
+    row: ['string'],
+    rowArray,
+    param: ['string'],
+});
+const number = { row: ['number'], rowArray: ['number'], param: ['number'] };
+const date = { row: ['Date'], rowArray: ['Date'], param: ['Date', 'string'] };
+const json = { row: ['unknown'], rowArray: ['unknown'], param: ['unknown'], json: true };
+const unknown = { row: ['unknown'], rowArray: 'unknown', param: ['unknown'] };
+const BUILTINS = [
+    [['int2', 'smallint', 'smallserial', 'serial2'], number],
+    [['int4', 'integer', 'int', 'serial', 'serial4'], number],
+    [
+        ['int8', 'bigint', 'bigserial', 'serial8'],
+        { row: ['string'], rowArray: ['string'], param: ['bigint', 'number', 'string'], bigint: true },
+    ],
+    [['numeric', 'decimal'], { row: ['string'], rowArray: ['number'], param: ['number', 'string'] }],
+    [['float4', 'real'], number],
+    [['float8', 'double precision', 'float'], number],
+    [['money'], text()],
+    [['text'], text()],
+    [['varchar', 'character varying'], text()],
+    [['bpchar', 'character', 'char'], text()],
+    [['name'], text('parse')],
+    [['uuid'], text()],
+    [['bool', 'boolean'], { row: ['boolean'], rowArray: ['boolean'], param: ['boolean'] }],
+    [['bytea'], { row: ['Buffer'], rowArray: ['Buffer'], param: ['Buffer'] }],
+    [['date'], date],
+    [['time', 'time without time zone'], text()],
+    [['timetz', 'time with time zone'], text()],
+    [['timestamp', 'timestamp without time zone'], date],
+    [['timestamptz', 'timestamp with time zone'], date],
+    [['interval'], { row: [INTERVAL], rowArray: [INTERVAL], param: ['string'] }],
+    [['json'], json],
+    [['jsonb'], json],
+    [['jsonpath'], text('parse')],
+    [['inet', 'cidr', 'macaddr'], text()],
+    [['macaddr8'], text('parse')],
+    [['point'], { row: [POINT], rowArray: [POINT], param: ['string'] }],
+    [['circle'], { row: [CIRCLE], rowArray: 'unknown', param: ['string'] }],
+    [['line', 'lseg', 'path', 'polygon'], text('parse')],
+    [['box'], text('unknown')],
+    [['tsvector', 'tsquery'], text('parse')],
+    [['xml'], text('parse')],
+    [['bit', 'varbit', 'bit varying'], text('parse')],
+    [['numrange'], text()],
+    [['int4range', 'int8range', 'tsrange', 'tstzrange', 'daterange'], text('parse')],
+    [
+        [
+            'int4multirange',
+            'int8multirange',
+            'nummultirange',
+            'tsmultirange',
+            'tstzmultirange',
+            'datemultirange',
+        ],
+        text('parse'),
+    ],
+    [['oid'], number],
+    [['regproc'], text()],
+    [
+        [
+            'regclass',
+            'regtype',
+            'regprocedure',
+            'regoper',
+            'regoperator',
+            'regconfig',
+            'regdictionary',
+            'regnamespace',
+            'regrole',
+            'regcollation',
+        ],
+        text('parse'),
+    ],
+    [['xid', 'xid8', 'cid', 'tid', 'pg_lsn', 'txid_snapshot', 'pg_snapshot'], text('parse')],
+    [['void'], { row: ['null'], rowArray: 'unknown', param: ['unknown'] }],
+];
+const BUILTIN_BY_NAME = new Map(BUILTINS.flatMap(([names, builtin]) => names.map((name) => [name, builtin])));
+const CITEXT = text('parse');
+// R44: splits, unquotes and strips a type name, and counts its array dimensions.
+export function normaliseType(column) {
+    let schema = column.type?.schema ?? '';
+    let name = column.type?.name ?? '';
+    if (schema === '') {
+        const dot = dotOutsideQuotes(name);
+        if (dot !== -1) {
+            schema = name.slice(0, dot);
+            name = name.slice(dot + 1);
+        }
+    }
+    schema = unquote(schema);
+    name = unquote(name);
+    name = name
+        .replace(/\(\s*\d+\s*(,\s*\d+\s*)?\)/g, ' ')
+        .replace(/ +/g, ' ')
+        .trim();
+    if (name.startsWith('interval '))
+        name = 'interval';
+    let count = 0;
+    while (name.endsWith('[]')) {
+        name = name.slice(0, -2).trimEnd();
+        count++;
+    }
+    const dims = Math.max(count, column.array_dims, column.is_array ? 1 : 0);
+    return { schema, name, dims };
+}
+function dotOutsideQuotes(name) {
+    let quoted = false;
+    for (let i = 0; i < name.length; i++) {
+        const char = name[i];
+        if (char === '"')
+            quoted = !quoted;
+        else if (char === '.' && !quoted)
+            return i;
+    }
+    return -1;
+}
+function unquote(part) {
+    if (part.length >= 2 && part.startsWith('"') && part.endsWith('"')) {
+        return part.slice(1, -1).replaceAll('""', '"');
+    }
+    return part;
+}
+// R45: built-ins, then citext in any schema, then the catalog's enums, else unknown.
+export function resolveType(column, catalog) {
+    const { schema, name, dims } = normaliseType(column);
+    if (schema === '' || schema === 'pg_catalog') {
+        const builtin = BUILTIN_BY_NAME.get(name);
+        if (builtin !== undefined)
+            return { base: builtin, dims };
+    }
+    if (name === 'citext')
+        return { base: CITEXT, dims };
+    const vals = findEnum(catalog, schema, name);
+    if (vals !== undefined) {
+        // R47: string literals, in catalog order, escaped as R53 says.
+        const union = vals.map((val) => singleQuoted(val));
+        // An empty enum is `unknown` in a row, because `row[i]` can't be assigned to `never`,
+        // and `never` as a parameter.
+        if (union.length === 0)
+            return { base: { row: ['unknown'], rowArray: 'unknown', param: [] }, dims };
+        return { base: { row: union, rowArray: 'parse', param: union }, dims };
+    }
+    return { base: unknown, dims };
+}
+function findEnum(catalog, schema, name) {
+    if (catalog === null)
+        return undefined;
+    const inSchema = (schemaName) => catalog.schemas.find((s) => s.name === schemaName)?.enums.find((e) => e.name === name)?.vals;
+    if (schema !== '')
+        return inSchema(schema);
+    const fromDefault = inSchema(catalog.default_schema);
+    if (fromDefault !== undefined)
+        return fromDefault;
+    const found = catalog.schemas.flatMap((s) => s.enums.filter((e) => e.name === name));
+    return found.length === 1 ? found[0]?.vals : undefined;
+}
+export function isJson(type) {
+    return type.base.json === true;
+}
+// Whether a row column of this type is built with `parsePgArray` (✱).
+export function needsParse(type) {
+    return type.dims > 0 && type.base.rowArray === 'parse';
+}
+// A row column's TypeScript type (R46, R48). `elementsNotNull` is R64's or `@notnull`'s
+// narrowing of an array's elements.
+export function rowType(type, nullable, elementsNotNull, bigint) {
+    const { base, dims } = type;
+    if (dims === 0) {
+        const members = base.bigint === true ? [bigint] : base.row;
+        return render(members, nullable);
+    }
+    if (base.rowArray === 'unknown')
+        return 'unknown';
+    // ✱ elements come from `parsePgArray` as strings, or as an enum's values.
+    const element = base.rowArray === 'parse' ? base.row : base.bigint === true ? [bigint] : base.rowArray;
+    const isUnknown = element.length === 1 && element[0] === 'unknown';
+    const elementMembers = isUnknown || elementsNotNull ? element : withNull(element);
+    return render([arrayOf(elementMembers, dims)], nullable);
+}
+// A parameter's TypeScript type (R33, R46, R48, R49).
+export function paramType(type, nullable) {
+    const { base, dims } = type;
+    if (dims === 0)
+        return render(base.param, nullable);
+    // An unknown element makes the array unknown; json elements are known, and stringified (R34).
+    if (base.param.length === 1 && base.param[0] === 'unknown' && base.json !== true)
+        return 'unknown';
+    return render([arrayOf(base.param, dims)], nullable);
+}
+function withNull(members) {
+    return members.includes('null') ? members : [...members, 'null'];
+}
+function arrayOf(members, dims) {
+    const element = members.length === 0
+        ? 'never'
+        : members.length === 1
+            ? members[0]
+            : `(${members.join(' | ')})`;
+    return element + '[]'.repeat(dims);
+}
+// Joins union members, with `null` last when nullable. `unknown` absorbs `null`, and an
+// empty union is `never`.
+function render(members, nullable) {
+    if (members.length === 1 && members[0] === 'unknown')
+        return 'unknown';
+    const all = nullable ? withNull(members) : members;
+    if (all.length === 0)
+        return 'never';
+    return all.join(' | ');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { defineConfig } from './config/define-config.ts';
+export type { BigintMode, SequelConfig } from './config/define-config.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+// The only part of sequel an app imports, and only from its config file.
+export { defineConfig } from './config/define-config.js';

package/dist/migrate/adopt-prisma.d.ts

@@ -0,0 +1,23 @@
+import { type Migration } from './files.ts';
+export declare const PRISMA_LOCK_FILE = "migration_lock.toml";
+export type FileAdoption = {
+    renamed: {
+        from: string;
+        to: string;
+    }[];
+    lockRemoved: boolean;
+};
+export declare function adoptPrismaFiles(folder: string, root: string): Promise<FileAdoption>;
+export type HistoryAdoption = {
+    status: 'adopted';
+    rows: number;
+} | {
+    status: 'already-adopted';
+} | {
+    status: 'no-prisma-history';
+};
+export declare function adoptPrismaHistory(options: {
+    url: string;
+    migrations: Migration[];
+    lockWaitMs?: number;
+}): Promise<HistoryAdoption>;

package/dist/migrate/adopt-prisma.js

@@ -0,0 +1,119 @@
+import { existsSync } from 'node:fs';
+import { readdir, rename, rm, rmdir } from 'node:fs/promises';
+import path from 'node:path';
+import { databaseName, withClient } from '../db/connection.js';
+import { SequelError } from '../errors.js';
+import { compare } from './files.js';
+import { acquireLock, createHistoryTable, historyState, recordMigration, releaseLock, } from './history.js';
+const PRISMA_FOLDER = /^\d{14}_[a-z0-9_]+$/;
+export const PRISMA_LOCK_FILE = 'migration_lock.toml';
+// TECH-SPEC §8, the files: each `<ts>_<name>/migration.sql` becomes `<ts>_<name>.sql` in the
+// same parent folder, with its contents untouched, and Prisma's lock file goes. Every move is
+// checked before any is made.
+export async function adoptPrismaFiles(folder, root) {
+    let entries;
+    try {
+        entries = await readdir(folder, { recursive: true, withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { renamed: [], lockRemoved: false };
+        throw error;
+    }
+    const shown = (file) => path.relative(root, file);
+    const moves = [];
+    const problems = [];
+    const targets = new Set();
+    for (const entry of entries) {
+        if (!entry.isFile() || entry.name !== 'migration.sql')
+            continue;
+        const from = path.join(entry.parentPath, entry.name);
+        const dir = entry.parentPath;
+        const name = path.basename(dir);
+        if (!PRISMA_FOLDER.test(name)) {
+            problems.push(`${shown(from)} is in a folder not named \`<YYYYMMDDHHMMSS>_<name>\`, with a lower-case name, so it has no migration identity. Rename the folder to Prisma's form, then run this again.`);
+            continue;
+        }
+        const to = path.join(path.dirname(dir), `${name}.sql`);
+        if (existsSync(to) || targets.has(to)) {
+            problems.push(`${shown(from)} would become ${shown(to)}, which already exists. Remove one.`);
+            continue;
+        }
+        targets.add(to);
+        moves.push({ from, to });
+    }
+    if (problems.length > 0) {
+        throw new SequelError(`Refusing to rename Prisma's migrations, so nothing changed:\n${problems.join('\n')}`);
+    }
+    moves.sort((a, b) => compare(a.from, b.from));
+    for (const move of moves) {
+        await rename(move.from, move.to);
+        // Prisma's folder held only the file; anything else stays, with its folder.
+        await rmdir(path.dirname(move.from)).catch(() => { });
+    }
+    const lock = path.join(folder, PRISMA_LOCK_FILE);
+    const lockRemoved = existsSync(lock);
+    if (lockRemoved)
+        await rm(lock);
+    return { renamed: moves, lockRemoved };
+}
+// TECH-SPEC §8, the history: under the runner's lock, in one transaction that also creates
+// `sequel_migrations`, copy every applied Prisma row once its checksum matches its file.
+// `_prisma_migrations` is only read.
+export async function adoptPrismaHistory(options) {
+    const database = databaseName(options.url);
+    return withClient(options.url, async (client) => {
+        client.on('error', () => { });
+        await acquireLock(client, database, options.lockWaitMs);
+        try {
+            const state = await historyState(client, database);
+            if (state.hasHistory)
+                return { status: 'already-adopted' };
+            if (!state.hasPrismaHistory)
+                return { status: 'no-prisma-history' };
+            const { rows } = await client.query(`SELECT migration_name, checksum, finished_at, rolled_back_at
+         FROM _prisma_migrations ORDER BY migration_name COLLATE "C", started_at`);
+            const files = new Map(options.migrations.map((m) => [m.identity, m]));
+            const problems = [];
+            const adopted = new Map();
+            for (const row of rows) {
+                const name = row.migration_name;
+                if (row.rolled_back_at !== null)
+                    continue;
+                if (row.finished_at === null) {
+                    problems.push(`\`${name}\` was started by Prisma but never finished, and never rolled back: a Prisma deploy failed. Resolve it with Prisma first (\`prisma migrate resolve --applied\` or \`--rolled-back\`), then run this again.`);
+                    continue;
+                }
+                if (adopted.has(name))
+                    continue;
+                const file = files.get(name);
+                if (file === undefined) {
+                    problems.push(`\`${name}\` is applied, but no migration file has that name. Restore it from version control.`);
+                }
+                else if (file.sha256 !== row.checksum) {
+                    problems.push(`${file.shown} has changed since Prisma applied it (sha256 ${row.checksum} then, ${file.sha256} now). Restore the file from version control.`);
+                }
+                adopted.set(name, row);
+            }
+            if (problems.length > 0) {
+                throw new SequelError(`Refusing to adopt the Prisma history of ${database}, so nothing changed:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+            }
+            await client.query('BEGIN');
+            try {
+                await createHistoryTable(client);
+                for (const row of adopted.values()) {
+                    await recordMigration(client, row.migration_name, row.checksum, row.finished_at);
+                }
+                await client.query('COMMIT');
+            }
+            catch (error) {
+                await client.query('ROLLBACK').catch(() => { });
+                throw error;
+            }
+            return { status: 'adopted', rows: adopted.size };
+        }
+        finally {
+            await releaseLock(client).catch(() => { });
+        }
+    });
+}

package/dist/migrate/deploy.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedConfig } from '../config/resolve-config.ts';
+import { type DeployResult } from './runner.ts';
+export declare function deployTo(config: ResolvedConfig, url: string, options: {
+    allowOutOfOrder?: boolean;
+    log: (message: string) => void;
+    quietWhenCurrent?: boolean;
+}): Promise<DeployResult>;

package/dist/migrate/deploy.js

@@ -0,0 +1,23 @@
+import { databaseName } from '../db/connection.js';
+import { findMigrations } from './files.js';
+import { deployMigrations } from './runner.js';
+// Deploys the app's migrations to one of its databases, under the runner's rules, and reports
+// what happened through `log`.
+export async function deployTo(config, url, options) {
+    const migrations = await findMigrations(config.migrations, { root: config.root });
+    const result = await deployMigrations({
+        url,
+        migrations,
+        timeouts: config.timeouts,
+        allowOutOfOrder: options.allowOutOfOrder ?? false,
+        log: options.log,
+    });
+    const database = databaseName(url);
+    for (const name of result.newerApplied) {
+        options.log(`\`${name}\` is applied to ${database} but has no file, and sorts after every file: it is from a newer build, as after a rollback. Continuing.`);
+    }
+    if (result.applied.length === 0 && !options.quietWhenCurrent) {
+        options.log(`No pending migrations: ${database} is up to date.`);
+    }
+    return result;
+}

package/dist/migrate/drift.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedConfig } from '../config/resolve-config.ts';
+import { type DiffResult } from '../engine/diff.ts';
+import type { SchemaFile } from '../schema/schema.ts';
+import type { Migration } from './files.ts';
+export declare function diffMigrationsToSchema(options: {
+    config: ResolvedConfig;
+    migrations: Migration[];
+    files: SchemaFile[];
+    engineBinary?: string;
+}): Promise<DiffResult>;

package/dist/migrate/drift.js

@@ -0,0 +1,36 @@
+import { ensureBinary } from '../binaries/ensure-binary.js';
+import { shadowOptions, withShadowDatabase } from '../db/shadow.js';
+import { startSchemaEngine } from '../engine/client.js';
+import { diffToSchema } from '../engine/diff.js';
+import { SequelError } from '../errors.js';
+import { deployMigrations } from './runner.js';
+// TECH-SPEC §8: the runner replays the migrations into a shadow database, exactly as `deploy`
+// applies them, then the engine diffs that database against the schema folder. A difference is
+// drift for `check`, and the next migration for `migrate new`. It never touches the target.
+export async function diffMigrationsToSchema(options) {
+    const { config } = options;
+    const engineBinary = options.engineBinary ?? (await ensureBinary('schema-engine'));
+    return withShadowDatabase(shadowOptions(config), async (shadowUrl) => {
+        let historySchema;
+        try {
+            ;
+            ({ historySchema } = await deployMigrations({
+                url: shadowUrl,
+                migrations: options.migrations,
+                timeouts: config.timeouts,
+            }));
+        }
+        catch (error) {
+            if (!(error instanceof SequelError))
+                throw error;
+            throw new SequelError(`Replaying the migrations into a shadow database failed:\n${error.message}`);
+        }
+        const engine = startSchemaEngine(engineBinary, config.schema);
+        try {
+            return await diffToSchema(engine, { url: shadowUrl, historySchema }, options.files);
+        }
+        finally {
+            await engine.close();
+        }
+    });
+}

package/dist/migrate/files.d.ts

@@ -0,0 +1,19 @@
+import { type ScannedSql } from './sql-text.ts';
+export type Migration = {
+    identity: string;
+    file: string;
+    shown: string;
+    text: string;
+    sha256: string;
+    noTransaction: boolean;
+    scanned: ScannedSql;
+};
+export declare const MIGRATION_FILE: RegExp;
+export declare const NAME: RegExp;
+export declare function migrationIdentity(now: Date, name: string): string;
+export declare function sha256(bytes: Buffer | string): string;
+export declare function findMigrations(folder: string, options?: {
+    root?: string;
+}): Promise<Migration[]>;
+export declare function readMigrationFile(file: string, root: string): Promise<Migration>;
+export declare function compare(a: string, b: string): number;

package/dist/migrate/files.js

@@ -0,0 +1,97 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { SequelError } from '../errors.js';
+import { noTransactionMarker, scanSql } from './sql-text.js';
+export const MIGRATION_FILE = /^(\d{14})_([a-z0-9_]+)\.sql$/;
+export const NAME = /^[a-z0-9_]+$/;
+// `<YYYYMMDDHHMMSS>_<name>`, with the time in UTC.
+export function migrationIdentity(now, name) {
+    if (!NAME.test(name)) {
+        throw new SequelError(`The migration name \`${name}\` must be lower-case letters, digits and underscores, such as \`add_accounts\`.`);
+    }
+    const stamp = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+    return `${stamp}_${name}`;
+}
+export function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+// TECH-SPEC §8: every `.sql` file under the folder, at any depth, ordered by identity. The path
+// plays no part in order or identity. A missing folder holds no migrations.
+export async function findMigrations(folder, options = {}) {
+    const root = options.root ?? process.cwd();
+    const shown = (file) => path.relative(root, file);
+    const files = await sqlFilesUnder(folder);
+    const problems = [];
+    const byIdentity = new Map();
+    for (const file of files) {
+        const base = path.basename(file);
+        if (base === 'migration.sql') {
+            problems.push(`${shown(file)} is in Prisma's layout. Run \`sequel migrate adopt-prisma\` to rename Prisma's migrations to \`<timestamp>_<name>.sql\` files.`);
+            continue;
+        }
+        if (!MIGRATION_FILE.test(base)) {
+            problems.push(`${shown(file)} is not named as a migration. Every .sql file under ${shown(folder) || '.'} must be named \`<YYYYMMDDHHMMSS>_<name>.sql\`, with a lower-case name; rename it, or move it out of the migrations folder.`);
+            continue;
+        }
+        const identity = base.slice(0, -'.sql'.length);
+        const existing = byIdentity.get(identity);
+        if (existing !== undefined) {
+            problems.push(`${shown(existing.file)} and ${shown(file)} are the same migration, \`${identity}\`. Delete one, or rename it with a new timestamp.`);
+            continue;
+        }
+        const bytes = await readFile(file);
+        const text = bytes.toString('utf8');
+        const scanned = scanSql(text);
+        byIdentity.set(identity, {
+            identity,
+            file,
+            shown: shown(file),
+            text,
+            sha256: sha256(bytes),
+            noTransaction: noTransactionMarker(scanned).noTransaction,
+            scanned,
+        });
+    }
+    if (problems.length > 0)
+        throw new SequelError(problems.join('\n'));
+    return [...byIdentity.values()].sort((a, b) => compare(a.identity, b.identity));
+}
+// Reads one file as a migration, for `migrate lint` on files named on the command line.
+export async function readMigrationFile(file, root) {
+    const bytes = await readFile(file);
+    const text = bytes.toString('utf8');
+    const scanned = scanSql(text);
+    return {
+        identity: path.basename(file).replace(/\.sql$/, ''),
+        file,
+        shown: path.relative(root, file),
+        text,
+        sha256: sha256(bytes),
+        noTransaction: noTransactionMarker(scanned).noTransaction,
+        scanned,
+    };
+}
+// Identities compare by code point, so order never depends on the locale.
+export function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+async function sqlFilesUnder(folder) {
+    let entries;
+    try {
+        entries = await readdir(folder, { recursive: true, withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.sql'))
+        .map((entry) => path.join(entry.parentPath, entry.name))
+        .filter((file) => !path
+        .relative(folder, file)
+        .split(path.sep)
+        .some((part) => part.startsWith('.')))
+        .sort(compare);
+}

package/dist/migrate/history.d.ts

@@ -0,0 +1,20 @@
+import type pg from 'pg';
+export declare const HISTORY_TABLE = "sequel_migrations";
+export declare const LOCK_KEY = "126879532410220";
+export declare const LOCK_WAIT_MS: number;
+export type HistoryRow = {
+    name: string;
+    sha256: string;
+    appliedAt: Date;
+};
+export type HistoryState = {
+    schema: string;
+    hasHistory: boolean;
+    hasPrismaHistory: boolean;
+};
+export declare function acquireLock(client: pg.Client, database: string, waitMs?: number): Promise<void>;
+export declare function releaseLock(client: pg.Client): Promise<void>;
+export declare function historyState(client: pg.Client, database: string): Promise<HistoryState>;
+export declare function createHistoryTable(client: pg.Client): Promise<void>;
+export declare function readHistory(client: pg.Client): Promise<HistoryRow[]>;
+export declare function recordMigration(client: pg.Client, name: string, sha256: string, appliedAt?: Date): Promise<void>;

package/dist/migrate/history.js

@@ -0,0 +1,54 @@
+import { SequelError } from '../errors.js';
+// sequel's migration history: one row per applied file, in the connection's default schema.
+export const HISTORY_TABLE = 'sequel_migrations';
+// The advisory lock every sequel run that writes the history takes: "sequel" as a number.
+// It blocks only other sequel runs; application queries never take it.
+export const LOCK_KEY = '126879532410220';
+// How long a run waits for another run's lock before failing.
+export const LOCK_WAIT_MS = 10 * 60_000;
+// Takes the session-level advisory lock, waiting up to `waitMs`. Postgres applies
+// `lock_timeout` to advisory locks, so the wait is bounded without polling.
+export async function acquireLock(client, database, waitMs = LOCK_WAIT_MS) {
+    await client.query(`SET lock_timeout = '${Math.trunc(waitMs)}ms'`);
+    try {
+        await client.query('SELECT pg_advisory_lock($1::bigint)', [LOCK_KEY]);
+    }
+    catch (error) {
+        if (error.code === '55P03') {
+            throw new SequelError(`Another sequel run has held the migration lock on ${database} for ${Math.round(waitMs / 1000)} s. Wait for it to finish, then run this again.`);
+        }
+        throw error;
+    }
+    finally {
+        await client.query('RESET lock_timeout');
+    }
+}
+export async function releaseLock(client) {
+    await client.query('SELECT pg_advisory_unlock($1::bigint)', [LOCK_KEY]);
+}
+// Which histories the database has. Both names resolve through the search path, as an
+// unqualified `CREATE TABLE` would place them.
+export async function historyState(client, database) {
+    const { rows } = await client.query(`SELECT current_schema() AS schema,
+            to_regclass('${HISTORY_TABLE}') IS NOT NULL AS history,
+            to_regclass('_prisma_migrations') IS NOT NULL AS prisma`);
+    const row = rows[0];
+    if (row?.schema == null) {
+        throw new SequelError(`${database} has no schema on its search path to hold ${HISTORY_TABLE}. Create the schema, such as \`public\`, or fix the role's search_path.`);
+    }
+    return { schema: row.schema, hasHistory: row.history, hasPrismaHistory: row.prisma };
+}
+export async function createHistoryTable(client) {
+    await client.query(`CREATE TABLE IF NOT EXISTS ${HISTORY_TABLE} (
+      name text PRIMARY KEY,
+      sha256 text NOT NULL,
+      applied_at timestamptz NOT NULL DEFAULT now()
+    )`);
+}
+export async function readHistory(client) {
+    const { rows } = await client.query(`SELECT name, sha256, applied_at FROM ${HISTORY_TABLE} ORDER BY name COLLATE "C"`);
+    return rows.map((row) => ({ name: row.name, sha256: row.sha256, appliedAt: row.applied_at }));
+}
+export async function recordMigration(client, name, sha256, appliedAt) {
+    await client.query(`INSERT INTO ${HISTORY_TABLE} (name, sha256, applied_at) VALUES ($1, $2, coalesce($3, now()))`, [name, sha256, appliedAt ?? null]);
+}

package/dist/migrate/lint.d.ts

@@ -0,0 +1,21 @@
+import { type Migration } from './files.ts';
+import type { UnsupportedColumns } from '../schema/unsupported.ts';
+export type LintFinding = {
+    shown: string;
+    line: number;
+    column: number;
+    rule: string;
+    message: string;
+};
+export declare const DEFAULT_SQUAWK_CONFIG = "pg_version = \"18.0\"\nexcluded_rules = [\n  \"prefer-bigint-over-int\",\n  \"prefer-identity\",\n  \"require-enum-value-ordering\",\n  \"require-lock-timeout\",\n  \"require-statement-timeout\",\n]\n";
+export declare const SQUAWK_CONFIG_FILE = ".squawk.toml";
+export declare function migrationsToLint(migrations: Migration[], cutover: string | undefined): Migration[];
+export declare function lintMigrations(options: {
+    squawk: string;
+    migrations: Migration[];
+    root: string;
+    unsupported?: UnsupportedColumns;
+}): Promise<LintFinding[]>;
+export declare function formatFinding(finding: LintFinding): string;
+export declare function ownRules(migration: Migration, unsupported?: UnsupportedColumns): LintFinding[];
+export declare function lintFailureMessage(findings: LintFinding[]): string;