kysely-ddl 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ver
 
 ## [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

package/README.md

@@ -134,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([...])`
 
@@ -206,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` |
 |---|---|
@@ -221,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();
@@ -246,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
@@ -465,6 +496,7 @@ 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.

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export type { GenerateResult } from './generator/generate.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 type { inferKyselyDatabase, inferKyselyTable } from './kysely/infer.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';

package/dist/kysely/infer.d.ts

@@ -12,13 +12,17 @@
  * because `defineTable` keeps them as literals, so the bridge does not depend on
  * casing plugins or on conventions shared between two libraries.
  *
- * When Kysely runs with `CamelCasePlugin`, pass `true` as the second parameter:
- * the column and table keys then become camelCase versions of the database names,
- * exactly as the plugin rewrites them with default options:
+ * The second parameter is an options object, `InferOptions`, and the options combine:
  *
  * ```ts
- * type DB = inferKyselyDatabase<typeof schema, true>;
+ * // Kysely runs with CamelCasePlugin: column and table keys become camelCase,
+ * // exactly as the plugin rewrites them with default options
+ * type DB = inferKyselyDatabase<typeof schema, { camelCase: true }>;
  * const db = new Kysely<DB>({ dialect, plugins: [new CamelCasePlugin()] });
+ *
+ * // the driver returns int8 as BigInt (Bun.SQL with `{ bigint: true }`, pg with a
+ * // type parser): bigint() columns become bigint, bigint().array() ones bigint[]
+ * type DB = inferKyselyDatabase<typeof schema, { bigint: true }>;
  * ```
  *
  * `kysely` is imported as a type only; there is no runtime dependency.
@@ -27,18 +31,42 @@ import type { CamelCase } from '../table/casing.ts';
 import type { ResolvedColumnCfg, Table } from '../table/define.ts';
 import type { Jsonb } from './json.ts';
 import type { ColumnType } from 'kysely';
+/** The second parameter of `inferKyselyTable` and `inferKyselyDatabase`. Everything is off by default. */
+export interface InferOptions {
+    /**
+     * Column and table keys as `CamelCasePlugin` rewrites them: `created_at` ->
+     * `createdAt`, `audit_log` -> `auditLog`. Otherwise the names in the database.
+     */
+    readonly camelCase?: boolean;
+    /**
+     * `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 1016 for arrays). Otherwise strings,
+     * which is what both drivers return by default. A column with `$type<T>()`
+     * stays `T` either way.
+     */
+    readonly bigint?: boolean;
+}
+type Camel<O extends InferOptions> = O extends {
+    readonly camelCase: true;
+} ? true : false;
+type Big<O extends InferOptions> = O extends {
+    readonly bigint: true;
+} ? true : false;
 type Cols<T extends Table> = T['_']['columns'];
 /** The key in the Kysely interface: the database name or, under `CamelCasePlugin`, its camelCase. */
-type Key<Name extends string, Camel extends boolean> = Camel extends true ? CamelCase<Name> : Name;
+type Key<Name extends string, O extends InferOptions> = Camel<O> extends true ? CamelCase<Name> : Name;
+/** The JS value of a column: `data` from the builder, or `bigint` for an int8 the driver returns that way. */
+type Data<C extends ResolvedColumnCfg, O extends InferOptions> = C['bigint'] extends true ? Big<O> extends true ? C['array'] extends true ? bigint[] : bigint : C['data'] : C['data'];
 /** What comes back from SELECT. */
-type Select<C extends ResolvedColumnCfg> = C['notNull'] extends true ? C['data'] : C['data'] | null;
+type Select<C extends ResolvedColumnCfg, O extends InferOptions> = C['notNull'] extends true ? Data<C, O> : Data<C, O> | null;
 type ElementOf<T> = T extends readonly (infer E)[] ? E : never;
 /**
  * What goes into INSERT / UPDATE before nullability and defaults are applied. For
  * jsonb this is branded JSON text: only `jsonb()` produces it (`jsonbArray()` for
  * `jsonb[]`), a raw object or string does not compile.
  */
-type Written<C extends ResolvedColumnCfg> = C['json'] extends true ? C['array'] extends true ? Jsonb<ElementOf<C['data']>>[] : Jsonb<C['data']> : C['data'];
+type Written<C extends ResolvedColumnCfg, O extends InferOptions> = C['json'] extends true ? C['array'] extends true ? Jsonb<ElementOf<C['data']>>[] : Jsonb<C['data']> : Data<C, O>;
 /**
  * What can be passed for a write:
  *   identity always          -> not at all;
@@ -46,16 +74,16 @@ type Written<C extends ResolvedColumnCfg> = C['json'] extends true ? C['array']
  *   has a default            -> optional;
  *   nullable                 -> optional and accepts null.
  */
-type Insert<C extends ResolvedColumnCfg> = C['identity'] extends 'always' ? never : C['notNull'] extends true ? C['hasDefault'] extends true ? Written<C> | undefined : Written<C> : Written<C> | null | undefined;
-export type inferKyselyTable<T extends Table, Camel extends boolean = false> = {
-    [K in keyof Cols<T> as Key<Cols<T>[K]['name'], Camel>]: ColumnType<Select<Cols<T>[K]>, Insert<Cols<T>[K]>, Insert<Cols<T>[K]>>;
+type Insert<C extends ResolvedColumnCfg, O extends InferOptions> = C['identity'] extends 'always' ? never : C['notNull'] extends true ? C['hasDefault'] extends true ? Written<C, O> | undefined : Written<C, O> : Written<C, O> | null | undefined;
+export type inferKyselyTable<T extends Table, O extends InferOptions = InferOptions> = {
+    [K in keyof Cols<T> as Key<Cols<T>[K]['name'], O>]: ColumnType<Select<Cols<T>[K], O>, Insert<Cols<T>[K], O>, Insert<Cols<T>[K], O>>;
 };
 /**
  * The interface of the whole database from a schema module: the key is the table
  * name, the value is `inferKyselyTable`. Anything that is not a table (constants,
  * types, zod schemas) is filtered out.
  */
-export type inferKyselyDatabase<TSchema, Camel extends boolean = false> = {
-    [K in keyof TSchema as TSchema[K] extends Table ? Key<TSchema[K]['_']['name'], Camel> : never]: TSchema[K] extends Table ? inferKyselyTable<TSchema[K], Camel> : never;
+export type inferKyselyDatabase<TSchema, O extends InferOptions = InferOptions> = {
+    [K in keyof TSchema as TSchema[K] extends Table ? Key<TSchema[K]['_']['name'], O> : never]: TSchema[K] extends Table ? inferKyselyTable<TSchema[K], O> : never;
 };
 export {};

package/dist/table/columns.d.ts

@@ -16,6 +16,9 @@
  *   int8    -> string   (no precision loss beyond 2^53)
  *   numeric -> string   (no float error)
  *
+ * The one option there is follows the driver instead of replacing it: `pg` and
+ * `Bun.SQL` can both be told to return int8 as `bigint`, and `{ bigint: true }` in
+ * the infer options (see the kysely layer) types `bigint()` columns to match.
  * For another type use `$type<T>()` plus an explicit conversion on your side.
  */
 import type { Sql } from './sql.ts';
@@ -32,6 +35,12 @@ export interface ColumnCfg {
     readonly enumValues: readonly string[] | undefined;
     /** A jsonb column: values for writes go through `jsonb()`, see the kysely layer. */
     readonly json: boolean;
+    /**
+     * An int8 column still typed as the driver's default, a string. `{ bigint: true }`
+     * in the infer options reads such a column as `bigint`; `$type<T>()` clears the
+     * flag, since an explicit type is final.
+     */
+    readonly bigint: boolean;
 }
 /**
  * A targeted config update: what U has overrides T, the rest is carried over.
@@ -63,6 +72,9 @@ type Update<T extends ColumnCfg, U extends Partial<ColumnCfg>> = {
     readonly json: U extends {
         json: infer V extends boolean;
     } ? V : T['json'];
+    readonly bigint: U extends {
+        bigint: infer V extends boolean;
+    } ? V : T['bigint'];
 };
 /** A default: a literal or an SQL expression. */
 export type DefaultValue = Sql | string | number | boolean | null;
@@ -102,14 +114,19 @@ export declare class ColumnBuilder<T extends ColumnCfg = ColumnCfg> {
         data: T['data'][];
         array: true;
     }>>;
-    /** Narrows the value type without touching the column type in the database. */
+    /**
+     * Narrows the value type without touching the column type in the database. The
+     * type is final: on a `bigint()` column it also switches the `bigint: true` infer
+     * option off.
+     */
     $type<U>(): ColumnBuilder<Update<T, {
         data: U;
+        bigint: false;
     }>>;
 }
 export type AnyColumn = ColumnBuilder<ColumnCfg>;
 /** A fresh column: the name is either explicit or taken from the object key. */
-type Fresh<N extends string | undefined, TData, TEnum extends readonly string[] | undefined = undefined, TJson extends boolean = false> = ColumnBuilder<{
+type Fresh<N extends string | undefined, TData, TEnum extends readonly string[] | undefined = undefined, TJson extends boolean = false, TBigint extends boolean = false> = ColumnBuilder<{
     name: N;
     data: TData;
     notNull: false;
@@ -118,6 +135,7 @@ type Fresh<N extends string | undefined, TData, TEnum extends readonly string[]
     identity: undefined;
     enumValues: TEnum;
     json: TJson;
+    bigint: TBigint;
 }>;
 declare function uuid<N extends string>(name: N): Fresh<N, string>;
 declare function uuid(): Fresh<undefined, string>;
@@ -148,9 +166,13 @@ declare function enumColumn<N extends string, const T extends readonly [string,
 declare function enumColumn<const T extends readonly [string, ...string[]]>(values: T): Fresh<undefined, T[number], T>;
 declare function integer<N extends string>(name: N): Fresh<N, number>;
 declare function integer(): Fresh<undefined, number>;
-/** int8. A string in JS: that is what `pg` returns, and no precision is lost. */
-declare function bigint<N extends string>(name: N): Fresh<N, string>;
-declare function bigint(): Fresh<undefined, string>;
+/**
+ * int8. A string in JS by default: that is what `pg` and `Bun.SQL` return, and no
+ * precision is lost. A driver told to return `bigint` is matched by the
+ * `bigint: true` infer option, which turns these columns into `bigint`.
+ */
+declare function bigint<N extends string>(name: N): Fresh<N, string, undefined, false, true>;
+declare function bigint(): Fresh<undefined, string, undefined, false, true>;
 declare function boolean<N extends string>(name: N): Fresh<N, boolean>;
 declare function boolean(): Fresh<undefined, boolean>;
 interface NumericConfig {

package/dist/table/columns.js

@@ -28,7 +28,11 @@ export class ColumnBuilder {
     array() {
         return this.next({ array: true });
     }
-    /** Narrows the value type without touching the column type in the database. */
+    /**
+     * Narrows the value type without touching the column type in the database. The
+     * type is final: on a `bigint()` column it also switches the `bigint: true` infer
+     * option off.
+     */
     // oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- the type parameter is the whole point of the method
     $type() {
         return this;

package/dist/table/define.d.ts

@@ -44,6 +44,7 @@ export type ResolveColumns<TCols extends Record<string, AnyColumn>> = {
         readonly identity: TCols[K]['_']['identity'];
         readonly enumValues: TCols[K]['_']['enumValues'];
         readonly json: TCols[K]['_']['json'];
+        readonly bigint: TCols[K]['_']['bigint'];
     };
 };
 export type ReferentialAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely-ddl",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "PostgreSQL schema as TypeScript code: SQL migrations from snapshot diffs, Kysely table types and a migration runner",
   "keywords": [
     "postgres",