kysely-ddl 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow [SemVer](https://semver.org/).
 
+## [Unreleased]
+
+## [0.3.0] — 2026-09-12
+
+### Added
+
+- `{ bigint: true }` in the infer options: `bigint()` columns as `bigint` and
+  `bigint().array()` columns as `bigint[]`, for a driver that returns int8 that
+  way (`Bun.SQL` with `{ bigint: true }`, `pg` with a type parser for oid 20 and,
+  for arrays, 1016). A column with `$type<T>()` keeps `T`. The `InferOptions`
+  type is exported.
+
+### Changed
+
+- **Breaking:** the second type parameter of `inferKyselyTable` and
+  `inferKyselyDatabase` is an options object instead of a boolean:
+  `inferKyselyDatabase<typeof schema, true>` becomes
+  `inferKyselyDatabase<typeof schema, { camelCase: true }>`.
+
+## [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
@@ -131,8 +134,9 @@ config second: `t.varchar('title', { length: 200 })`.
 
 TypeScript value types match what the driver returns, without modes like
 `bigint({ mode })`: `bigint` and `numeric` are strings (no precision loss),
-`timestamp` is `Date`, `jsonb` is `unknown`. For another type use `$type<T>()`
-and convert on your side.
+`timestamp` is `Date`, `jsonb` is `unknown`. A driver told to return int8 as
+`bigint` is matched by the `bigint: true` infer option, see "Types for Kysely".
+For another type use `$type<T>()` and convert on your side.
 
 ### `enum([...])`
 
@@ -183,17 +187,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>;
@@ -204,9 +207,10 @@ type NewUser = Insertable<UserTable>;
 ```
 
 Keys are **the column names in the database**: they are known at the type level
-because `defineTable` keeps them as literals. With Kysely's `CamelCasePlugin`
-pass `true` as the second parameter and the column and table keys become
-camelCase, see below. Write rules:
+because `defineTable` keeps them as literals. The second parameter of both types
+is an options object, `InferOptions`: `{ camelCase: true }` for Kysely's
+`CamelCasePlugin`, `{ bigint: true }` for a driver that returns int8 as `bigint`;
+both are described below, and they combine. Write rules:
 
 | column | `Insertable` |
 |---|---|
@@ -219,13 +223,13 @@ camelCase, see below. Write rules:
 ### CamelCasePlugin
 
 `CamelCasePlugin` rewrites camelCase in code to snake_case in SQL and back in
-result row keys. To have the types reflect that, both `infer` types take `true`
-as the second parameter:
+result row keys. To have the types reflect that, pass `{ camelCase: true }` to
+either `infer` type:
 
 ```ts
 import { CamelCasePlugin, Kysely } from 'kysely';
 
-type DB = inferKyselyDatabase<typeof schema, true>;
+type DB = inferKyselyDatabase<typeof schema, { camelCase: true }>;
 const db = new Kysely<DB>({ dialect, plugins: [new CamelCasePlugin()] });
 
 await db.selectFrom('auditLog').select(['userId', 'happenedAt']).execute();
@@ -244,6 +248,35 @@ leading underscore. Plugin options (`upperCase`, `underscoreBeforeDigits`,
 conversions themselves are exported too: the types `SnakeCase`, `CamelCase` and
 the functions `toSnakeCase`, `toCamelCase`.
 
+### bigint: when the driver returns `bigint`
+
+`bigint()` columns are strings in the types because that is what `pg` and
+`Bun.SQL` return for int8 by default. Both can return `bigint` instead, and then
+the types follow with `{ bigint: true }`: `bigint()` columns read and write as
+`bigint`, `bigint().array()` columns as `bigint[]`, nullable ones as
+`bigint | null`. A column with `$type<T>()` stays `T`, and `numeric` stays a
+string either way.
+
+```ts
+// Bun.SQL: its own option
+const sql = new SQL(process.env.DATABASE_URL, { bigint: true });
+
+// pg: a parser for int8 (oid 20); int8[] (oid 1016) is parsed separately and has no entry in pg.types.builtins
+pg.types.setTypeParser(pg.types.builtins.INT8, BigInt);
+const INT8_ARRAY = 1016 as Parameters<typeof pg.types.getTypeParser>[0];
+const parseInt8Array = pg.types.getTypeParser(INT8_ARRAY) as (value: string) => (string | null)[];
+pg.types.setTypeParser(INT8_ARRAY, value => parseInt8Array(value).map(item => (item === null ? null : BigInt(item))));
+
+type DB = inferKyselyDatabase<typeof schema, { bigint: true }>;
+// together with CamelCasePlugin: { camelCase: true, bigint: true }
+
+const row = await db.selectFrom('ledger').select(['amount', 'history']).executeTakeFirstOrThrow();
+//    ^? { amount: bigint; history: bigint[] }
+```
+
+Values past 2^53 stay exact on both drivers, in parameters as well as in
+results, which is the point of `bigint` over `number`.
+
 ### jsonb: values through `jsonb()` and `jsonbArray()`
 
 Drivers disagree on how a jsonb parameter should be passed, and there is no raw
@@ -255,7 +288,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 +327,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 +414,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 +432,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 +454,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
@@ -411,27 +496,18 @@ What the checks showed on `pg` 8.23 and `Bun.SQL` 1.4 (parameters via Kysely):
 | array of objects -> `jsonb[]` | ok | error: arrays are not encoded | `jsonbArray([...])` |
 | array of strings -> `varchar[]` | ok, including commas, quotes, `null` | error: elements joined with commas | a Bun dialect must encode arrays into literals itself, as the test one does |
 | `numeric` = 0 on read | `'0.00'` | `'0'` | compare as numbers |
+| `int8` on read | `'42'`; `42n` with a parser for oid 20, and 1016 for `int8[]` | `'42'`; `42n` with `{ bigint: true }` | the `bigint: true` infer option once the driver returns `bigint` |
 
 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, InferOptions } 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';