kysely-ddl 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow [SemVer](https://semver.org/).
 
+## [Unreleased]
+
+## [0.2.0] — 2026-09-12
+
+### Added
+
+- `concurrently: true` on an index in `defineTable`: the index is built and
+  dropped with `CONCURRENTLY`. Postgres refuses that inside a transaction and
+  inside a multi-statement query, so the generator writes such statements into a
+  migration of their own, `<stamp>_<name>_concurrently.sql`, marked
+  `--> no-transaction` and split by `--> statement-breakpoint`, with a
+  `DROP INDEX CONCURRENTLY IF EXISTS` in front of every create so that a rerun
+  after a failure is clean. `GenerateResult.concurrently` holds these
+  statements. Toggling the flag on an existing index is not a change; the
+  snapshot records it, and older snapshots read as `false`.
+- `--> no-transaction`: a header marker in a `.sql` migration. The runner honors
+  it under `transaction: 'each'` and `'none'` and rejects it under `'all'`
+  before applying anything. `sqlFileMigrationProvider` turns it into
+  `config: { transaction: false }` for Kysely 0.30+
+  (`transactionMode: 'per-migration'`); on older Kysely the marked migration
+  fails with a clear error when the `Migrator` runs it inside a transaction.
+- `MigrationError.line`: the line postgres pointed at inside the failing query.
+- `readMigration`, `renderConcurrentStatements`, `NO_TRANSACTION_MARKER`,
+  `CONCURRENTLY_SUFFIX` and the `MigrationFile` type.
+
+### Changed
+
+- **Breaking:** entry points. `kysely-ddl/kysely` is gone: `inferKyselyTable`,
+  `inferKyselyDatabase`, `jsonb`, `jsonbArray` and the `Jsonb` type now come
+  from `kysely-ddl`, which therefore imports `kysely`, the peer dependency, at
+  runtime. The runner (`createMigrator`, `migrateToLatest`, `MigrationError`,
+  `DEFAULT_JOURNAL_TABLE`, `MIGRATION_LOCK_ID` and their types) and
+  `sqlFileMigrationProvider` moved to the new `kysely-ddl/migrator`, so that a
+  project which applies its migrations some other way does not pull them in.
+- **Breaking:** the `defineTable` option `tableName` is now `name`.
+- **Breaking:** the runner's default `transaction` mode is `'each'` instead of
+  `'all'`, so that a generated `_concurrently` migration runs out of the box.
+  Pass `transaction: 'all'` to keep the whole run atomic.
+- **Breaking:** `writeMigration` returns the names of the files written, an
+  array, instead of one name.
+- **Breaking:** a `Change` of kind `dropIndex` carries `concurrently`.
+- Ordinary migrations are written as plain SQL, without
+  `--> statement-breakpoint`, and the runner sends such a file to postgres as
+  one query: postgres runs it as one implicit transaction and reports the
+  failing line. Files with breakpoints, hand-written or `_concurrently`, are
+  still sent one chunk at a time.
+
 ## [0.1.0] — 2026-09-10
 
 First release.

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/hehmonke/kysely-ddl/actions/workflows/ci.yml/badge.svg)](https://github.com/hehmonke/kysely-ddl/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/kysely-ddl)](https://www.npmjs.com/package/kysely-ddl)
+[![license](https://img.shields.io/npm/l/kysely-ddl)](LICENSE)
 
 PostgreSQL schema as TypeScript code, SQL migrations generated from snapshot
 diffs, Kysely table types, and a migration runner on top of your `Kysely`.
@@ -28,8 +29,8 @@ Bun, or any PostgreSQL dialect for Kysely. Runtime: Node >= 20 or Bun >= 1.2.
 
 | import | contents |
 |---|---|
-| `kysely-ddl` | table definitions, migration generation, migration files on disk. Does not import Kysely |
-| `kysely-ddl/kysely` | `inferKyselyTable`, `inferKyselyDatabase`, `jsonb` / `jsonbArray`, `createMigrator` / `migrateToLatest`, `sqlFileMigrationProvider` |
+| `kysely-ddl` | table definitions, migration generation, migration files on disk, `inferKyselyTable` / `inferKyselyDatabase`, `jsonb` / `jsonbArray` |
+| `kysely-ddl/migrator` | running migrations: `createMigrator` / `migrateToLatest` and `sqlFileMigrationProvider`. A separate entry point, so that a project which applies its migrations some other way does not pull the runner in |
 
 ## Quick start
 
@@ -39,7 +40,7 @@ Bun, or any PostgreSQL dialect for Kysely. Runtime: Node >= 20 or Bun >= 1.2.
 import { defineTable, ref, sql } from 'kysely-ddl';
 
 export const userTable = defineTable({
-  tableName: 'user',
+  name: 'user',
   // builders arrive as an argument; they are not exported one by one
   columns: t => ({
     // no explicit column name -> derived from the property: created_at, apple_id, ...
@@ -56,7 +57,7 @@ export const userTable = defineTable({
 });
 
 export const sessionTable = defineTable({
-  tableName: 'session',
+  name: 'session',
   columns: t => ({
     id: t.uuid().notNull().default(sql`gen_random_uuid()`),
     userId: t.uuid().notNull(),
@@ -75,17 +76,19 @@ import * as schema from './schema';
 const dir = './migrations';
 const result = generateMigration([schema.userTable, schema.sessionTable], readLatestSnapshot(dir));
 
-if (result.statements.length === 0) {
+if (result.changes.length === 0) {
   console.log('no changes');
 } else {
-  console.log(writeMigration(dir, process.argv[2] ?? 'migration', result)); // 20260910123045_migration
+  // one file, or two when the diff has indexes built CONCURRENTLY:
+  // [ '20260910123045_migration', '20260910123046_migration_concurrently' ]
+  console.log(writeMigration(dir, process.argv[2] ?? 'migration', result));
 }
 ```
 
 `migrate.ts`, applying migrations:
 
 ```ts
-import { migrateToLatest } from 'kysely-ddl/kysely';
+import { migrateToLatest } from 'kysely-ddl/migrator';
 import { Kysely, PostgresDialect } from 'kysely';
 import pg from 'pg';
 
@@ -102,7 +105,7 @@ try {
 Types for queries:
 
 ```ts
-import type { inferKyselyDatabase } from 'kysely-ddl/kysely';
+import type { inferKyselyDatabase } from 'kysely-ddl';
 import * as schema from './schema';
 
 type DB = inferKyselyDatabase<typeof schema>;
@@ -120,7 +123,7 @@ A hybrid: columns as chains, everything else as a declarative block.
 |---|---|
 | column types | `t.uuid` `t.varchar({ length })` `t.integer` `t.bigint` `t.boolean` `t.numeric({ precision, scale })` `t.timestamp({ withTimezone, precision })` `t.jsonb` `t.enum([...])` |
 | modifiers | `.notNull()` `.default(v \| sql)` `.defaultNow()` `.array()` `.$type<T>()` `.generatedAlwaysAsIdentity()` |
-| table | `primaryKey` (composite too), `uniques`, `indexes` (unique and partial via `where`), `foreignKeys` (`onDelete` / `onUpdate`), `checks`; names are optional everywhere |
+| table | `primaryKey` (composite too), `uniques`, `indexes` (unique, partial via `where`, built online via `concurrently`), `foreignKeys` (`onDelete` / `onUpdate`), `checks`; names are optional everywhere |
 | expressions | `` sql`...` `` with column and literal interpolation, `inArray(c.status, [...])` |
 
 When a column name is not given, it is derived from the property name with the
@@ -183,17 +186,16 @@ Collisions are caught too: two objects on the same columns, an index named like
 a unique constraint, a check with neither columns nor a name, two properties
 mapping to the same database name.
 
-### What is missing
+### Limitations
 
 Native enums, stored generated columns, schemas other than `public`, views,
-`DEFERRABLE`, covering indexes, index methods other than btree. Everything is
-added the same way: a field in `TableSpec` -> a field in the snapshot -> a branch
-in the diff -> a branch in the renderer.
+`DEFERRABLE`, covering indexes, index methods other than btree. Pull requests are
+welcome; [CONTRIBUTING.md](CONTRIBUTING.md) describes how such a feature is added.
 
 ## Types for Kysely
 
 ```ts
-import type { inferKyselyDatabase, inferKyselyTable } from 'kysely-ddl/kysely';
+import type { inferKyselyDatabase, inferKyselyTable } from 'kysely-ddl';
 import type { Insertable, Selectable } from 'kysely';
 
 type UserTable = inferKyselyTable<typeof userTable>;
@@ -255,7 +257,7 @@ and the `Jsonb<T>` brand in the write types keeps raw objects and strings from
 slipping past them:
 
 ```ts
-import { jsonb, jsonbArray } from 'kysely-ddl/kysely';
+import { jsonb, jsonbArray } from 'kysely-ddl';
 
 await db.insertInto('user').values({ settings: jsonb({ theme: 'dark', tags: ['a'] }) }).execute();
 await db.updateTable('user').set({ settings: jsonb({ theme: 'light' }) }).where('id', '=', id).execute();
@@ -294,15 +296,56 @@ migrations/
   snapshot.json
 ```
 
-`writeMigration(dir, name, result)` writes the `.sql` file and updates
-`snapshot.json`, `readLatestSnapshot(dir)` reads it for the next diff, and
+`writeMigration(dir, name, result)` writes the `.sql` files and updates
+`snapshot.json`, returning the names in application order.
+`readLatestSnapshot(dir)` reads the snapshot for the next diff, and
 `listMigrations(dir)` returns names in the order the runner applies them (by
 character codes, like Kysely). There is no separate journal on disk: the table in
 the database knows what has been applied.
 
-Inside a `.sql` file, statements are separated by the `--> statement-breakpoint`
-comment: the file stays valid for `psql`, and the runner splits on it to execute
-statements one at a time so that an error points at a specific statement.
+An ordinary migration is plain SQL. The runner sends the whole file to postgres
+as one query, and postgres runs a multi-statement query as one implicit
+transaction, so even under `transaction: 'none'` a failing statement rolls the
+file back. `MigrationError.line` says which line postgres pointed at.
+
+### Indexes built `CONCURRENTLY`
+
+`CREATE INDEX CONCURRENTLY` does not lock the table against writes, but postgres
+refuses it inside a transaction and inside a multi-statement query alike. An
+index declared with `concurrently: true` is therefore written as a migration of
+its own, one second after the ordinary one:
+
+```ts
+indexes: [{ columns: ['userId'], concurrently: true }],
+```
+
+```
+migrations/
+  20260910120000_add_tickets.sql               <- the table and its fk, one transaction
+  20260910120001_add_tickets_concurrently.sql  <- the index, outside any transaction
+```
+
+```sql
+--> no-transaction
+DROP INDEX CONCURRENTLY IF EXISTS "ticket_user_id_idx";
+--> statement-breakpoint
+CREATE INDEX CONCURRENTLY "ticket_user_id_idx" ON "ticket" ("user_id");
+```
+
+The `--> no-transaction` marker in the header tells the runner to skip the
+transaction, and `--> statement-breakpoint` makes it send the statements one at a
+time, which `CONCURRENTLY` also demands. Both are comments for `psql`. Dropping
+such an index is `DROP INDEX CONCURRENTLY` in the same kind of file. A failed
+`CREATE INDEX CONCURRENTLY` leaves an invalid index behind while the migration
+stays unrecorded, hence the `DROP INDEX CONCURRENTLY IF EXISTS` in front: the
+rerun is clean. Toggling `concurrently` on an existing index changes nothing.
+
+The runner applies such a migration under the default `transaction: 'each'` and
+under `'none'`, and rejects it under `'all'` before touching the database; through the provider,
+Kysely's `Migrator` needs `transactionMode: 'per-migration'` (Kysely 0.30+).
+Both markers may also be written by hand. A `--> no-transaction` below the
+header is an error: postgres would take it for a comment. `readMigration(dir, name)`
+returns the execution chunks together with the `transaction` flag.
 
 Names are monotonic: if the previous migration was created in the same second,
 the timestamp is bumped forward, otherwise the suffix would decide the order.
@@ -340,13 +383,13 @@ The runner takes a ready `Kysely` with any PostgreSQL dialect and works through
 single connection (`db.connection()`): the lock and the transaction live on it.
 
 ```ts
-import { createMigrator, migrateToLatest } from 'kysely-ddl/kysely';
+import { createMigrator, migrateToLatest } from 'kysely-ddl/migrator';
 
 const migrator = createMigrator({
   db,                          // a Kysely instance, not a Transaction
   migrationsDir: './migrations',
   journalTable: 'kysely_migration', // the default, same as Kysely
-  transaction: 'all',          // 'all' | 'each' | 'none'
+  transaction: 'each',         // the default; 'all' | 'each' | 'none'
   allowUnordered: false,
 });
 
@@ -358,13 +401,15 @@ await migrateToLatest({ db, migrationsDir: './migrations' }); // the same in one
 
 | option | effect |
 |---|---|
-| `transaction: 'all'` | the whole run in one transaction, like Kysely: a failing migration rolls back the earlier ones from the same run |
-| `transaction: 'each'` | one transaction per migration: the ones before the failure stay applied |
-| `transaction: 'none'` | no transactions, for `CREATE INDEX CONCURRENTLY` and the like |
+| `transaction: 'each'` | the default: one transaction per migration, the ones before the failure stay applied. A `--> no-transaction` migration runs without one, its journal row in autocommit right after it |
+| `transaction: 'all'` | the whole run in one transaction, like Kysely: a failing migration rolls back the earlier ones from the same run. A `--> no-transaction` migration is an error before anything is applied: one shared transaction cannot leave it out |
+| `transaction: 'none'` | no `BEGIN` at all. A plain file still runs as one implicit transaction; only a file split by `--> statement-breakpoint` fails statement by statement. `--> no-transaction` changes nothing here |
 | `allowUnordered` | apply migrations that sort before already applied ones (branch merges). An error by default |
 
-A failing statement throws `MigrationError` with `migration`, `statement`,
-`applied` (what this run applied before the failure) and the driver's `cause`.
+A failing query throws `MigrationError` with `migration`, `statement` (the text
+sent: a whole file, or one chunk between breakpoints), `line` (where postgres
+pointed inside it), `applied` (what this run applied before the failure) and the
+driver's `cause`.
 A migration present in the journal but missing on disk is an error: restore the
 file from history or delete the row by hand.
 
@@ -378,13 +423,22 @@ lock is the same `pg_advisory_lock`. So `.sql` migrations can also be run by the
 built-in `Migrator`, and the two runners can alternate on one database:
 
 ```ts
-import { sqlFileMigrationProvider } from 'kysely-ddl/kysely';
+import { sqlFileMigrationProvider } from 'kysely-ddl/migrator';
 import { Migrator } from 'kysely/migration';
 
 const migrator = new Migrator({ db, provider: sqlFileMigrationProvider('./migrations') });
 const { error, results } = await migrator.migrateToLatest();
 ```
 
+`--> no-transaction` reaches the `Migrator` as `config: { transaction: false }`
+on the migration, the field Kysely 0.30+ honors under
+`new Migrator({ ..., transactionMode: 'per-migration' })`: every migration in
+its own transaction, the marked one without. Under the default `'per-run'`
+Kysely itself reports the marked migration as an error and applies nothing.
+Older Kysely ignores `config`; there the marked migration checks that it is not
+inside a transaction and fails with an error naming the fix, and the only way to
+run it is `disableTransactions: true` for the whole run.
+
 There are no rollbacks: the generator only writes forward. Without `down`,
 Kysely skips a migration on `migrateDown` (`NotExecuted`) and leaves it in the
 journal, so by default the provider supplies a `down` that fails with a clear
@@ -415,23 +469,13 @@ What the checks showed on `pg` 8.23 and `Bun.SQL` 1.4 (parameters via Kysely):
 Reading jsonb, JSON arrays, `jsonb[]` and `varchar[]` yields parsed JS values
 with both drivers.
 
-## Development
-
-```bash
-bun install
-bun run db:up                                   # postgres:18-alpine on 54329
-DATABASE_URL=postgres://postgres:postgres@localhost:54329/kysely_ddl bun test
-bun run typecheck && bun run lint && bun run build
-DATABASE_URL=... bun run smoke:node             # the built dist under Node with pg
-```
-
-Without `DATABASE_URL` the integration tests are skipped, the unit tests always
-run. Type-level checks live in `test/types.test-d.ts` and are read by `tsc` only.
+## Contributing
 
-Releases are tagged `vX.Y.Z`, matching `version` in `package.json`: GitHub
-Actions runs the checks and does `npm publish` with provenance. It needs the
-`NPM_TOKEN` secret in the repository settings.
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/hehmonke/kysely-ddl/issues). [CONTRIBUTING.md](CONTRIBUTING.md)
+covers setting up the repository, running the tests and cutting a release.
+Changes between versions are listed in [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
-MIT.
+[MIT](LICENSE)

package/dist/generator/diff.d.ts

@@ -63,6 +63,8 @@ export type Change = {
 } | {
     readonly kind: 'dropIndex';
     readonly index: string;
+    /** `DROP INDEX CONCURRENTLY`, in the `--> no-transaction` migration together with the concurrent creates. */
+    readonly concurrently: boolean;
 };
 export declare function diffSnapshots(prev: Snapshot, next: Snapshot): Change[];
 export {};

package/dist/generator/diff.js

@@ -24,6 +24,7 @@ function sameConstraint(a, b) {
     }
     return false;
 }
+/** `concurrently` is left out on purpose: it says how to build the index, not what the index is. */
 function sameIndex(a, b) {
     return a.unique === b.unique && sameArray(a.columns, b.columns) && a.where === b.where;
 }
@@ -137,13 +138,15 @@ export function diffSnapshots(prev, next) {
                 createIndexes.push({ kind: 'createIndex', table: after.name, index });
             }
             else if (!sameIndex(old, index)) {
-                dropIndexes.push({ kind: 'dropIndex', index: index.name });
+                // the drop follows the NEW flag: both statements must land in the same
+                // migration, or the create would run before the drop
+                dropIndexes.push({ kind: 'dropIndex', index: index.name, concurrently: index.concurrently });
                 createIndexes.push({ kind: 'createIndex', table: after.name, index });
             }
         }
         for (const index of before.indexes) {
             if (!afterIndexes.has(index.name)) {
-                dropIndexes.push({ kind: 'dropIndex', index: index.name });
+                dropIndexes.push({ kind: 'dropIndex', index: index.name, concurrently: index.concurrently });
             }
         }
     }

package/dist/generator/generate.d.ts

@@ -7,13 +7,19 @@ import type { AnyTable } from '../table/define.ts';
 import { type Change } from './diff.ts';
 import { type Snapshot } from './snapshot.ts';
 export interface GenerateResult {
-    /** Migration SQL; an empty string means no changes. */
+    /** The migration text, without the `CONCURRENTLY` statements; an empty string means none. */
     readonly sql: string;
-    /** The same SQL as individual statements; the runner executes these. */
+    /** The same SQL statement by statement. */
     readonly statements: readonly string[];
+    /**
+     * The `CONCURRENTLY` index statements. Postgres refuses them inside a
+     * transaction and inside a multi-statement query alike, so `writeMigration`
+     * puts them into a migration of their own, marked `--> no-transaction`.
+     */
+    readonly concurrently: readonly string[];
     /** The snapshot to store next to the migration. */
     readonly snapshot: Snapshot;
-    /** Parsed changes; handy for tests and for a "what changed" summary. */
+    /** Parsed changes; handy for tests and for a "what changed" summary. Empty means nothing to write. */
     readonly changes: readonly Change[];
 }
 export declare function generateMigration(tables: readonly AnyTable[], previous?: Snapshot): GenerateResult;

package/dist/generator/generate.js

@@ -1,8 +1,14 @@
 import { diffSnapshots } from './diff.js';
-import { renderChanges, renderStatements } from './render.js';
+import { renderChanges, renderConcurrentStatements, renderStatements } from './render.js';
 import { buildSnapshot, EMPTY_SNAPSHOT } from './snapshot.js';
 export function generateMigration(tables, previous = EMPTY_SNAPSHOT) {
     const snapshot = buildSnapshot(tables);
     const changes = diffSnapshots(previous, snapshot);
-    return { sql: renderChanges(changes), statements: renderStatements(changes), snapshot, changes };
+    return {
+        sql: renderChanges(changes),
+        statements: renderStatements(changes),
+        concurrently: renderConcurrentStatements(changes),
+        snapshot,
+        changes,
+    };
 }

package/dist/generator/render.d.ts

@@ -1,6 +1,15 @@
 import type { Change } from './diff.ts';
 export declare function renderChange(change: Change): string[];
-/** Individual statements; `writeMigration` writes these to disk. */
+/** The statements of the ordinary migration, that is, everything but the `CONCURRENTLY` ones. */
 export declare function renderStatements(changes: readonly Change[]): string[];
-/** Multi-line statements are separated by a blank line, single-line ones follow each other. */
+/**
+ * The statements of the `--> no-transaction` migration: `CONCURRENTLY` drops and
+ * creates. A replaced index yields its drop twice, as a change of its own and as
+ * the guard in front of the create, so duplicates are folded.
+ */
+export declare function renderConcurrentStatements(changes: readonly Change[]): string[];
+/**
+ * The ordinary migration as one text: multi-line statements are separated by a
+ * blank line, single-line ones follow each other. `writeMigration` writes it as is.
+ */
 export declare function renderChanges(changes: readonly Change[]): string;

package/dist/generator/render.js

@@ -67,8 +67,19 @@ function createTable(table) {
 }
 function createIndex(table, index) {
     const unique = index.unique ? 'UNIQUE ' : '';
+    const concurrently = index.concurrently ? 'CONCURRENTLY ' : '';
     const where = index.where === null ? '' : ` WHERE ${index.where}`;
-    return `CREATE ${unique}INDEX ${q(index.name)} ON ${q(table)} (${columns(index.columns)})${where};`;
+    return `CREATE ${unique}INDEX ${concurrently}${q(index.name)} ON ${q(table)} (${columns(index.columns)})${where};`;
+}
+function dropIndexConcurrently(name) {
+    return `DROP INDEX CONCURRENTLY IF EXISTS ${q(name)};`;
+}
+/**
+ * Changes whose SQL postgres refuses inside a transaction, and inside a
+ * multi-statement query too. `writeMigration` gives them a migration of their own.
+ */
+function isConcurrent(change) {
+    return (change.kind === 'createIndex' && change.index.concurrently) || (change.kind === 'dropIndex' && change.concurrently);
 }
 function alterColumn(table, from, to) {
     const head = `ALTER TABLE ${q(table)} ALTER COLUMN ${q(to.name)}`;
@@ -111,18 +122,34 @@ export function renderChange(change) {
                     `ADD ${constraintClause(change.constraint)};`,
             ];
         case 'createIndex':
-            return [createIndex(change.table, change.index)];
+            // a failed CREATE INDEX CONCURRENTLY leaves an invalid index behind, and the
+            // migration stays unrecorded; the drop in front makes the rerun clean
+            return change.index.concurrently
+                ? [dropIndexConcurrently(change.index.name), createIndex(change.table, change.index)]
+                : [createIndex(change.table, change.index)];
         case 'dropIndex':
-            return [`DROP INDEX ${q(change.index)};`];
+            return [change.concurrently ? dropIndexConcurrently(change.index) : `DROP INDEX ${q(change.index)};`];
         default:
             return unreachable(change);
     }
 }
-/** Individual statements; `writeMigration` writes these to disk. */
+/** The statements of the ordinary migration, that is, everything but the `CONCURRENTLY` ones. */
 export function renderStatements(changes) {
-    return changes.flatMap(renderChange);
+    return changes.filter(change => !isConcurrent(change)).flatMap(renderChange);
 }
-/** Multi-line statements are separated by a blank line, single-line ones follow each other. */
+/**
+ * The statements of the `--> no-transaction` migration: `CONCURRENTLY` drops and
+ * creates. A replaced index yields its drop twice, as a change of its own and as
+ * the guard in front of the create, so duplicates are folded.
+ */
+export function renderConcurrentStatements(changes) {
+    const statements = changes.filter(isConcurrent).flatMap(renderChange);
+    return statements.filter((statement, i) => statements.indexOf(statement) === i);
+}
+/**
+ * The ordinary migration as one text: multi-line statements are separated by a
+ * blank line, single-line ones follow each other. `writeMigration` writes it as is.
+ */
 export function renderChanges(changes) {
     const statements = renderStatements(changes);
     let out = '';

package/dist/generator/snapshot.d.ts

@@ -25,6 +25,12 @@ export interface TableSnapshot {
         readonly unique: boolean;
         readonly columns: readonly string[];
         readonly where: string | null;
+        /**
+         * Built and dropped with `CONCURRENTLY`. How the index is built, not what it
+         * is: the diff ignores it when comparing indexes. Snapshots written before
+         * the field existed simply lack it, which reads as `false`.
+         */
+        readonly concurrently: boolean;
     }[];
     readonly foreignKeys: readonly {
         readonly name: string;

package/dist/generator/snapshot.js

@@ -29,6 +29,7 @@ function tableSnapshot(spec) {
             unique: i.unique,
             columns: [...i.columns],
             where: i.where !== undefined ? renderSql(i.where) : null,
+            concurrently: i.concurrently,
         })),
         foreignKeys: spec.foreignKeys.map(f => ({
             name: f.name,

package/dist/index.d.ts

@@ -1,27 +1,37 @@
 /**
- * kysely-ddl: PostgreSQL schema as code and SQL migration generation.
- * Has no runtime dependency on Kysely or on any driver.
+ * kysely-ddl: PostgreSQL schema as code, SQL migration generation and the
+ * Kysely side of it, row types and jsonb values. Imports `kysely`, the peer
+ * dependency, and no driver.
  *
  * Layers and dependency direction:
  *
- *   table ◄── generator ◄── migrator ◄── kysely
+ *   table ◄── generator ◄── migrator/store ◄── migrator (runner, provider)
+ *   table ◄── kysely (row types, jsonb values)
  *
  * Entry points:
  *
- *   kysely-ddl         — this file: tables, generation, migration files
- *   kysely-ddl/kysely  — row types, migration runner, provider for Migrator
+ *   kysely-ddl           — this file: tables, generation, migration files on disk,
+ *                          `inferKyselyTable` / `inferKyselyDatabase`, `jsonb` / `jsonbArray`
+ *   kysely-ddl/migrator  — running migrations: `createMigrator` / `migrateToLatest`
+ *                          and `sqlFileMigrationProvider`; separate, so that a project
+ *                          which applies migrations some other way does not pull it in
  *
  * Exports are sorted by module path: generator (snapshot, diff, render,
- * facade), migrator (files on disk), table (table definitions).
+ * facade), kysely (row types, jsonb values), migrator (files on disk), table
+ * (table definitions).
  */
 export { diffSnapshots } from './generator/diff.ts';
 export type { Change, Constraint } from './generator/diff.ts';
 export { generateMigration } from './generator/generate.ts';
 export type { GenerateResult } from './generator/generate.ts';
-export { renderChange, renderChanges, renderStatements } from './generator/render.ts';
+export { renderChange, renderChanges, renderConcurrentStatements, renderStatements } from './generator/render.ts';
 export { buildSnapshot, EMPTY_SNAPSHOT, SNAPSHOT_VERSION } from './generator/snapshot.ts';
 export type { ColumnSnapshot, Snapshot, TableSnapshot } from './generator/snapshot.ts';
-export { listMigrations, MIGRATION_EXTENSION, migrationTimestamp, readLatestSnapshot, readStatements, SNAPSHOT_FILE, STATEMENT_SEPARATOR, writeMigration, } from './migrator/store.ts';
+export type { inferKyselyDatabase, inferKyselyTable } from './kysely/infer.ts';
+export { jsonb, jsonbArray } from './kysely/json.ts';
+export type { Jsonb } from './kysely/json.ts';
+export { CONCURRENTLY_SUFFIX, listMigrations, MIGRATION_EXTENSION, migrationTimestamp, NO_TRANSACTION_MARKER, readLatestSnapshot, readMigration, readStatements, SNAPSHOT_FILE, STATEMENT_SEPARATOR, writeMigration, } from './migrator/store.ts';
+export type { MigrationFile } from './migrator/store.ts';
 export { toCamelCase, toSnakeCase } from './table/casing.ts';
 export type { CamelCase, SnakeCase } from './table/casing.ts';
 export { ColumnBuilder, columnBuilders } from './table/columns.ts';

package/dist/index.js

@@ -1,24 +1,31 @@
 /**
- * kysely-ddl: PostgreSQL schema as code and SQL migration generation.
- * Has no runtime dependency on Kysely or on any driver.
+ * kysely-ddl: PostgreSQL schema as code, SQL migration generation and the
+ * Kysely side of it, row types and jsonb values. Imports `kysely`, the peer
+ * dependency, and no driver.
  *
  * Layers and dependency direction:
  *
- *   table ◄── generator ◄── migrator ◄── kysely
+ *   table ◄── generator ◄── migrator/store ◄── migrator (runner, provider)
+ *   table ◄── kysely (row types, jsonb values)
  *
  * Entry points:
  *
- *   kysely-ddl         — this file: tables, generation, migration files
- *   kysely-ddl/kysely  — row types, migration runner, provider for Migrator
+ *   kysely-ddl           — this file: tables, generation, migration files on disk,
+ *                          `inferKyselyTable` / `inferKyselyDatabase`, `jsonb` / `jsonbArray`
+ *   kysely-ddl/migrator  — running migrations: `createMigrator` / `migrateToLatest`
+ *                          and `sqlFileMigrationProvider`; separate, so that a project
+ *                          which applies migrations some other way does not pull it in
  *
  * Exports are sorted by module path: generator (snapshot, diff, render,
- * facade), migrator (files on disk), table (table definitions).
+ * facade), kysely (row types, jsonb values), migrator (files on disk), table
+ * (table definitions).
  */
 export { diffSnapshots } from './generator/diff.js';
 export { generateMigration } from './generator/generate.js';
-export { renderChange, renderChanges, renderStatements } from './generator/render.js';
+export { renderChange, renderChanges, renderConcurrentStatements, renderStatements } from './generator/render.js';
 export { buildSnapshot, EMPTY_SNAPSHOT, SNAPSHOT_VERSION } from './generator/snapshot.js';
-export { listMigrations, MIGRATION_EXTENSION, migrationTimestamp, readLatestSnapshot, readStatements, SNAPSHOT_FILE, STATEMENT_SEPARATOR, writeMigration, } from './migrator/store.js';
+export { jsonb, jsonbArray } from './kysely/json.js';
+export { CONCURRENTLY_SUFFIX, listMigrations, MIGRATION_EXTENSION, migrationTimestamp, NO_TRANSACTION_MARKER, readLatestSnapshot, readMigration, readStatements, SNAPSHOT_FILE, STATEMENT_SEPARATOR, writeMigration, } from './migrator/store.js';
 export { toCamelCase, toSnakeCase } from './table/casing.js';
 export { ColumnBuilder, columnBuilders } from './table/columns.js';
 export { AUTO_NAMES, defineTable, ref } from './table/define.js';

package/dist/migrator/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Running `.sql` migrations. Entry point `kysely-ddl/migrator`, kept apart from
+ * the root one so that a project which applies its migrations some other way
+ * (psql, a CI job, a runner of its own) does not pull this in.
+ *
+ * Two ways to run: `createMigrator` / `migrateToLatest`, a runner on top of a
+ * ready `Kysely`, and `sqlFileMigrationProvider`, which feeds the same files to
+ * Kysely's own `Migrator`. Both read what `writeMigration` writes; the file
+ * format itself (`store.ts` next door) is exported from the root entry point,
+ * since generating a migration needs it and running one is optional.
+ */
+export { sqlFileMigrationProvider } from './provider.ts';
+export type { SqlMigrationProviderOptions } from './provider.ts';
+export { createMigrator, DEFAULT_JOURNAL_TABLE, migrateToLatest, MIGRATION_LOCK_ID, MigrationError, } from './runner.ts';
+export type { MigrationRunResult, MigrationStatus, MigratorOptions, SqlMigrator, TransactionMode } from './runner.ts';

package/dist/migrator/index.js

@@ -0,0 +1,13 @@
+/**
+ * Running `.sql` migrations. Entry point `kysely-ddl/migrator`, kept apart from
+ * the root one so that a project which applies its migrations some other way
+ * (psql, a CI job, a runner of its own) does not pull this in.
+ *
+ * Two ways to run: `createMigrator` / `migrateToLatest`, a runner on top of a
+ * ready `Kysely`, and `sqlFileMigrationProvider`, which feeds the same files to
+ * Kysely's own `Migrator`. Both read what `writeMigration` writes; the file
+ * format itself (`store.ts` next door) is exported from the root entry point,
+ * since generating a migration needs it and running one is optional.
+ */
+export { sqlFileMigrationProvider } from './provider.js';
+export { createMigrator, DEFAULT_JOURNAL_TABLE, migrateToLatest, MIGRATION_LOCK_ID, MigrationError, } from './runner.js';

package/dist/{kysely → migrator}/provider.js

@@ -21,13 +21,16 @@
  *
  * On transactions: on postgres Kysely runs the WHOLE run in one transaction by
  * default, DDL is transactional there, so a failing migration rolls back all the
- * previous ones from the same run. It is disabled with
- * `new Migrator({ ..., disableTransactions: true })`; that is needed for
- * operations postgres forbids inside a transaction (`CREATE INDEX CONCURRENTLY`
- * and the like).
+ * previous ones from the same run. A migration with `--> no-transaction` in its
+ * header gets `config: { transaction: false }`, which Kysely 0.30+ honors under
+ * `new Migrator({ ..., transactionMode: 'per-migration' })`: every migration in
+ * its own transaction, the marked one without. Older Kysely ignores `config`, so
+ * the marked migration checks that it is not inside a transaction and fails with
+ * a clear error instead of a postgres one; there the only way out is
+ * `disableTransactions: true` for the whole run.
  */
 import { sql } from 'kysely';
-import { listMigrations, readStatements } from '../migrator/store.js';
+import { listMigrations, NO_TRANSACTION_MARKER, readMigration } from './store.js';
 /**
  * A provider that hands `.sql` files from a folder to the `Migrator`.
  * The migration name is the file name without the extension, the order is
@@ -39,14 +42,22 @@ export function sqlFileMigrationProvider(dir, options = {}) {
         async getMigrations() {
             const migrations = {};
             for (const name of listMigrations(dir)) {
-                migrations[name] = {
+                const file = readMigration(dir, name);
+                const migration = {
                     async up(db) {
-                        // one statement at a time: the driver does not trip over
-                        // multi-statement text, and an error points at a specific query
-                        for (const statement of readStatements(dir, name)) {
+                        if (!file.transaction && db.isTransaction) {
+                            throw new Error(`${name} is marked "${NO_TRANSACTION_MARKER}" but the Migrator runs it inside a transaction. ` +
+                                "Kysely 0.30+: new Migrator({ ..., transactionMode: 'per-migration' }); older Kysely: " +
+                                "disableTransactions: true; or kysely-ddl's createMigrator({ ..., transaction: 'each' }).");
+                        }
+                        // chunk by chunk: a plain file is one chunk, a file with
+                        // `--> statement-breakpoint` several; CONCURRENTLY statements must travel alone
+                        for (const statement of file.statements) {
                             await sql.raw(statement).execute(db);
                         }
                     },
+                    // only when marked: in Kysely's other transaction modes an explicit value is an error
+                    ...(file.transaction ? {} : { config: { transaction: false } }),
                     ...(onDown === 'throw'
                         ? {
                             down() {
@@ -56,6 +67,7 @@ export function sqlFileMigrationProvider(dir, options = {}) {
                         }
                         : {}),
                 };
+                migrations[name] = migration;
             }
             return migrations;
         },

package/dist/{kysely → migrator}/runner.d.ts

@@ -34,10 +34,13 @@ export interface MigratorOptions {
     /** The journal table. `kysely_migration` by default, like Kysely. */
     readonly journalTable?: string;
     /**
-     * `all` (default): the whole run in one transaction, like Kysely, so a failing
-     * migration rolls back the previous ones from the same run. `each`: a
-     * transaction per migration. `none`: no transactions, needed for
-     * `CREATE INDEX CONCURRENTLY`.
+     * `each` (default): a transaction per migration; a migration with
+     * `--> no-transaction` in its header, which is how the generator writes
+     * `CREATE INDEX CONCURRENTLY`, runs without one. `all`: the whole run in one
+     * transaction, like Kysely, so a failing migration rolls back the previous ones
+     * from the same run; the marker is an error here, one shared transaction cannot
+     * leave a migration out. `none`: no `BEGIN` at all; a plain file still runs as
+     * one implicit transaction, since postgres treats a multi-statement query that way.
      */
     readonly transaction?: TransactionMode;
     /**
@@ -60,14 +63,23 @@ export interface SqlMigrator {
     /** Applies everything pending. A failing statement throws `MigrationError`. */
     toLatest(): Promise<MigrationRunResult>;
 }
-/** A failing statement: which migration, which query and what was applied before it. */
+/** A failing query: which migration, which text and what was applied before it. */
 export declare class MigrationError extends Error {
     readonly migration: string;
+    /** The text sent as one query: a whole file, or one chunk between `--> statement-breakpoint` markers. */
     readonly statement: string;
     /** Migrations applied by this run before the error. With `transaction: 'all'` they are rolled back. */
     readonly applied: readonly string[];
     readonly name = "MigrationError";
-    constructor(migration: string, statement: string, 
+    /**
+     * The line inside `statement` postgres pointed at, when it did. A generated
+     * migration is one query with several statements, so this is what locates
+     * the failing one.
+     */
+    readonly line: number | undefined;
+    constructor(migration: string, 
+    /** The text sent as one query: a whole file, or one chunk between `--> statement-breakpoint` markers. */
+    statement: string, 
     /** Migrations applied by this run before the error. With `transaction: 'all'` they are rolled back. */
     applied: readonly string[], cause: unknown);
 }

package/dist/{kysely → migrator}/runner.js

@@ -18,31 +18,49 @@
  * happy with `Migrator` takes `sqlFileMigrationProvider`.
  */
 import { sql } from 'kysely';
-import { listMigrations, readStatements } from '../migrator/store.js';
+import { listMigrations, NO_TRANSACTION_MARKER, readMigration } from './store.js';
 /** Same as Kysely, so both runners see one state. */
 export const DEFAULT_JOURNAL_TABLE = 'kysely_migration';
 /** The `pg_advisory_lock` key, the same as Kysely's `PostgresAdapter` uses. */
 export const MIGRATION_LOCK_ID = 3853314791062309107n;
 /** How long to wait for another run. An hour, like Kysely. */
 const LOCK_TIMEOUT_MS = 60 * 60 * 1000;
-/** A failing statement: which migration, which query and what was applied before it. */
+/** A failing query: which migration, which text and what was applied before it. */
 export class MigrationError extends Error {
     migration;
     statement;
     applied;
     name = 'MigrationError';
-    constructor(migration, statement, 
+    /**
+     * The line inside `statement` postgres pointed at, when it did. A generated
+     * migration is one query with several statements, so this is what locates
+     * the failing one.
+     */
+    line;
+    constructor(migration, 
+    /** The text sent as one query: a whole file, or one chunk between `--> statement-breakpoint` markers. */
+    statement, 
     /** Migrations applied by this run before the error. With `transaction: 'all'` they are rolled back. */
     applied, cause) {
-        super(`${migration}: statement failed\n${statement}\n${describe(cause)}`, { cause });
+        const line = lineOf(statement, cause);
+        super(`${migration}: statement failed${line === undefined ? '' : ` at line ${line}`}\n${statement}\n${describe(cause)}`, { cause });
         this.migration = migration;
         this.statement = statement;
         this.applied = applied;
+        this.line = line;
     }
 }
 function describe(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
+/** Postgres reports the error position as a 1-based character offset into the query; both drivers pass it on. */
+function lineOf(statement, cause) {
+    const position = Number(cause?.position);
+    if (!Number.isInteger(position) || position < 1) {
+        return undefined;
+    }
+    return statement.slice(0, position - 1).split('\n').length;
+}
 export function createMigrator(options) {
     const { db, migrationsDir: dir } = options;
     if (db.isTransaction) {
@@ -53,7 +71,7 @@ export function createMigrator(options) {
         throw new Error(`journalTable: "${journal}" may only contain letters, digits and underscores`);
     }
     const table = sql.table(journal);
-    const mode = options.transaction ?? 'all';
+    const mode = options.transaction ?? 'each';
     const allowUnordered = options.allowUnordered ?? false;
     return {
         status: () => db.connection().execute(async (connection) => {
@@ -122,8 +140,17 @@ async function apply(connection, table, dir, pending, mode) {
     if (pending.length === 0) {
         return { applied };
     }
-    const runOne = async (name) => {
-        for (const statement of readStatements(dir, name)) {
+    // parse everything first: a malformed file, or a marker the mode cannot honor,
+    // must fail before the first statement reaches the database
+    const migrations = pending.map(name => ({ name, ...readMigration(dir, name) }));
+    const marked = migrations.find(migration => !migration.transaction);
+    // under 'none' the marker asks for what already happens; under 'all' it cannot be honored
+    if (marked !== undefined && mode === 'all') {
+        throw new Error(`${dir}: ${marked.name} is marked "${NO_TRANSACTION_MARKER}", but transaction: 'all' runs the whole run ` +
+            "in one transaction and cannot leave a migration out. Use transaction: 'each'.");
+    }
+    const runOne = async ({ name, statements }) => {
+        for (const statement of statements) {
             try {
                 await run(connection, statement);
             }
@@ -149,19 +176,25 @@ async function apply(connection, table, dir, pending, mode) {
     switch (mode) {
         case 'all':
             await inTransaction(async () => {
-                for (const name of pending) {
-                    await runOne(name);
+                for (const migration of migrations) {
+                    await runOne(migration);
                 }
             });
             break;
         case 'each':
-            for (const name of pending) {
-                await inTransaction(() => runOne(name));
+            for (const migration of migrations) {
+                // a marked migration runs in autocommit, its journal row too, like Kysely's 'per-migration' mode
+                if (migration.transaction) {
+                    await inTransaction(() => runOne(migration));
+                }
+                else {
+                    await runOne(migration);
+                }
             }
             break;
         case 'none':
-            for (const name of pending) {
-                await runOne(name);
+            for (const migration of migrations) {
+                await runOne(migration);
             }
             break;
     }

package/dist/migrator/store.d.ts

@@ -7,11 +7,43 @@ export declare const SNAPSHOT_FILE = "snapshot.json";
  * stays valid when fed to psql as a whole.
  */
 export declare const STATEMENT_SEPARATOR = "--> statement-breakpoint";
+/**
+ * A header marker: the migration runs outside a transaction, which postgres
+ * demands for `CREATE INDEX CONCURRENTLY` and the like. Recognized only in the
+ * header, that is, among the blank lines and comments before the first statement.
+ *
+ * The runner honors it under `transaction: 'each'`. For Kysely's `Migrator` the
+ * provider turns it into `config: { transaction: false }`, which Kysely 0.30+
+ * honors under `transactionMode: 'per-migration'`.
+ */
+export declare const NO_TRANSACTION_MARKER = "--> no-transaction";
 export declare function migrationTimestamp(now?: Date): string;
 /** Migration names (without `.sql`), sorted the way Kysely sorts them: by character codes. */
 export declare function listMigrations(dir: string): string[];
 /** The schema state after the latest migration; the next diff is computed from it. */
 export declare function readLatestSnapshot(dir: string): Snapshot;
+/** A parsed migration file. */
+export interface MigrationFile {
+    /** The statements, split on `STATEMENT_SEPARATOR`, with the header markers taken out. */
+    readonly statements: readonly string[];
+    /** `false` when the header carries `NO_TRANSACTION_MARKER`. */
+    readonly transaction: boolean;
+}
+/** The statements of a migration and what its header markers said. */
+export declare function readMigration(dir: string, name: string): MigrationFile;
+/** The statements only; `readMigration` also tells whether the migration wants a transaction. */
 export declare function readStatements(dir: string, name: string): string[];
-/** Writes the migration file, updates the snapshot and returns the migration name. */
-export declare function writeMigration(dir: string, name: string, result: GenerateResult): string;
+/** The suffix of the migration that holds the `CONCURRENTLY` statements. */
+export declare const CONCURRENTLY_SUFFIX = "_concurrently";
+/**
+ * Writes the migration files, updates the snapshot and returns the names in
+ * application order.
+ *
+ * The ordinary statements go into `<stamp>_<name>.sql` as plain SQL: postgres
+ * runs such a file as one query. The `CONCURRENTLY` statements, which postgres
+ * refuses inside a transaction and inside a multi-statement query alike, go into
+ * `<stamp+1>_<name>_concurrently.sql`, marked `--> no-transaction` and split by
+ * `--> statement-breakpoint` so that the runner sends them one at a time.
+ * Either file is skipped when it would be empty.
+ */
+export declare function writeMigration(dir: string, name: string, result: GenerateResult): string[];

package/dist/migrator/store.js

@@ -17,17 +17,34 @@
  * which is all that is needed to compute the next diff. The price is merge
  * conflicts: two branches that each add a migration diverge in one file, and
  * the snapshot has to be regenerated after the merge.
+ *
+ * Inside a file, `-->` comments are markers for the runner; postgres sees plain
+ * comments. `--> statement-breakpoint` separates statements, and
+ * `--> no-transaction` in the header says the migration runs outside a transaction.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { EMPTY_SNAPSHOT } from '../generator/snapshot.js';
 export const MIGRATION_EXTENSION = '.sql';
 export const SNAPSHOT_FILE = 'snapshot.json';
+/** Machine-readable comments start with this. */
+const MARKER = '-->';
+const NO_TRANSACTION = 'no-transaction';
 /**
  * Separator between statements inside a file. It is an SQL comment, so the file
  * stays valid when fed to psql as a whole.
  */
 export const STATEMENT_SEPARATOR = '--> statement-breakpoint';
+/**
+ * A header marker: the migration runs outside a transaction, which postgres
+ * demands for `CREATE INDEX CONCURRENTLY` and the like. Recognized only in the
+ * header, that is, among the blank lines and comments before the first statement.
+ *
+ * The runner honors it under `transaction: 'each'`. For Kysely's `Migrator` the
+ * provider turns it into `config: { transaction: false }`, which Kysely 0.30+
+ * honors under `transactionMode: 'per-migration'`.
+ */
+export const NO_TRANSACTION_MARKER = `${MARKER} ${NO_TRANSACTION}`;
 /** Parses the file name prefix back into a date. */
 function parseTimestamp(value) {
     return new Date(Date.UTC(Number(value.slice(0, 4)), Number(value.slice(4, 6)) - 1, Number(value.slice(6, 8)), Number(value.slice(8, 10)), Number(value.slice(10, 12)), Number(value.slice(12, 14))));
@@ -61,36 +78,104 @@ export function readLatestSnapshot(dir) {
     }
     return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
-export function readStatements(dir, name) {
-    const text = fs.readFileSync(path.join(dir, `${name}${MIGRATION_EXTENSION}`), 'utf8');
-    return text
+/** The word after `-->` on a marker line, undefined for any other line. */
+function markerOf(line) {
+    return line.startsWith(MARKER) ? line.slice(MARKER.length).trim() : undefined;
+}
+/**
+ * The header is everything before the first statement: blank lines, plain `--`
+ * comments and markers. Markers are taken out, the rest goes to postgres as is.
+ * A marker below the header would reach postgres as a comment and change
+ * nothing, so it is an error rather than a silent no-op.
+ */
+function parseMigration(text, name) {
+    const kept = [];
+    let transaction = true;
+    let inHeader = true;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        const marker = markerOf(line);
+        if (inHeader && marker !== undefined && line !== STATEMENT_SEPARATOR) {
+            if (marker !== NO_TRANSACTION) {
+                throw new Error(`${name}: unknown marker "${line}" in the header. The only header marker is "${NO_TRANSACTION_MARKER}".`);
+            }
+            transaction = false;
+            continue;
+        }
+        // the first statement, or a separator, ends the header
+        if (inHeader && line !== '' && (marker !== undefined || !line.startsWith('--'))) {
+            inHeader = false;
+        }
+        if (!inHeader && marker === NO_TRANSACTION) {
+            throw new Error(`${name}: "${NO_TRANSACTION_MARKER}" must be in the header, before the first statement.`);
+        }
+        kept.push(raw);
+    }
+    const statements = kept
+        .join('\n')
         .split(STATEMENT_SEPARATOR)
         .map(statement => statement.trim())
         .filter(statement => statement !== '');
+    return { statements, transaction };
+}
+/** The statements of a migration and what its header markers said. */
+export function readMigration(dir, name) {
+    return parseMigration(fs.readFileSync(path.join(dir, `${name}${MIGRATION_EXTENSION}`), 'utf8'), name);
+}
+/** The statements only; `readMigration` also tells whether the migration wants a transaction. */
+export function readStatements(dir, name) {
+    return [...readMigration(dir, name).statements];
 }
-/** Writes the migration file, updates the snapshot and returns the migration name. */
+/**
+ * Names must grow monotonically: Kysely applies migrations in alphabetical
+ * order. Two migrations created within the same second would get the same
+ * prefix, and the suffix would decide the order, that is, by luck.
+ */
+function nextTimestamp(dir) {
+    const previous = listMigrations(dir).at(-1);
+    const stamp = migrationTimestamp();
+    if (previous !== undefined && stamp <= previous.slice(0, 14)) {
+        return migrationTimestamp(new Date(parseTimestamp(previous.slice(0, 14)).getTime() + 1000));
+    }
+    return stamp;
+}
+/** The suffix of the migration that holds the `CONCURRENTLY` statements. */
+export const CONCURRENTLY_SUFFIX = '_concurrently';
+/**
+ * Writes the migration files, updates the snapshot and returns the names in
+ * application order.
+ *
+ * The ordinary statements go into `<stamp>_<name>.sql` as plain SQL: postgres
+ * runs such a file as one query. The `CONCURRENTLY` statements, which postgres
+ * refuses inside a transaction and inside a multi-statement query alike, go into
+ * `<stamp+1>_<name>_concurrently.sql`, marked `--> no-transaction` and split by
+ * `--> statement-breakpoint` so that the runner sends them one at a time.
+ * Either file is skipped when it would be empty.
+ */
 export function writeMigration(dir, name, result) {
-    if (result.statements.length === 0) {
+    if (result.statements.length === 0 && result.concurrently.length === 0) {
         throw new Error('nothing to write: no changes');
     }
     if (!/^[a-z0-9_]+$/.test(name)) {
         throw new Error(`migration name "${name}": only [a-z0-9_] is allowed`);
     }
-    // Names must grow monotonically: Kysely applies migrations in alphabetical
-    // order. Two migrations created within the same second would get the same
-    // prefix, and the suffix would decide the order, that is, by luck.
-    const previous = listMigrations(dir).at(-1);
-    let stamp = migrationTimestamp();
-    if (previous !== undefined && stamp <= previous.slice(0, 14)) {
-        stamp = migrationTimestamp(new Date(parseTimestamp(previous.slice(0, 14)).getTime() + 1000));
+    fs.mkdirSync(dir, { recursive: true });
+    const written = [];
+    const write = (suffix, text) => {
+        const migration = `${nextTimestamp(dir)}_${name}${suffix}`;
+        const file = path.join(dir, `${migration}${MIGRATION_EXTENSION}`);
+        if (fs.existsSync(file)) {
+            throw new Error(`migration ${migration} already exists`);
+        }
+        fs.writeFileSync(file, text);
+        written.push(migration);
+    };
+    if (result.statements.length > 0) {
+        write('', result.sql);
     }
-    const migration = `${stamp}_${name}`;
-    const file = path.join(dir, `${migration}${MIGRATION_EXTENSION}`);
-    if (fs.existsSync(file)) {
-        throw new Error(`migration ${migration} already exists`);
+    if (result.concurrently.length > 0) {
+        write(CONCURRENTLY_SUFFIX, `${NO_TRANSACTION_MARKER}\n${result.concurrently.join(`\n${STATEMENT_SEPARATOR}\n`)}\n`);
     }
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(file, `${result.statements.join(`\n${STATEMENT_SEPARATOR}\n`)}\n`);
     fs.writeFileSync(path.join(dir, SNAPSHOT_FILE), `${JSON.stringify(result.snapshot, null, 2)}\n`);
-    return migration;
+    return written;
 }

package/dist/table/columns.d.ts

@@ -168,7 +168,7 @@ declare function timestamp<N extends string>(name: N, config?: TimestampConfig):
 declare function timestamp(config?: TimestampConfig): Fresh<undefined, Date>;
 /**
  * `unknown` in TS, narrow it with `$type<T>()`. Values for writes go only
- * through `jsonb()` from `kysely-ddl/kysely`: drivers accept a raw jsonb
+ * through `jsonb()` from `kysely-ddl`: drivers accept a raw jsonb
  * parameter differently, and the helper evens that out.
  */
 declare function jsonb<N extends string>(name: N): Fresh<N, unknown, undefined, true>;

package/dist/table/define.d.ts

@@ -69,6 +69,8 @@ export interface TableSpec {
         readonly unique: boolean;
         readonly columns: readonly string[];
         readonly where: Sql | undefined;
+        /** Built and dropped with `CONCURRENTLY`, in a migration of its own. */
+        readonly concurrently: boolean;
     }[];
     readonly foreignKeys: readonly {
         readonly name: string;
@@ -121,7 +123,7 @@ export interface ForeignKeyDef<TCols> {
 export declare function ref<T extends AnyTable>(table: T, columns: readonly (keyof T['_']['columns'] & string)[]): Reference;
 export interface TableOptions<TName extends string, TCols extends Record<string, AnyColumn>> {
     /** The table name in the database. Inferred as a literal; the Kysely interface keys come from it. */
-    readonly tableName: TName;
+    readonly name: TName;
     /**
      * Columns are declared with a callback that receives the builder set:
      *
@@ -153,6 +155,14 @@ export interface TableOptions<TName extends string, TCols extends Record<string,
         readonly unique?: boolean;
         readonly columns: readonly (keyof TCols & string)[];
         readonly where?: (c: Refs<TCols>) => Sql;
+        /**
+         * Build and drop the index with `CONCURRENTLY`, without locking the table
+         * against writes. Postgres refuses that inside a transaction, so the
+         * generator puts such statements into a separate migration marked
+         * `--> no-transaction`, which the runner applies under `transaction: 'each'`.
+         * Toggling the flag on an existing index changes nothing in the database.
+         */
+        readonly concurrently?: boolean;
     }[];
     readonly foreignKeys?: readonly ForeignKeyDef<TCols>[];
     readonly checks?: readonly {

package/dist/table/define.js

@@ -46,7 +46,7 @@ export function ref(table, columns) {
 }
 // ── defineTable ──────────────────────────────────────────────────────────────
 export function defineTable(options) {
-    const name = options.tableName;
+    const name = options.name;
     assertIdentifier(name, 'table');
     const columns = [];
     const dbName = {};
@@ -93,6 +93,7 @@ export function defineTable(options) {
             unique: index.unique ?? false,
             columns: indexColumns,
             where: index.where !== undefined ? index.where(typedRefs) : undefined,
+            concurrently: index.concurrently ?? false,
         };
     });
     // ── primary key ────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely-ddl",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "PostgreSQL schema as TypeScript code: SQL migrations from snapshot diffs, Kysely table types and a migration runner",
   "keywords": [
     "postgres",
@@ -41,9 +41,9 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./kysely": {
-      "types": "./dist/kysely/index.d.ts",
-      "default": "./dist/kysely/index.js"
+    "./migrator": {
+      "types": "./dist/migrator/index.d.ts",
+      "default": "./dist/migrator/index.js"
     },
     "./package.json": "./package.json"
   },

package/dist/kysely/index.d.ts

@@ -1,12 +0,0 @@
-/**
- * Everything tied to Kysely: row types, jsonb values, the migration runner on
- * top of a ready `Kysely`, and the `.sql` file provider for the built-in `Migrator`.
- * Entry point `kysely-ddl/kysely`.
- */
-export type { inferKyselyDatabase, inferKyselyTable } from './infer.ts';
-export { jsonb, jsonbArray } from './json.ts';
-export type { Jsonb } from './json.ts';
-export { sqlFileMigrationProvider } from './provider.ts';
-export type { SqlMigrationProviderOptions } from './provider.ts';
-export { createMigrator, DEFAULT_JOURNAL_TABLE, migrateToLatest, MIGRATION_LOCK_ID, MigrationError, } from './runner.ts';
-export type { MigrationRunResult, MigrationStatus, MigratorOptions, SqlMigrator, TransactionMode } from './runner.ts';

package/dist/kysely/index.js

@@ -1,3 +0,0 @@
-export { jsonb, jsonbArray } from './json.js';
-export { sqlFileMigrationProvider } from './provider.js';
-export { createMigrator, DEFAULT_JOURNAL_TABLE, migrateToLatest, MIGRATION_LOCK_ID, MigrationError, } from './runner.js';