@typesql/core 0.8.1 → 0.9.0

package/README.md

@@ -71,6 +71,43 @@ const query = findUser(7);
 
 Named parameters and fixed fragments work too. The `pg` and `postgres` adapters also request server-side preparation when these queries execute. See the [prepared query API](https://typesql.karsli.net/reference/api#sql-prepare-text-slots).
 
+## Tracked migrations
+
+The separate `@typesql/core/migration` entry point loads TypeScript migration files and runs them against PostgreSQL or SQLite on Node 26. Each file exports `up` and `down`:
+
+```ts
+import type { PostgresMigration } from "@typesql/core/migration";
+
+export async function up(db: PostgresMigration) {
+  const next = await db.add("CREATE TABLE users (id int PRIMARY KEY, name text NOT NULL)");
+  await next("INSERT INTO users (id, name) VALUES ($1, $2)", 1, "Ada").execute();
+  return next;
+}
+
+export async function down(db: PostgresMigration) {
+  await db.raw("DROP TABLE users");
+}
+```
+
+Use `SqliteMigration` for SQLite. Later files can declare their starting schema as
+`PostgresMigration<MigrationSchema<typeof previousUp>>` by importing the previous
+`up` as a type. Await `.add()` or `.raw<NewSchema>()` into a new constant to retain
+the updated schema; return that context from `up`, including for a no-op migration.
+`down` may return nothing.
+
+`migrateUp`, `migrateDown`, and `migrateLatest` accept `{ dialect, migrationsDir,
+execute, migrationTable? }`. `execute` is a TypeSQL executor bound to one dedicated
+database connection for the entire call. Files run in filename order, each in its
+own transaction, with SHA-256 history checks and concurrency protection. A failed
+file rolls back while earlier committed files remain applied. Migration code must
+await every database operation and leave transaction management to the runner.
+The default tracking table is `schema_migrations`. Hashes cover each migration
+file's runtime code; imported runtime helpers are not tracked.
+
+For configuration, file generation, and command-line execution, install
+`@typesql/cli` and use `typesql migrate make <name>`, `up`, `down`, or `latest`.
+See the [migration guide](https://typesql.karsli.net/guide/migrations).
+
 ## Documentation
 
 The full guide is at **[typesql.karsli.net](https://typesql.karsli.net)**. It covers the [schema](https://typesql.karsli.net/guide/schema), [parameters](https://typesql.karsli.net/guide/parameters), [writing data](https://typesql.karsli.net/guide/writing-data), [dynamic SQL](https://typesql.karsli.net/guide/dynamic-sql), [migrations](https://typesql.karsli.net/guide/migrations), the [type cache](https://typesql.karsli.net/guide/performance) and [known limits](https://typesql.karsli.net/guide/limits).

package/dist/migration/context.d.ts

@@ -0,0 +1,35 @@
+import type { ApplyDdlOf, DialectTypes, ValidateDdlOf } from "../dialect.js";
+import type { EngineTypes } from "../engine/contract.js";
+import type { ParamsOf, RowOf } from "../engine/infer.js";
+import { type Postgres } from "../postgres/dialect.js";
+import type { PgEngine } from "../postgres/engine/engine.js";
+import type { Executor, Query } from "../query.js";
+import type { SqlApi } from "../sql/api.js";
+import type { BoxCallArgs, BoxSlottedArgs, CallRet, GateCallCheck, GateSlottedCheck, SplicedOr } from "../sql/call.js";
+import type { SlotMap, SlotsFor } from "../sql/slots.js";
+import { type Sqlite } from "../sqlite/dialect.js";
+import type { SqliteEngine } from "../sqlite/engine/engine.js";
+type GateDdl<T extends DialectTypes, DB, Q extends string> = [DB, Q] extends [
+    infer D,
+    infer Text extends string
+] ? ValidateDdlOf<T, D, Text> : never;
+/** A checked SQL executor whose schema evolves after each awaited DDL statement. */
+export interface MigrationContext<E extends EngineTypes, T extends DialectTypes, DB, TM = T["typeMap"]> extends Omit<SqlApi<E, DB, TM>, "raw"> {
+    /** Type-only schema marker; no database introspection is performed. */
+    readonly schema: DB;
+    <const Q extends string>(query: GateCallCheck<E, DB, TM, "preserve", Q> & Q, ...params: BoxCallArgs<E, DB, TM, "preserve", Q>): CallRet<E, DB, TM, "preserve", Q>;
+    <const Q extends string, const S extends SlotMap>(query: GateSlottedCheck<E, DB, TM, Q, S> & Q, slots: S & SlotsFor<Q, S>, ...params: BoxSlottedArgs<E, DB, TM, Q, S>): Query<RowOf<E, DB, TM, SplicedOr<Q, S>>, ParamsOf<E, DB, TM, SplicedOr<Q, S>>, SplicedOr<Q, S>>;
+    add<const Q extends string>(ddl: GateDdl<T, DB, Q> & Q): Promise<MigrationContext<E, T, ApplyDdlOf<T, DB, Q>, TM>>;
+    /** Execute SQL the checker cannot see, explicitly asserting its resulting schema. */
+    raw<NewSchema = DB>(sql: string): Promise<MigrationContext<E, T, NewSchema, TM>>;
+}
+export type PostgresMigration<Base = {}> = MigrationContext<PgEngine, Postgres, Base>;
+export type SqliteMigration<Base = {}> = MigrationContext<SqliteEngine, Sqlite, Base>;
+/** Extract the final schema returned by an async migration's up function. */
+export type MigrationSchema<Up extends (...args: never[]) => unknown> = Awaited<ReturnType<Up>> extends {
+    readonly schema: infer Schema;
+} ? Schema : never;
+/** Internal factory: execution is bound to the runner's active transaction. */
+export declare function createMigrationContext(dialect: "postgres" | "sqlite", execute: Executor): PostgresMigration | SqliteMigration;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/migration/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/migration/context.ts"],"names":[],"mappings":"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"}

package/dist/migration/context.js

@@ -0,0 +1,15 @@
+import { createDialectSql } from "../create-sql.js";
+import { postgres } from "../postgres/dialect.js";
+import { sqlite } from "../sqlite/dialect.js";
+/** Internal factory: execution is bound to the runner's active transaction. */
+export function createMigrationContext(dialect, execute) {
+    const sql = dialect === "postgres"
+        ? createDialectSql(postgres, execute)
+        : createDialectSql(sqlite, execute);
+    const next = async (statement) => {
+        await execute(statement, []);
+        return createMigrationContext(dialect, execute);
+    };
+    return Object.assign(sql, { add: next, raw: next });
+}
+//# sourceMappingURL=context.js.map

package/dist/migration/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/migration/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIpD,OAAO,EAAiB,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAajE,OAAO,EAAe,MAAM,EAAE,MAAM,sBAAsB,CAAC;AA0D3D,+EAA+E;AAC/E,MAAM,UAAU,sBAAsB,CACrC,OAA8B,EAC9B,OAAiB;IAEjB,MAAM,GAAG,GACR,OAAO,KAAK,UAAU;QACrB,CAAC,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC;QACrC,CAAC,CAAC,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,KAAK,EAAE,SAAiB,EAAE,EAAE;QACxC,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAC7B,OAAO,sBAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC,CAAC;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAEhC,CAAC;AACpB,CAAC"}

package/dist/migration/files.d.ts

@@ -0,0 +1,19 @@
+/** A discovered TypeScript migration. Loading uses Node's native TypeScript support. */
+export interface MigrationFile {
+    readonly name: string;
+    readonly path: string;
+    readonly hash: string;
+    load(): Promise<MigrationModule>;
+}
+export interface MigrationModule {
+    readonly up: (context: never) => unknown;
+    readonly down: (context: never) => unknown;
+}
+/**
+ * Hash the erased JavaScript's syntax tree and original runtime token spellings.
+ * Tree boundaries preserve automatic semicolon insertion (including return/newline)
+ * while trivia and TypeScript-only declarations do not contribute to the hash.
+ */
+export declare function migrationHash(source: string): string;
+export declare function discoverMigrations(migrationsDir: string): Promise<readonly MigrationFile[]>;
+//# sourceMappingURL=files.d.ts.map

package/dist/migration/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/migration/files.ts"],"names":[],"mappings":"AAQA,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,OAAO,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,OAAO,CAAC;CAC3C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqBpD;AAED,wBAAsB,kBAAkB,CACvC,aAAa,EAAE,MAAM,GACnB,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CA0CnC"}

package/dist/migration/files.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { stripTypeScriptTypes } from "node:module";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { formatSyntaxKind } from "typescript/ast";
+import { API } from "typescript/sync";
+/**
+ * Hash the erased JavaScript's syntax tree and original runtime token spellings.
+ * Tree boundaries preserve automatic semicolon insertion (including return/newline)
+ * while trivia and TypeScript-only declarations do not contribute to the hash.
+ */
+export function migrationHash(source) {
+    const javascript = stripTypeScriptTypes(source);
+    const api = new API();
+    try {
+        const lease = api.createSourceFile("migration.js", javascript);
+        const file = lease.sourceFile;
+        const hash = createHash("sha256");
+        const visit = (node) => {
+            if (formatSyntaxKind(node.kind).startsWith("JSDoc"))
+                return;
+            const children = node.getChildren(file);
+            hash.update(`${formatSyntaxKind(node.kind)}[`);
+            if (children.length === 0)
+                hash.update(JSON.stringify(node.getText(file)));
+            else
+                for (const child of children)
+                    visit(child);
+            hash.update("]");
+        };
+        visit(file);
+        return hash.digest("hex");
+    }
+    finally {
+        api.close();
+    }
+}
+export async function discoverMigrations(migrationsDir) {
+    const directory = resolve(migrationsDir);
+    const entries = await readdir(directory, { withFileTypes: true });
+    const names = entries
+        .filter((entry) => (entry.isFile() || entry.isSymbolicLink()) &&
+        entry.name.endsWith(".ts"))
+        .map((entry) => entry.name)
+        .sort();
+    return Promise.all(names.map(async (name) => {
+        const path = resolve(directory, name);
+        const source = await readFile(path, "utf8");
+        const hash = migrationHash(source);
+        return {
+            name,
+            path,
+            hash,
+            async load() {
+                if (migrationHash(await readFile(path, "utf8")) !== hash)
+                    throw new Error(`Migration changed during execution: ${name}`);
+                const url = pathToFileURL(path);
+                url.searchParams.set("typesql", hash);
+                const module = await import(url.href);
+                if (module === null ||
+                    typeof module !== "object" ||
+                    !("up" in module) ||
+                    typeof module.up !== "function" ||
+                    !("down" in module) ||
+                    typeof module.down !== "function")
+                    throw new Error(`Migration must export up and down functions: ${name}`);
+                return module;
+            },
+        };
+    }));
+}
+//# sourceMappingURL=files.js.map

package/dist/migration/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/migration/files.ts"],"names":[],"mappings":"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"}

package/dist/migration/index.d.ts

@@ -0,0 +1,4 @@
+export type { MigrationContext, MigrationSchema, PostgresMigration, SqliteMigration, } from "./context.js";
+export { discoverMigrations, type MigrationFile, type MigrationModule, migrationHash, } from "./files.js";
+export { type MigrationOptions, type MigrationResult, migrateDown, migrateLatest, migrateUp, } from "./runtime.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/migration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migration/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,eAAe,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,aAAa,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,WAAW,EACX,aAAa,EACb,SAAS,GACT,MAAM,cAAc,CAAC"}

package/dist/migration/index.js

@@ -0,0 +1,3 @@
+export { discoverMigrations, migrationHash, } from "./files.js";
+export { migrateDown, migrateLatest, migrateUp, } from "./runtime.js";
+//# sourceMappingURL=index.js.map

package/dist/migration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migration/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACN,kBAAkB,EAGlB,aAAa,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAGN,WAAW,EACX,aAAa,EACb,SAAS,GACT,MAAM,cAAc,CAAC"}

package/dist/migration/runtime.d.ts

@@ -0,0 +1,16 @@
+import type { Executor } from "../query.js";
+export interface MigrationOptions {
+    readonly dialect: "postgres" | "sqlite";
+    readonly migrationsDir: string;
+    readonly migrationTable?: string;
+    /** A dedicated connection, kept open and unused by other work until completion. */
+    readonly execute: Executor;
+}
+export interface MigrationResult {
+    readonly direction: "up" | "down";
+    readonly migrations: readonly string[];
+}
+export declare function migrateUp(options: MigrationOptions): Promise<MigrationResult>;
+export declare function migrateDown(options: MigrationOptions): Promise<MigrationResult>;
+export declare function migrateLatest(options: MigrationOptions): Promise<MigrationResult>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/migration/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/migration/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,aAAa,CAAC;AAI5D,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAOD,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAE7E;AAED,wBAAgB,WAAW,CAC1B,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,eAAe,CAAC,CAE1B;AAED,wBAAgB,aAAa,CAC5B,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,eAAe,CAAC,CAE1B"}

package/dist/migration/runtime.js

@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import { createMigrationContext } from "./context.js";
+import { discoverMigrations } from "./files.js";
+export function migrateUp(options) {
+    return migrate(options, "up", false);
+}
+export function migrateDown(options) {
+    return migrate(options, "down", false);
+}
+export function migrateLatest(options) {
+    return migrate(options, "up", true);
+}
+function identifier(name) {
+    if (!name || name.includes("\0"))
+        throw new Error("Migration table and schema names must be nonempty and contain no NUL");
+    return `"${name.replaceAll('"', '""')}"`;
+}
+async function rows(execute, text, values = []) {
+    const result = await execute(text, values);
+    return Array.isArray(result) ? result : result.rows;
+}
+function readHistory(records) {
+    return records.map((record) => {
+        if (typeof record !== "object" ||
+            record === null ||
+            !("name" in record) ||
+            typeof record.name !== "string" ||
+            !("hash" in record) ||
+            typeof record.hash !== "string")
+            throw new Error("Invalid migration history: expected string name and hash columns");
+        return { name: record.name, hash: record.hash };
+    });
+}
+function validateHistory(files, applied) {
+    const byName = new Map(files.map((file) => [file.name, file]));
+    const appliedNames = new Set(applied.map((file) => file.name));
+    let latest = "";
+    for (const entry of applied) {
+        const file = byName.get(entry.name);
+        if (!file)
+            throw new Error(`Applied migration is missing: ${entry.name}`);
+        if (file.hash !== entry.hash)
+            throw new Error(`Applied migration has changed: ${entry.name}`);
+        if (entry.name > latest)
+            latest = entry.name;
+    }
+    for (const file of files)
+        if (!appliedNames.has(file.name) && file.name < latest)
+            throw new Error(`Pending migration sorts before an applied migration: ${file.name}`);
+}
+async function migrate(options, direction, all) {
+    if (options.dialect !== "postgres" && options.dialect !== "sqlite")
+        throw new Error(`Unsupported migration dialect: ${String(options.dialect)}`);
+    const files = await discoverMigrations(options.migrationsDir);
+    const tableName = options.migrationTable ?? "schema_migrations";
+    let table = identifier(tableName);
+    const execute = options.execute;
+    const postgres = options.dialect === "postgres";
+    let lock;
+    if (postgres) {
+        const [location] = await rows(execute, "SELECT current_schema() AS schema, current_database() AS database, current_setting('max_identifier_length')::integer AS max_identifier_length");
+        if (typeof location !== "object" ||
+            location === null ||
+            !("schema" in location) ||
+            typeof location.schema !== "string" ||
+            !("database" in location) ||
+            typeof location.database !== "string" ||
+            !("max_identifier_length" in location) ||
+            typeof location.max_identifier_length !== "number")
+            throw new Error("Cannot determine the PostgreSQL migration schema");
+        if (Buffer.byteLength(tableName, "utf8") > location.max_identifier_length)
+            throw new Error(`Migration table name exceeds PostgreSQL's ${location.max_identifier_length}-byte identifier limit`);
+        table = `${identifier(location.schema)}.${table}`;
+        lock = createHash("sha256")
+            .update(JSON.stringify([location.database, location.schema, tableName]))
+            .digest()
+            .readBigInt64BE()
+            .toString();
+        await execute("SELECT pg_advisory_lock($1::bigint)", [lock]);
+    }
+    const completed = [];
+    try {
+        for (;;) {
+            await execute(postgres ? "BEGIN" : "BEGIN IMMEDIATE", []);
+            try {
+                await execute(`CREATE TABLE IF NOT EXISTS ${table} (name TEXT PRIMARY KEY NOT NULL, hash TEXT NOT NULL, applied_at ${postgres ? "TIMESTAMPTZ" : "TEXT"} NOT NULL DEFAULT CURRENT_TIMESTAMP)`, []);
+                // SQLite must read history only after obtaining its write lock.
+                const history = readHistory(await rows(execute, `SELECT name, hash FROM ${table}`));
+                validateHistory(files, history);
+                const applied = new Set(history.map((file) => file.name));
+                const selected = direction === "up"
+                    ? files.find((file) => !applied.has(file.name))
+                    : files.findLast((file) => applied.has(file.name));
+                if (!selected) {
+                    await execute("ROLLBACK", []);
+                    break;
+                }
+                const migration = await selected.load();
+                let active = true;
+                const checkActiveSql = (sql) => {
+                    if (!active)
+                        throw new Error("Migration context cannot execute after its migration has finished");
+                    assertMigrationSql(sql, options.dialect);
+                };
+                const count = execute.count;
+                const guarded = Object.assign(async (sql, values) => {
+                    checkActiveSql(sql);
+                    return execute(sql, values);
+                }, count === undefined
+                    ? {}
+                    : {
+                        count: async (sql, values) => {
+                            checkActiveSql(sql);
+                            return count(sql, values);
+                        },
+                    });
+                try {
+                    const context = createMigrationContext(options.dialect, guarded);
+                    await migration[direction](context);
+                }
+                finally {
+                    active = false;
+                }
+                if (direction === "up")
+                    await execute(`INSERT INTO ${table} (name, hash) VALUES ($1, $2)`, [
+                        selected.name,
+                        selected.hash,
+                    ]);
+                else
+                    await execute(`DELETE FROM ${table} WHERE name = $1`, [
+                        selected.name,
+                    ]);
+                await execute("COMMIT", []);
+                completed.push(selected.name);
+            }
+            catch (error) {
+                try {
+                    await execute("ROLLBACK", []);
+                }
+                catch (rollbackError) {
+                    throw new AggregateError([error, rollbackError], "Migration failed and rollback also failed");
+                }
+                throw error;
+            }
+            if (!all)
+                break;
+        }
+        return { direction, migrations: completed };
+    }
+    finally {
+        if (lock !== undefined)
+            await execute("SELECT pg_advisory_unlock($1::bigint)", [lock]);
+    }
+}
+/** Keep transaction ownership with the runner, including multi-statement raw SQL. */
+function assertMigrationSql(sql, dialect) {
+    const words = [];
+    const checkRollback = () => {
+        if (words[0] === "ROLLBACK" &&
+            words[1] !== "TO" &&
+            !((words[1] === "WORK" || words[1] === "TRANSACTION") &&
+                words[2] === "TO"))
+            throw new Error("Migrations cannot roll back their enclosing transaction; use ROLLBACK TO a savepoint");
+    };
+    let trigger = false;
+    let start = true;
+    for (let i = 0; i < sql.length;) {
+        const char = sql.charAt(i);
+        if (/\s/.test(char)) {
+            i++;
+            continue;
+        }
+        if (sql.startsWith("--", i)) {
+            const end = /[\r\n]/.exec(sql.slice(i + 2));
+            i = end === null ? sql.length : i + 2 + end.index + 1;
+            continue;
+        }
+        if (sql.startsWith("/*", i)) {
+            let depth = 1;
+            i += 2;
+            while (i < sql.length && depth > 0) {
+                if (sql.startsWith("/*", i) && dialect === "postgres") {
+                    depth++;
+                    i += 2;
+                }
+                else if (sql.startsWith("*/", i)) {
+                    depth--;
+                    i += 2;
+                }
+                else
+                    i++;
+            }
+            continue;
+        }
+        if (char === "'" ||
+            char === '"' ||
+            (dialect === "sqlite" && (char === "`" || char === "["))) {
+            const end = char === "[" ? "]" : char;
+            const escapes = dialect === "postgres" &&
+                char === "'" &&
+                /[eE]/.test(sql[i - 1] ?? "") &&
+                !/[\w$]/.test(sql[i - 2] ?? "");
+            i++;
+            while (i < sql.length) {
+                if (escapes && sql[i] === "\\")
+                    i += 2;
+                else if (sql[i] === end) {
+                    if (sql[i + 1] === end && char !== "[")
+                        i += 2;
+                    else {
+                        i++;
+                        break;
+                    }
+                }
+                else
+                    i++;
+            }
+            if (words.length < 4)
+                words.push("");
+            start = false;
+            continue;
+        }
+        if (char === "$" && dialect === "postgres") {
+            const tag = /^\$(?:[a-zA-Z_][a-zA-Z_0-9]*)?\$/.exec(sql.slice(i))?.[0];
+            if (tag) {
+                const end = sql.indexOf(tag, i + tag.length);
+                i = end < 0 ? sql.length : end + tag.length;
+                if (words.length < 4)
+                    words.push("");
+                start = false;
+                continue;
+            }
+        }
+        if (char === ";") {
+            checkRollback();
+            words.length = 0;
+            start = true;
+            i++;
+            continue;
+        }
+        const word = /^[a-zA-Z_][a-zA-Z_0-9$]*/.exec(sql.slice(i))?.[0];
+        if (word) {
+            const upper = word.toUpperCase();
+            if (trigger && start && upper === "END")
+                trigger = false;
+            else if (!trigger &&
+                start &&
+                /^(BEGIN|START|COMMIT|END|ABORT)$/.test(upper))
+                throw new Error("Migrations cannot control transactions; each migration runs in its own transaction");
+            if (words.length < 4)
+                words.push(upper);
+            if (words.length === 2 &&
+                words[0] === "PREPARE" &&
+                upper === "TRANSACTION")
+                throw new Error("Migrations cannot prepare transactions");
+            if (dialect === "sqlite" &&
+                upper === "TRIGGER" &&
+                (words.join(" ") === "CREATE TRIGGER" ||
+                    words.join(" ") === "CREATE TEMP TRIGGER" ||
+                    words.join(" ") === "CREATE TEMPORARY TRIGGER"))
+                trigger = true;
+            start = false;
+            i += word.length;
+            continue;
+        }
+        if (words.length < 4)
+            words.push("");
+        start = false;
+        i++;
+    }
+    checkRollback();
+}
+//# sourceMappingURL=runtime.js.map

package/dist/migration/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/migration/runtime.ts"],"names":[],"mappings":"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"}

package/dist/postgres/engine/cache.d.ts

@@ -17,7 +17,7 @@ export interface DdlCache {
 }
 export interface DdlCacheKeys {
 }
-export type CacheVersion = "2d89fa38d8f5";
+export type CacheVersion = "19a89f093fa1";
 export type Stale<DB, D extends DbSnapshot> = (D["v"] extends CacheVersion ? never : "*") | (Same<EnumsOf<DB>, D["t"]> extends true ? never : "*") | {
     [W in keyof D["w"] & string]: WordFresh<DB, W, D["w"][W]> extends true ? never : W;
 }[keyof D["w"] & string] | {

package/dist/sqlite/engine/cache.d.ts

@@ -15,7 +15,7 @@ export interface DdlCache {
 }
 export interface DdlCacheKeys {
 }
-export type CacheVersion = "2d89fa38d8f5";
+export type CacheVersion = "19a89f093fa1";
 export type Stale<DB, D extends DbSnapshot> = (D["v"] extends CacheVersion ? never : "*") | {
     [W in keyof D["w"] & string]: Same<Relations<DB, W>, D["w"][W][0]> extends true ? Same<Named<Functions<DB>, W>, D["w"][W][1]> extends true ? Same<Named<FunctionCatalog, W>, D["w"][W][2]> extends true ? never : W : W : W;
 }[keyof D["w"] & string] | Shared.StaleExtras<DB, D, HintIndex<DB>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typesql/core",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Type-level SQL inference for TypeScript: PostgreSQL (tested against PostgreSQL 18's regression suite) and SQLite. Zero runtime dependencies.",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,10 @@
     "./sqlite/engine": {
       "types": "./dist/sqlite/engine/index.d.ts",
       "default": "./dist/sqlite/engine/index.js"
+    },
+    "./migration": {
+      "types": "./dist/migration/index.d.ts",
+      "default": "./dist/migration/index.js"
     }
   },
   "files": [

package/src/migration/context.ts

@@ -0,0 +1,92 @@
+import { createDialectSql } from "../create-sql.js";
+import type { ApplyDdlOf, DialectTypes, ValidateDdlOf } from "../dialect.js";
+import type { EngineTypes } from "../engine/contract.js";
+import type { ParamsOf, RowOf } from "../engine/infer.js";
+import { type Postgres, postgres } from "../postgres/dialect.js";
+import type { PgEngine } from "../postgres/engine/engine.js";
+import type { Executor, Query } from "../query.js";
+import type { SqlApi } from "../sql/api.js";
+import type {
+	BoxCallArgs,
+	BoxSlottedArgs,
+	CallRet,
+	GateCallCheck,
+	GateSlottedCheck,
+	SplicedOr,
+} from "../sql/call.js";
+import type { SlotMap, SlotsFor } from "../sql/slots.js";
+import { type Sqlite, sqlite } from "../sqlite/dialect.js";
+import type { SqliteEngine } from "../sqlite/engine/engine.js";
+
+type GateDdl<T extends DialectTypes, DB, Q extends string> = [DB, Q] extends [
+	infer D,
+	infer Text extends string,
+]
+	? ValidateDdlOf<T, D, Text>
+	: never;
+
+/** A checked SQL executor whose schema evolves after each awaited DDL statement. */
+export interface MigrationContext<
+	E extends EngineTypes,
+	T extends DialectTypes,
+	DB,
+	TM = T["typeMap"],
+> extends Omit<SqlApi<E, DB, TM>, "raw"> {
+	/** Type-only schema marker; no database introspection is performed. */
+	readonly schema: DB;
+	<const Q extends string>(
+		query: GateCallCheck<E, DB, TM, "preserve", Q> & Q,
+		...params: BoxCallArgs<E, DB, TM, "preserve", Q>
+	): CallRet<E, DB, TM, "preserve", Q>;
+	<const Q extends string, const S extends SlotMap>(
+		query: GateSlottedCheck<E, DB, TM, Q, S> & Q,
+		slots: S & SlotsFor<Q, S>,
+		...params: BoxSlottedArgs<E, DB, TM, Q, S>
+	): Query<
+		RowOf<E, DB, TM, SplicedOr<Q, S>>,
+		ParamsOf<E, DB, TM, SplicedOr<Q, S>>,
+		SplicedOr<Q, S>
+	>;
+	add<const Q extends string>(
+		ddl: GateDdl<T, DB, Q> & Q,
+	): Promise<MigrationContext<E, T, ApplyDdlOf<T, DB, Q>, TM>>;
+	/** Execute SQL the checker cannot see, explicitly asserting its resulting schema. */
+	raw<NewSchema = DB>(
+		sql: string,
+	): Promise<MigrationContext<E, T, NewSchema, TM>>;
+}
+
+export type PostgresMigration<Base = {}> = MigrationContext<
+	PgEngine,
+	Postgres,
+	Base
+>;
+export type SqliteMigration<Base = {}> = MigrationContext<
+	SqliteEngine,
+	Sqlite,
+	Base
+>;
+
+/** Extract the final schema returned by an async migration's up function. */
+export type MigrationSchema<Up extends (...args: never[]) => unknown> =
+	Awaited<ReturnType<Up>> extends { readonly schema: infer Schema }
+		? Schema
+		: never;
+
+/** Internal factory: execution is bound to the runner's active transaction. */
+export function createMigrationContext(
+	dialect: "postgres" | "sqlite",
+	execute: Executor,
+): PostgresMigration | SqliteMigration {
+	const sql =
+		dialect === "postgres"
+			? createDialectSql(postgres, execute)
+			: createDialectSql(sqlite, execute);
+	const next = async (statement: string) => {
+		await execute(statement, []);
+		return createMigrationContext(dialect, execute);
+	};
+	return Object.assign(sql, { add: next, raw: next }) as unknown as
+		| PostgresMigration
+		| SqliteMigration;
+}

package/src/migration/files.ts

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { stripTypeScriptTypes } from "node:module";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { formatSyntaxKind, type Node } from "typescript/ast";
+import { API } from "typescript/sync";
+
+/** A discovered TypeScript migration. Loading uses Node's native TypeScript support. */
+export interface MigrationFile {
+	readonly name: string;
+	readonly path: string;
+	readonly hash: string;
+	load(): Promise<MigrationModule>;
+}
+
+export interface MigrationModule {
+	readonly up: (context: never) => unknown;
+	readonly down: (context: never) => unknown;
+}
+
+/**
+ * Hash the erased JavaScript's syntax tree and original runtime token spellings.
+ * Tree boundaries preserve automatic semicolon insertion (including return/newline)
+ * while trivia and TypeScript-only declarations do not contribute to the hash.
+ */
+export function migrationHash(source: string): string {
+	const javascript = stripTypeScriptTypes(source);
+	const api = new API();
+	try {
+		const lease = api.createSourceFile("migration.js", javascript);
+		const file = lease.sourceFile;
+		const hash = createHash("sha256");
+		const visit = (node: Node): void => {
+			if (formatSyntaxKind(node.kind).startsWith("JSDoc")) return;
+			const children = node.getChildren(file);
+			hash.update(`${formatSyntaxKind(node.kind)}[`);
+			if (children.length === 0)
+				hash.update(JSON.stringify(node.getText(file)));
+			else for (const child of children) visit(child);
+			hash.update("]");
+		};
+		visit(file);
+		return hash.digest("hex");
+	} finally {
+		api.close();
+	}
+}
+
+export async function discoverMigrations(
+	migrationsDir: string,
+): Promise<readonly MigrationFile[]> {
+	const directory = resolve(migrationsDir);
+	const entries = await readdir(directory, { withFileTypes: true });
+	const names = entries
+		.filter(
+			(entry) =>
+				(entry.isFile() || entry.isSymbolicLink()) &&
+				entry.name.endsWith(".ts"),
+		)
+		.map((entry) => entry.name)
+		.sort();
+	return Promise.all(
+		names.map(async (name): Promise<MigrationFile> => {
+			const path = resolve(directory, name);
+			const source = await readFile(path, "utf8");
+			const hash = migrationHash(source);
+			return {
+				name,
+				path,
+				hash,
+				async load() {
+					if (migrationHash(await readFile(path, "utf8")) !== hash)
+						throw new Error(`Migration changed during execution: ${name}`);
+					const url = pathToFileURL(path);
+					url.searchParams.set("typesql", hash);
+					const module: unknown = await import(url.href);
+					if (
+						module === null ||
+						typeof module !== "object" ||
+						!("up" in module) ||
+						typeof module.up !== "function" ||
+						!("down" in module) ||
+						typeof module.down !== "function"
+					)
+						throw new Error(
+							`Migration must export up and down functions: ${name}`,
+						);
+					return module as MigrationModule;
+				},
+			};
+		}),
+	);
+}

package/src/migration/index.ts

@@ -0,0 +1,19 @@
+export type {
+	MigrationContext,
+	MigrationSchema,
+	PostgresMigration,
+	SqliteMigration,
+} from "./context.js";
+export {
+	discoverMigrations,
+	type MigrationFile,
+	type MigrationModule,
+	migrationHash,
+} from "./files.js";
+export {
+	type MigrationOptions,
+	type MigrationResult,
+	migrateDown,
+	migrateLatest,
+	migrateUp,
+} from "./runtime.js";

package/src/migration/runtime.ts

@@ -0,0 +1,348 @@
+import { createHash } from "node:crypto";
+import type { Executor, ExecutorResult } from "../query.js";
+import { createMigrationContext } from "./context.js";
+import { discoverMigrations, type MigrationFile } from "./files.js";
+
+export interface MigrationOptions {
+	readonly dialect: "postgres" | "sqlite";
+	readonly migrationsDir: string;
+	readonly migrationTable?: string;
+	/** A dedicated connection, kept open and unused by other work until completion. */
+	readonly execute: Executor;
+}
+
+export interface MigrationResult {
+	readonly direction: "up" | "down";
+	readonly migrations: readonly string[];
+}
+
+interface AppliedMigration {
+	readonly name: string;
+	readonly hash: string;
+}
+
+export function migrateUp(options: MigrationOptions): Promise<MigrationResult> {
+	return migrate(options, "up", false);
+}
+
+export function migrateDown(
+	options: MigrationOptions,
+): Promise<MigrationResult> {
+	return migrate(options, "down", false);
+}
+
+export function migrateLatest(
+	options: MigrationOptions,
+): Promise<MigrationResult> {
+	return migrate(options, "up", true);
+}
+
+function identifier(name: string): string {
+	if (!name || name.includes("\0"))
+		throw new Error(
+			"Migration table and schema names must be nonempty and contain no NUL",
+		);
+	return `"${name.replaceAll('"', '""')}"`;
+}
+
+async function rows(
+	execute: Executor,
+	text: string,
+	values: readonly unknown[] = [],
+): Promise<readonly unknown[]> {
+	const result = await execute(text, values);
+	return Array.isArray(result) ? result : (result as ExecutorResult).rows;
+}
+
+function readHistory(records: readonly unknown[]): AppliedMigration[] {
+	return records.map((record) => {
+		if (
+			typeof record !== "object" ||
+			record === null ||
+			!("name" in record) ||
+			typeof record.name !== "string" ||
+			!("hash" in record) ||
+			typeof record.hash !== "string"
+		)
+			throw new Error(
+				"Invalid migration history: expected string name and hash columns",
+			);
+		return { name: record.name, hash: record.hash };
+	});
+}
+
+function validateHistory(
+	files: readonly MigrationFile[],
+	applied: readonly AppliedMigration[],
+): void {
+	const byName = new Map(files.map((file) => [file.name, file]));
+	const appliedNames = new Set(applied.map((file) => file.name));
+	let latest = "";
+	for (const entry of applied) {
+		const file = byName.get(entry.name);
+		if (!file) throw new Error(`Applied migration is missing: ${entry.name}`);
+		if (file.hash !== entry.hash)
+			throw new Error(`Applied migration has changed: ${entry.name}`);
+		if (entry.name > latest) latest = entry.name;
+	}
+	for (const file of files)
+		if (!appliedNames.has(file.name) && file.name < latest)
+			throw new Error(
+				`Pending migration sorts before an applied migration: ${file.name}`,
+			);
+}
+
+async function migrate(
+	options: MigrationOptions,
+	direction: "up" | "down",
+	all: boolean,
+): Promise<MigrationResult> {
+	if (options.dialect !== "postgres" && options.dialect !== "sqlite")
+		throw new Error(
+			`Unsupported migration dialect: ${String(options.dialect)}`,
+		);
+	const files = await discoverMigrations(options.migrationsDir);
+	const tableName = options.migrationTable ?? "schema_migrations";
+	let table = identifier(tableName);
+	const execute = options.execute;
+	const postgres = options.dialect === "postgres";
+	let lock: string | undefined;
+	if (postgres) {
+		const [location] = await rows(
+			execute,
+			"SELECT current_schema() AS schema, current_database() AS database, current_setting('max_identifier_length')::integer AS max_identifier_length",
+		);
+		if (
+			typeof location !== "object" ||
+			location === null ||
+			!("schema" in location) ||
+			typeof location.schema !== "string" ||
+			!("database" in location) ||
+			typeof location.database !== "string" ||
+			!("max_identifier_length" in location) ||
+			typeof location.max_identifier_length !== "number"
+		)
+			throw new Error("Cannot determine the PostgreSQL migration schema");
+		if (Buffer.byteLength(tableName, "utf8") > location.max_identifier_length)
+			throw new Error(
+				`Migration table name exceeds PostgreSQL's ${location.max_identifier_length}-byte identifier limit`,
+			);
+		table = `${identifier(location.schema)}.${table}`;
+		lock = createHash("sha256")
+			.update(JSON.stringify([location.database, location.schema, tableName]))
+			.digest()
+			.readBigInt64BE()
+			.toString();
+		await execute("SELECT pg_advisory_lock($1::bigint)", [lock]);
+	}
+	const completed: string[] = [];
+
+	try {
+		for (;;) {
+			await execute(postgres ? "BEGIN" : "BEGIN IMMEDIATE", []);
+			try {
+				await execute(
+					`CREATE TABLE IF NOT EXISTS ${table} (name TEXT PRIMARY KEY NOT NULL, hash TEXT NOT NULL, applied_at ${postgres ? "TIMESTAMPTZ" : "TEXT"} NOT NULL DEFAULT CURRENT_TIMESTAMP)`,
+					[],
+				);
+				// SQLite must read history only after obtaining its write lock.
+				const history = readHistory(
+					await rows(execute, `SELECT name, hash FROM ${table}`),
+				);
+				validateHistory(files, history);
+				const applied = new Set(history.map((file) => file.name));
+				const selected =
+					direction === "up"
+						? files.find((file) => !applied.has(file.name))
+						: files.findLast((file) => applied.has(file.name));
+				if (!selected) {
+					await execute("ROLLBACK", []);
+					break;
+				}
+				const migration = await selected.load();
+				let active = true;
+				const checkActiveSql = (sql: string): void => {
+					if (!active)
+						throw new Error(
+							"Migration context cannot execute after its migration has finished",
+						);
+					assertMigrationSql(sql, options.dialect);
+				};
+				const count = execute.count;
+				const guarded: Executor = Object.assign(
+					async (sql: string, values: readonly unknown[]) => {
+						checkActiveSql(sql);
+						return execute(sql, values);
+					},
+					count === undefined
+						? {}
+						: {
+								count: async (sql: string, values: readonly unknown[]) => {
+									checkActiveSql(sql);
+									return count(sql, values);
+								},
+							},
+				);
+				try {
+					const context = createMigrationContext(options.dialect, guarded);
+					await migration[direction](context as never);
+				} finally {
+					active = false;
+				}
+				if (direction === "up")
+					await execute(`INSERT INTO ${table} (name, hash) VALUES ($1, $2)`, [
+						selected.name,
+						selected.hash,
+					]);
+				else
+					await execute(`DELETE FROM ${table} WHERE name = $1`, [
+						selected.name,
+					]);
+				await execute("COMMIT", []);
+				completed.push(selected.name);
+			} catch (error) {
+				try {
+					await execute("ROLLBACK", []);
+				} catch (rollbackError) {
+					throw new AggregateError(
+						[error, rollbackError],
+						"Migration failed and rollback also failed",
+					);
+				}
+				throw error;
+			}
+			if (!all) break;
+		}
+		return { direction, migrations: completed };
+	} finally {
+		if (lock !== undefined)
+			await execute("SELECT pg_advisory_unlock($1::bigint)", [lock]);
+	}
+}
+
+/** Keep transaction ownership with the runner, including multi-statement raw SQL. */
+function assertMigrationSql(
+	sql: string,
+	dialect: MigrationOptions["dialect"],
+): void {
+	const words: string[] = [];
+	const checkRollback = (): void => {
+		if (
+			words[0] === "ROLLBACK" &&
+			words[1] !== "TO" &&
+			!(
+				(words[1] === "WORK" || words[1] === "TRANSACTION") &&
+				words[2] === "TO"
+			)
+		)
+			throw new Error(
+				"Migrations cannot roll back their enclosing transaction; use ROLLBACK TO a savepoint",
+			);
+	};
+	let trigger = false;
+	let start = true;
+	for (let i = 0; i < sql.length; ) {
+		const char = sql.charAt(i);
+		if (/\s/.test(char)) {
+			i++;
+			continue;
+		}
+		if (sql.startsWith("--", i)) {
+			const end = /[\r\n]/.exec(sql.slice(i + 2));
+			i = end === null ? sql.length : i + 2 + end.index + 1;
+			continue;
+		}
+		if (sql.startsWith("/*", i)) {
+			let depth = 1;
+			i += 2;
+			while (i < sql.length && depth > 0) {
+				if (sql.startsWith("/*", i) && dialect === "postgres") {
+					depth++;
+					i += 2;
+				} else if (sql.startsWith("*/", i)) {
+					depth--;
+					i += 2;
+				} else i++;
+			}
+			continue;
+		}
+		if (
+			char === "'" ||
+			char === '"' ||
+			(dialect === "sqlite" && (char === "`" || char === "["))
+		) {
+			const end = char === "[" ? "]" : char;
+			const escapes =
+				dialect === "postgres" &&
+				char === "'" &&
+				/[eE]/.test(sql[i - 1] ?? "") &&
+				!/[\w$]/.test(sql[i - 2] ?? "");
+			i++;
+			while (i < sql.length) {
+				if (escapes && sql[i] === "\\") i += 2;
+				else if (sql[i] === end) {
+					if (sql[i + 1] === end && char !== "[") i += 2;
+					else {
+						i++;
+						break;
+					}
+				} else i++;
+			}
+			if (words.length < 4) words.push("");
+			start = false;
+			continue;
+		}
+		if (char === "$" && dialect === "postgres") {
+			const tag = /^\$(?:[a-zA-Z_][a-zA-Z_0-9]*)?\$/.exec(sql.slice(i))?.[0];
+			if (tag) {
+				const end = sql.indexOf(tag, i + tag.length);
+				i = end < 0 ? sql.length : end + tag.length;
+				if (words.length < 4) words.push("");
+				start = false;
+				continue;
+			}
+		}
+		if (char === ";") {
+			checkRollback();
+			words.length = 0;
+			start = true;
+			i++;
+			continue;
+		}
+		const word = /^[a-zA-Z_][a-zA-Z_0-9$]*/.exec(sql.slice(i))?.[0];
+		if (word) {
+			const upper = word.toUpperCase();
+			if (trigger && start && upper === "END") trigger = false;
+			else if (
+				!trigger &&
+				start &&
+				/^(BEGIN|START|COMMIT|END|ABORT)$/.test(upper)
+			)
+				throw new Error(
+					"Migrations cannot control transactions; each migration runs in its own transaction",
+				);
+			if (words.length < 4) words.push(upper);
+			if (
+				words.length === 2 &&
+				words[0] === "PREPARE" &&
+				upper === "TRANSACTION"
+			)
+				throw new Error("Migrations cannot prepare transactions");
+			if (
+				dialect === "sqlite" &&
+				upper === "TRIGGER" &&
+				(words.join(" ") === "CREATE TRIGGER" ||
+					words.join(" ") === "CREATE TEMP TRIGGER" ||
+					words.join(" ") === "CREATE TEMPORARY TRIGGER")
+			)
+				trigger = true;
+			start = false;
+			i += word.length;
+			continue;
+		}
+		if (words.length < 4) words.push("");
+		start = false;
+		i++;
+	}
+	checkRollback();
+}

package/src/postgres/engine/cache.ts

@@ -26,7 +26,7 @@ export interface CacheSnapshots {}
 export interface DdlCache {}
 export interface DdlCacheKeys {}
 
-export type CacheVersion = "2d89fa38d8f5";
+export type CacheVersion = "19a89f093fa1";
 
 export type Stale<DB, D extends DbSnapshot> =
 	| (D["v"] extends CacheVersion ? never : "*")

package/src/sqlite/engine/cache.ts

@@ -20,7 +20,7 @@ export interface CacheSnapshots {}
 export interface DdlCache {}
 export interface DdlCacheKeys {}
 
-export type CacheVersion = "2d89fa38d8f5";
+export type CacheVersion = "19a89f093fa1";
 
 export type Stale<DB, D extends DbSnapshot> =
 	| (D["v"] extends CacheVersion ? never : "*")