@forinda/kickjs-db 8.0.0 → 8.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -45
- package/dist/cli.d.mts +16 -2
- package/dist/cli.d.mts.map +1 -1
- package/dist/cli.mjs +4 -3
- package/dist/cli.mjs.map +1 -1
- package/dist/create-CwuC1odW.mjs +29 -0
- package/dist/create-CwuC1odW.mjs.map +1 -0
- package/dist/custom-type-DeGuRFuz.mjs +12 -0
- package/dist/custom-type-DeGuRFuz.mjs.map +1 -0
- package/dist/devtools-events.d.mts +1 -1
- package/dist/devtools-events.mjs +1 -1
- package/dist/{index-BQQWKybR.d.mts → index-2fEnHqpn.d.mts} +702 -167
- package/dist/index-2fEnHqpn.d.mts.map +1 -0
- package/dist/index.d.mts +6 -4
- package/dist/index.mjs +2 -2
- package/dist/mysql.d.mts +41 -37
- package/dist/mysql.d.mts.map +1 -1
- package/dist/mysql.mjs +8 -8
- package/dist/mysql.mjs.map +1 -1
- package/dist/pg-CsmRByEZ.mjs +12 -0
- package/dist/pg-CsmRByEZ.mjs.map +1 -0
- package/dist/pg.d.mts +74 -8
- package/dist/pg.d.mts.map +1 -1
- package/dist/pg.mjs +8 -7
- package/dist/pg.mjs.map +1 -1
- package/dist/schema-BjGAg-s1.d.mts +95 -0
- package/dist/schema-BjGAg-s1.d.mts.map +1 -0
- package/dist/schema-types-DH-d43Pf.d.mts +51 -0
- package/dist/schema-types-DH-d43Pf.d.mts.map +1 -0
- package/dist/schema.d.mts +1 -1
- package/dist/schema.mjs +2 -2
- package/dist/schema.mjs.map +1 -1
- package/dist/split-statements-BPCw9cII.mjs +14 -0
- package/dist/split-statements-BPCw9cII.mjs.map +1 -0
- package/dist/sqlite.d.mts +86 -6
- package/dist/sqlite.d.mts.map +1 -1
- package/dist/sqlite.mjs +13 -7
- package/dist/sqlite.mjs.map +1 -1
- package/dist/src-DUtVGG2c.mjs +199 -0
- package/dist/src-DUtVGG2c.mjs.map +1 -0
- package/dist/table-CGPsm5i7.d.mts +221 -0
- package/dist/table-CGPsm5i7.d.mts.map +1 -0
- package/dist/testing.d.mts +53 -0
- package/dist/testing.d.mts.map +1 -0
- package/dist/testing.mjs +12 -0
- package/dist/testing.mjs.map +1 -0
- package/dist/{types-DtvYnaXL.d.mts → types-BZoTujcR.d.mts} +346 -9
- package/dist/types-BZoTujcR.d.mts.map +1 -0
- package/dist/{schema-DDMkteEP.d.mts → types-DNAKmwPO.d.mts} +174 -159
- package/dist/types-DNAKmwPO.d.mts.map +1 -0
- package/package.json +15 -5
- package/dist/custom-type-CZdUgkPT.mjs +0 -12
- package/dist/custom-type-CZdUgkPT.mjs.map +0 -1
- package/dist/index-BQQWKybR.d.mts.map +0 -1
- package/dist/pg-CwNv938J.mjs +0 -12
- package/dist/pg-CwNv938J.mjs.map +0 -1
- package/dist/schema-DDMkteEP.d.mts.map +0 -1
- package/dist/src-BEJ33yHI.mjs +0 -166
- package/dist/src-BEJ33yHI.mjs.map +0 -1
- package/dist/types-DtvYnaXL.d.mts.map +0 -1
|
@@ -1,11 +1,153 @@
|
|
|
1
1
|
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
2
|
+
import { C as TableSnapshot, S as SchemaSnapshot, _ as ForeignKeySnapshot, b as RelationSnapshot, d as TypedColumnRefs, f as CheckSnapshot, h as EnumSnapshot, l as NotNullBrand, m as Dialect$1, n as ColumnRef, o as GeneratedBrand, p as ColumnSnapshot, t as ColumnBuilder, u as TypedColumnRef, v as IndexSnapshot, w as ViewSnapshot, x as RoleSnapshot, y as PolicySnapshot } from "./types-DNAKmwPO.mjs";
|
|
3
|
+
import { _ as RelationMapEntry, n as CreateDbClientOptions, r as KickDbClient } from "./types-BZoTujcR.mjs";
|
|
4
|
+
import { f as TableConstraint, l as IndexDecl, n as TableDecl } from "./table-CGPsm5i7.mjs";
|
|
5
|
+
import { t as SchemaToTypes } from "./schema-types-DH-d43Pf.mjs";
|
|
6
|
+
import { o as SchemaLike, t as ColumnRule } from "./schema-BjGAg-s1.mjs";
|
|
7
|
+
import { CompiledQuery, Expression, ExpressionBuilder, Kysely, KyselyPlugin, RawBuilder, SelectType, SqlBool } from "kysely";
|
|
4
8
|
import { InjectionToken } from "@forinda/kickjs";
|
|
5
|
-
import {
|
|
9
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
6
10
|
import { ReadonlyKysely } from "kysely/readonly";
|
|
11
|
+
//#region src/migrate/adapter.d.ts
|
|
12
|
+
interface MigrationRow {
|
|
13
|
+
id: string;
|
|
14
|
+
name: string;
|
|
15
|
+
hash: string;
|
|
16
|
+
batch: number;
|
|
17
|
+
appliedAt: string;
|
|
18
|
+
direction: 'up' | 'down';
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Slim contract that connects the runner to a concrete database driver.
|
|
22
|
+
*
|
|
23
|
+
* Concrete impls: MemoryMigrationAdapter (this package, test-only) and
|
|
24
|
+
* pgAdapter from @forinda/kickjs-db/pg. Future db-sqlite / db-mysql adapter
|
|
25
|
+
* packages will satisfy this same shape so the runner stays driver-agnostic.
|
|
26
|
+
*/
|
|
27
|
+
interface MigrationAdapter {
|
|
28
|
+
readonly dialect: Dialect$1;
|
|
29
|
+
/** Idempotent CREATE TABLE IF NOT EXISTS for kick_migrations + kick_migrations_lock. */
|
|
30
|
+
ensureMigrationTables(): Promise<void>;
|
|
31
|
+
/** Read all applied migrations ordered by appliedAt asc, then id asc. */
|
|
32
|
+
listApplied(): Promise<MigrationRow[]>;
|
|
33
|
+
/** Insert a new applied migration row; appliedAt is set by the DB. */
|
|
34
|
+
recordApplied(row: Omit<MigrationRow, 'appliedAt'>): Promise<void>;
|
|
35
|
+
/** Delete an applied migration row (used by `migrate down`). */
|
|
36
|
+
removeApplied(id: string): Promise<void>;
|
|
37
|
+
/** Atomic lock acquire — true if we got it, false if held. Owner string is recorded for diagnostics. */
|
|
38
|
+
acquireLock(owner: string): Promise<boolean>;
|
|
39
|
+
/** Release the lock (no-op if not held). */
|
|
40
|
+
releaseLock(): Promise<void>;
|
|
41
|
+
/** Run arbitrary SQL inside a transaction. Used to apply up.sql / down.sql. */
|
|
42
|
+
applySqlInTx(sql: string): Promise<void>;
|
|
43
|
+
/**
|
|
44
|
+
* Run a migration's SQL and its bookkeeping — insert its `kick_migrations`
|
|
45
|
+
* row on the way up, delete it on the way down — in one transaction, so a
|
|
46
|
+
* crash between the two can't leave a migration applied but unrecorded (or
|
|
47
|
+
* reverted but still recorded). Optional: without it the runner calls
|
|
48
|
+
* `applySqlInTx` and then `recordApplied` / `removeApplied`.
|
|
49
|
+
*/
|
|
50
|
+
applyMigrationInTx?(sql: string, bookkeeping: MigrationBookkeeping | null): Promise<void>;
|
|
51
|
+
/** Apply SQL outside any transaction — for migrations with `meta.transaction: false` (CREATE INDEX CONCURRENTLY etc). */
|
|
52
|
+
applySqlNoTx(sql: string): Promise<void>;
|
|
53
|
+
/** Introspect the live schema; returns the canonical SchemaSnapshot. Used by drift detection and `kick db introspect`. */
|
|
54
|
+
introspect(): Promise<SchemaSnapshot>;
|
|
55
|
+
/**
|
|
56
|
+
* A Kysely instance on the adapter's connection — what a migration written
|
|
57
|
+
* in TypeScript (`migration.ts`) runs with. Optional: an adapter without it
|
|
58
|
+
* can't run those migrations.
|
|
59
|
+
*/
|
|
60
|
+
kysely?(): Kysely<any>;
|
|
61
|
+
/** The table migrations are recorded in, when not `kick_migrations`. */
|
|
62
|
+
readonly migrationsTable?: string;
|
|
63
|
+
/** Close any underlying pool / connection. Caller-owned resources may keep the no-op. */
|
|
64
|
+
close(): Promise<void>;
|
|
65
|
+
}
|
|
66
|
+
/** What `applyMigrationInTx` writes to `kick_migrations` with the migration's SQL. */
|
|
67
|
+
type MigrationBookkeeping = {
|
|
68
|
+
record: Omit<MigrationRow, 'appliedAt'>;
|
|
69
|
+
} | {
|
|
70
|
+
remove: string;
|
|
71
|
+
};
|
|
72
|
+
//#endregion
|
|
73
|
+
//#region src/migrate/drift.d.ts
|
|
74
|
+
type DriftBehavior = 'error' | 'warn' | 'ignore';
|
|
75
|
+
interface DriftLogger {
|
|
76
|
+
warn: (message: string) => void;
|
|
77
|
+
}
|
|
78
|
+
declare function checkDrift(liveSnapshot: SchemaSnapshot, expectedSnapshot: SchemaSnapshot, behavior: DriftBehavior, log?: DriftLogger): Promise<void>;
|
|
79
|
+
//#endregion
|
|
80
|
+
//#region src/cli/config.d.ts
|
|
81
|
+
type MigrationAdapterFactory = () => MigrationAdapter | Promise<MigrationAdapter>;
|
|
82
|
+
interface DbConfig {
|
|
83
|
+
schemaPath: string;
|
|
84
|
+
migrationsDir: string;
|
|
85
|
+
/** Where `kick db seed` finds seed files. Default `db/seeds`. */
|
|
86
|
+
seedsDir?: string;
|
|
87
|
+
dialect: Dialect$1;
|
|
88
|
+
/**
|
|
89
|
+
* How `kick db migrate` reacts when the live DB has schema not recorded
|
|
90
|
+
* in the migrations (someone ran DDL out of band): `'error'` (default —
|
|
91
|
+
* refuse), `'warn'` (log + continue), `'ignore'` (skip the check). The
|
|
92
|
+
* check is dialect-normalised, so SQLite/MySQL's lossy introspection
|
|
93
|
+
* doesn't false-positive.
|
|
94
|
+
*/
|
|
95
|
+
driftCheck?: DriftBehavior;
|
|
96
|
+
/**
|
|
97
|
+
* `'snake_case'`: migrations name tables and columns in snake_case while
|
|
98
|
+
* the schema's keys stay camelCase. Pass the same `casing` to `createDbClient`.
|
|
99
|
+
*/
|
|
100
|
+
casing?: 'snake_case';
|
|
101
|
+
/**
|
|
102
|
+
* The table migrations are recorded in (default `kick_migrations`) — for
|
|
103
|
+
* the built-in Postgres adapter. An `adapter()` factory passes it itself:
|
|
104
|
+
* `pgAdapter({ pool, migrationsTable })`.
|
|
105
|
+
*/
|
|
106
|
+
migrationsTable?: string;
|
|
107
|
+
/** More migration folders, run with `migrationsDir` as one history. */
|
|
108
|
+
migrationsDirs?: string[];
|
|
109
|
+
/**
|
|
110
|
+
* Postgres connection string for the built-in pgAdapter path. Read from
|
|
111
|
+
* `db.connectionString` in kick.config.ts, or falls back to the
|
|
112
|
+
* DATABASE_URL env var. The CLI uses this when no `adapter` factory is
|
|
113
|
+
* provided.
|
|
114
|
+
*/
|
|
115
|
+
connectionString?: string;
|
|
116
|
+
/**
|
|
117
|
+
* Escape hatch: a factory returning a fully-constructed MigrationAdapter.
|
|
118
|
+
* Takes precedence over `connectionString` when both are set. Use this
|
|
119
|
+
* for non-default adapter wiring (custom pool, neon-serverless, etc).
|
|
120
|
+
*/
|
|
121
|
+
adapter?: MigrationAdapterFactory;
|
|
122
|
+
/**
|
|
123
|
+
* Schema- or database-per-tenant: the tenants, and the adapter for one —
|
|
124
|
+
* what `kick db migrate latest --tenants` runs with.
|
|
125
|
+
*/
|
|
126
|
+
tenants?: TenantsConfig;
|
|
127
|
+
}
|
|
128
|
+
interface TenantsConfig {
|
|
129
|
+
/** Every tenant's id — typically read from the central database. */
|
|
130
|
+
list: () => readonly string[] | Promise<readonly string[]>;
|
|
131
|
+
/** The migration adapter for one tenant (closed after it's migrated). */
|
|
132
|
+
adapter: (tenantId: string) => MigrationAdapter | Promise<MigrationAdapter>;
|
|
133
|
+
/** Tenants migrated at once. Default 1. */
|
|
134
|
+
concurrency?: number;
|
|
135
|
+
}
|
|
136
|
+
declare function resolveDbConfig(opts: {
|
|
137
|
+
configPath: string;
|
|
138
|
+
}): Promise<DbConfig>;
|
|
139
|
+
//#endregion
|
|
140
|
+
//#region src/snapshot/casing.d.ts
|
|
141
|
+
type Casing = 'snake_case';
|
|
142
|
+
/** A TypeScript key as the database names it: `firstName` → `first_name`. */
|
|
143
|
+
declare const toDbName: (key: string) => string;
|
|
144
|
+
/** A database name as a TypeScript key: `first_name` → `firstName`. */
|
|
145
|
+
declare const toKeyName: (name: string) => string;
|
|
146
|
+
//#endregion
|
|
7
147
|
//#region src/snapshot/extract.d.ts
|
|
8
|
-
declare function extractSnapshot(schema: Record<string, unknown>, dialect: Dialect$1
|
|
148
|
+
declare function extractSnapshot(schema: Record<string, unknown>, dialect: Dialect$1, options?: {
|
|
149
|
+
casing?: Casing;
|
|
150
|
+
}): SchemaSnapshot;
|
|
9
151
|
//#endregion
|
|
10
152
|
//#region src/snapshot/name.d.ts
|
|
11
153
|
/**
|
|
@@ -183,11 +325,135 @@ interface RemoveEnumValue {
|
|
|
183
325
|
default: string | null;
|
|
184
326
|
}[];
|
|
185
327
|
}
|
|
186
|
-
|
|
328
|
+
/** A table's primary key as a change sees it. Empty `columns` = no key. */
|
|
329
|
+
interface PrimaryKeyShape {
|
|
330
|
+
name?: string;
|
|
331
|
+
columns: string[];
|
|
332
|
+
}
|
|
333
|
+
/**
|
|
334
|
+
* The primary key changed: different columns, column order, or (Postgres)
|
|
335
|
+
* name. `before.columns` empty means one is added; `after.columns` empty,
|
|
336
|
+
* that it's dropped. Emitters drop the old key, then add the new one.
|
|
337
|
+
*/
|
|
338
|
+
interface AlterPrimaryKey {
|
|
339
|
+
kind: 'alterPrimaryKey';
|
|
340
|
+
table: string;
|
|
341
|
+
before: PrimaryKeyShape;
|
|
342
|
+
after: PrimaryKeyShape;
|
|
343
|
+
}
|
|
344
|
+
interface AddCheck {
|
|
345
|
+
kind: 'addCheck';
|
|
346
|
+
table: string;
|
|
347
|
+
check: CheckSnapshot;
|
|
348
|
+
}
|
|
349
|
+
interface DropCheck {
|
|
350
|
+
kind: 'dropCheck';
|
|
351
|
+
table: string;
|
|
352
|
+
check: CheckSnapshot;
|
|
353
|
+
}
|
|
354
|
+
/**
|
|
355
|
+
* Create a role if it doesn't exist (Postgres). Roles belong to the server,
|
|
356
|
+
* so a removed one is never dropped and a down migration doesn't drop it.
|
|
357
|
+
*/
|
|
358
|
+
interface CreateRole {
|
|
359
|
+
kind: 'createRole';
|
|
360
|
+
role: RoleSnapshot;
|
|
361
|
+
}
|
|
362
|
+
/** Change a declared role's attributes (Postgres). Not inverted, like CreateRole. */
|
|
363
|
+
interface AlterRole {
|
|
364
|
+
kind: 'alterRole';
|
|
365
|
+
role: RoleSnapshot;
|
|
366
|
+
}
|
|
367
|
+
/** Turn row-level security on or off for a table, and whether it binds the owner. */
|
|
368
|
+
interface SetRowLevelSecurity {
|
|
369
|
+
kind: 'setRowLevelSecurity';
|
|
370
|
+
table: string;
|
|
371
|
+
from: {
|
|
372
|
+
force?: true;
|
|
373
|
+
} | null;
|
|
374
|
+
to: {
|
|
375
|
+
force?: true;
|
|
376
|
+
} | null;
|
|
377
|
+
}
|
|
378
|
+
interface CreatePolicy {
|
|
379
|
+
kind: 'createPolicy';
|
|
380
|
+
table: string;
|
|
381
|
+
policy: PolicySnapshot;
|
|
382
|
+
}
|
|
383
|
+
interface DropPolicy {
|
|
384
|
+
kind: 'dropPolicy';
|
|
385
|
+
table: string;
|
|
386
|
+
policy: PolicySnapshot;
|
|
387
|
+
}
|
|
388
|
+
/** Create a view (after every table change in the migration). */
|
|
389
|
+
interface CreateView {
|
|
390
|
+
kind: 'createView';
|
|
391
|
+
view: ViewSnapshot;
|
|
392
|
+
}
|
|
393
|
+
/** Drop a view (before every table change in the migration). */
|
|
394
|
+
interface DropView {
|
|
395
|
+
kind: 'dropView';
|
|
396
|
+
view: ViewSnapshot;
|
|
397
|
+
}
|
|
398
|
+
/** A table's comment changed; `null` is none. */
|
|
399
|
+
interface SetTableComment {
|
|
400
|
+
kind: 'setTableComment';
|
|
401
|
+
table: string;
|
|
402
|
+
from: string | null;
|
|
403
|
+
to: string | null;
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* A column's comment changed; `null` is none. `column` is its definition,
|
|
407
|
+
* for MySQL, which can only set a comment by restating it.
|
|
408
|
+
*/
|
|
409
|
+
interface SetColumnComment {
|
|
410
|
+
kind: 'setColumnComment';
|
|
411
|
+
table: string;
|
|
412
|
+
column: ColumnSnapshot;
|
|
413
|
+
from: string | null;
|
|
414
|
+
to: string | null;
|
|
415
|
+
}
|
|
416
|
+
type Change = CreateSchema | CreateTable | DropTable | RenameTable | AddColumn | DropColumn | RenameColumn | AlterColumn | AddIndex | DropIndex | AddForeignKey | DropForeignKey | CreateEnum | DropEnum | AddEnumValue | RemoveEnumValue | AlterPrimaryKey | AddCheck | DropCheck | SetTableComment | SetColumnComment | CreateView | DropView | CreateRole | AlterRole | SetRowLevelSecurity | CreatePolicy | DropPolicy;
|
|
187
417
|
type ChangeSet = Change[];
|
|
188
418
|
//#endregion
|
|
189
419
|
//#region src/diff/engine.d.ts
|
|
190
|
-
|
|
420
|
+
/**
|
|
421
|
+
* Renames to apply instead of a drop and an add. Names are qualified
|
|
422
|
+
* (`billing.invoices`) when the table lives in a schema.
|
|
423
|
+
*/
|
|
424
|
+
interface RenameHints {
|
|
425
|
+
/** Old table name → new table name. */
|
|
426
|
+
tables?: Record<string, string>;
|
|
427
|
+
/** `<new table>.<old column>` → new column name. */
|
|
428
|
+
columns?: Record<string, string>;
|
|
429
|
+
}
|
|
430
|
+
interface DiffOptions {
|
|
431
|
+
renames?: RenameHints;
|
|
432
|
+
/**
|
|
433
|
+
* When true, only `renames` pair a drop with an add; the one-drop,
|
|
434
|
+
* one-add guess is off. Set once someone has answered for every candidate.
|
|
435
|
+
*/
|
|
436
|
+
explicitRenames?: boolean;
|
|
437
|
+
}
|
|
438
|
+
declare function diff(prev: SchemaSnapshot, next: SchemaSnapshot, options?: DiffOptions): ChangeSet;
|
|
439
|
+
/** Drops that might be renames: each lists what it could have become. */
|
|
440
|
+
interface RenameCandidates {
|
|
441
|
+
tables: {
|
|
442
|
+
from: string;
|
|
443
|
+
to: string[];
|
|
444
|
+
}[];
|
|
445
|
+
columns: {
|
|
446
|
+
table: string;
|
|
447
|
+
from: string;
|
|
448
|
+
to: string[];
|
|
449
|
+
}[];
|
|
450
|
+
}
|
|
451
|
+
/**
|
|
452
|
+
* Every dropped table that a created table could replace, and every dropped
|
|
453
|
+
* column that a column added to the same table could replace — the cases
|
|
454
|
+
* where a drop might really be a rename, so someone should say which.
|
|
455
|
+
*/
|
|
456
|
+
declare function findRenameCandidates(prev: SchemaSnapshot, next: SchemaSnapshot): RenameCandidates;
|
|
191
457
|
//#endregion
|
|
192
458
|
//#region src/diff/invert.d.ts
|
|
193
459
|
/**
|
|
@@ -284,6 +550,87 @@ declare class CompositeEnumReferenceError extends KickDbError {
|
|
|
284
550
|
constructor(refs: readonly CompositeRef[]);
|
|
285
551
|
}
|
|
286
552
|
//#endregion
|
|
553
|
+
//#region src/query/relations.d.ts
|
|
554
|
+
type ResolvedRelation = RelationSnapshot;
|
|
555
|
+
/**
|
|
556
|
+
* Sidecar map: source table → relation name → resolved entry. Lives
|
|
557
|
+
* on `SchemaSnapshot.relations` and is populated by
|
|
558
|
+
* `extractRelations()` (`query/extract-relations.ts`).
|
|
559
|
+
*/
|
|
560
|
+
type ResolvedRelations = Record<string, Record<string, ResolvedRelation>>;
|
|
561
|
+
//#endregion
|
|
562
|
+
//#region src/client/wrap.d.ts
|
|
563
|
+
/**
|
|
564
|
+
* A query ran on a call chain whose transaction had already finished —
|
|
565
|
+
* typically a promise started inside `transaction()` that wasn't awaited.
|
|
566
|
+
*/
|
|
567
|
+
declare class TransactionFinishedError extends KickDbError {
|
|
568
|
+
constructor();
|
|
569
|
+
}
|
|
570
|
+
//#endregion
|
|
571
|
+
//#region src/db-errors.d.ts
|
|
572
|
+
type DbDialect = 'postgres' | 'mysql' | 'sqlite';
|
|
573
|
+
/** What the database reported, parsed. */
|
|
574
|
+
interface DatabaseErrorInfo {
|
|
575
|
+
dialect: DbDialect;
|
|
576
|
+
/** SQLSTATE (Postgres, MySQL) or the driver's error code (`SQLITE_CONSTRAINT_UNIQUE`, `ER_DUP_ENTRY`). */
|
|
577
|
+
driverCode?: string;
|
|
578
|
+
constraint?: string;
|
|
579
|
+
table?: string;
|
|
580
|
+
/** Columns involved, when the database names them. */
|
|
581
|
+
columns: string[];
|
|
582
|
+
/** The database's own explanation (Postgres `detail`). */
|
|
583
|
+
detail?: string;
|
|
584
|
+
}
|
|
585
|
+
/** A failure the database reported. Subclasses name the common kinds. */
|
|
586
|
+
declare class DatabaseError extends KickDbError {
|
|
587
|
+
readonly dialect: DbDialect;
|
|
588
|
+
readonly driverCode?: string;
|
|
589
|
+
readonly constraint?: string;
|
|
590
|
+
readonly table?: string;
|
|
591
|
+
readonly columns: string[];
|
|
592
|
+
readonly detail?: string;
|
|
593
|
+
constructor(code: string, message: string, info: DatabaseErrorInfo, cause: unknown);
|
|
594
|
+
/** Whether running the transaction again can succeed — true for serialization failures and deadlocks. */
|
|
595
|
+
get retryable(): boolean;
|
|
596
|
+
}
|
|
597
|
+
/** A row would duplicate a unique or primary key. Answers `409` when unhandled. */
|
|
598
|
+
declare class UniqueViolationError extends DatabaseError {
|
|
599
|
+
readonly status = 409;
|
|
600
|
+
constructor(info: DatabaseErrorInfo, cause: unknown);
|
|
601
|
+
}
|
|
602
|
+
/** A row references one that doesn't exist, or a referenced row was deleted. */
|
|
603
|
+
declare class ForeignKeyViolationError extends DatabaseError {
|
|
604
|
+
constructor(info: DatabaseErrorInfo, cause: unknown);
|
|
605
|
+
}
|
|
606
|
+
/** A CHECK constraint rejected the row. */
|
|
607
|
+
declare class CheckViolationError extends DatabaseError {
|
|
608
|
+
constructor(info: DatabaseErrorInfo, cause: unknown);
|
|
609
|
+
}
|
|
610
|
+
/** A NOT NULL column got null. */
|
|
611
|
+
declare class NotNullViolationError extends DatabaseError {
|
|
612
|
+
constructor(info: DatabaseErrorInfo, cause: unknown);
|
|
613
|
+
}
|
|
614
|
+
/** The transaction conflicted with a concurrent one — run it again. */
|
|
615
|
+
declare class SerializationFailureError extends DatabaseError {
|
|
616
|
+
constructor(info: DatabaseErrorInfo, cause: unknown);
|
|
617
|
+
get retryable(): boolean;
|
|
618
|
+
}
|
|
619
|
+
/** Two transactions waited on each other; the database cancelled this one — run it again. */
|
|
620
|
+
declare class DeadlockError extends DatabaseError {
|
|
621
|
+
constructor(info: DatabaseErrorInfo, cause: unknown);
|
|
622
|
+
get retryable(): boolean;
|
|
623
|
+
}
|
|
624
|
+
/** The database couldn't be reached, or dropped the connection. */
|
|
625
|
+
declare class ConnectionError extends DatabaseError {
|
|
626
|
+
constructor(info: DatabaseErrorInfo, cause: unknown);
|
|
627
|
+
}
|
|
628
|
+
/**
|
|
629
|
+
* The typed error for a driver failure, or the input unchanged when it isn't
|
|
630
|
+
* one (a `TypeError` from your own code, an error already translated).
|
|
631
|
+
*/
|
|
632
|
+
declare function translateDbError(err: unknown, dialect: DbDialect): unknown;
|
|
633
|
+
//#endregion
|
|
287
634
|
//#region src/migrate/errors.d.ts
|
|
288
635
|
declare class MigrationError extends KickDbError {}
|
|
289
636
|
declare class MigrationLockError extends MigrationError {
|
|
@@ -298,6 +645,15 @@ declare class MigrationDriftError extends MigrationError {
|
|
|
298
645
|
readonly diff: SchemaDiffSummary;
|
|
299
646
|
constructor(message: string, diff: SchemaDiffSummary);
|
|
300
647
|
}
|
|
648
|
+
/**
|
|
649
|
+
* A migration's SQL failed to apply. Names the migration — with several
|
|
650
|
+
* pending, the driver's own message ("no such table: …") doesn't say which —
|
|
651
|
+
* and keeps the driver error as `cause`. The migration stays pending.
|
|
652
|
+
*/
|
|
653
|
+
declare class MigrationFailedError extends MigrationError {
|
|
654
|
+
readonly id: string;
|
|
655
|
+
constructor(id: string, cause: unknown);
|
|
656
|
+
}
|
|
301
657
|
declare class MigrationHashError extends MigrationError {
|
|
302
658
|
readonly id: string;
|
|
303
659
|
readonly expected: string;
|
|
@@ -375,51 +731,18 @@ declare function appendJournalEntry(migrationsDir: string, dialect: Dialect$1, e
|
|
|
375
731
|
declare function computeMigrationHash(migrationDir: string): Promise<string>;
|
|
376
732
|
declare function verifyMigrationHash(migrationDir: string, expected: string): Promise<boolean>;
|
|
377
733
|
//#endregion
|
|
378
|
-
//#region src/migrate/adapter.d.ts
|
|
379
|
-
interface MigrationRow {
|
|
380
|
-
id: string;
|
|
381
|
-
name: string;
|
|
382
|
-
hash: string;
|
|
383
|
-
batch: number;
|
|
384
|
-
appliedAt: string;
|
|
385
|
-
direction: 'up' | 'down';
|
|
386
|
-
}
|
|
387
|
-
/**
|
|
388
|
-
* Slim contract that connects the runner to a concrete database driver.
|
|
389
|
-
*
|
|
390
|
-
* Concrete impls: MemoryMigrationAdapter (this package, test-only) and
|
|
391
|
-
* pgAdapter from @forinda/kickjs-db/pg. Future db-sqlite / db-mysql adapter
|
|
392
|
-
* packages will satisfy this same shape so the runner stays driver-agnostic.
|
|
393
|
-
*/
|
|
394
|
-
interface MigrationAdapter {
|
|
395
|
-
readonly dialect: Dialect$1;
|
|
396
|
-
/** Idempotent CREATE TABLE IF NOT EXISTS for kick_migrations + kick_migrations_lock. */
|
|
397
|
-
ensureMigrationTables(): Promise<void>;
|
|
398
|
-
/** Read all applied migrations ordered by appliedAt asc, then id asc. */
|
|
399
|
-
listApplied(): Promise<MigrationRow[]>;
|
|
400
|
-
/** Insert a new applied migration row; appliedAt is set by the DB. */
|
|
401
|
-
recordApplied(row: Omit<MigrationRow, 'appliedAt'>): Promise<void>;
|
|
402
|
-
/** Delete an applied migration row (used by `migrate down`). */
|
|
403
|
-
removeApplied(id: string): Promise<void>;
|
|
404
|
-
/** Atomic lock acquire — true if we got it, false if held. Owner string is recorded for diagnostics. */
|
|
405
|
-
acquireLock(owner: string): Promise<boolean>;
|
|
406
|
-
/** Release the lock (no-op if not held). */
|
|
407
|
-
releaseLock(): Promise<void>;
|
|
408
|
-
/** Run arbitrary SQL inside a transaction. Used to apply up.sql / down.sql. */
|
|
409
|
-
applySqlInTx(sql: string): Promise<void>;
|
|
410
|
-
/** Apply SQL outside any transaction — for migrations with `meta.transaction: false` (CREATE INDEX CONCURRENTLY etc). */
|
|
411
|
-
applySqlNoTx(sql: string): Promise<void>;
|
|
412
|
-
/** Introspect the live schema; returns the canonical SchemaSnapshot. Used by drift detection and `kick db introspect`. */
|
|
413
|
-
introspect(): Promise<SchemaSnapshot>;
|
|
414
|
-
/** Close any underlying pool / connection. Caller-owned resources may keep the no-op. */
|
|
415
|
-
close(): Promise<void>;
|
|
416
|
-
}
|
|
417
|
-
//#endregion
|
|
418
734
|
//#region src/migrate/schema.d.ts
|
|
419
735
|
declare const KICK_MIGRATIONS_TABLE = "kick_migrations";
|
|
420
736
|
declare const KICK_LOCK_TABLE = "kick_migrations_lock";
|
|
421
|
-
|
|
422
|
-
declare function
|
|
737
|
+
/** The lock table that goes with a migrations table. */
|
|
738
|
+
declare function lockTableName(table: string): string;
|
|
739
|
+
/**
|
|
740
|
+
* A table name quoted for the dialect. A dotted name is schema-qualified on
|
|
741
|
+
* Postgres (`meta.kick_migrations`); elsewhere a dot is part of the name.
|
|
742
|
+
*/
|
|
743
|
+
declare function quoteTable(dialect: Dialect$1, name: string): string;
|
|
744
|
+
declare function migrationsTableDdl(dialect: Dialect$1, table?: string): string;
|
|
745
|
+
declare function lockTableDdl(dialect: Dialect$1, table?: string): string;
|
|
423
746
|
//#endregion
|
|
424
747
|
//#region src/migrate/memory-adapter.d.ts
|
|
425
748
|
/**
|
|
@@ -441,6 +764,7 @@ declare class MemoryMigrationAdapter implements MigrationAdapter {
|
|
|
441
764
|
acquireLock(owner: string): Promise<boolean>;
|
|
442
765
|
releaseLock(): Promise<void>;
|
|
443
766
|
applySqlInTx(sql: string): Promise<void>;
|
|
767
|
+
applyMigrationInTx(sql: string, bookkeeping: MigrationBookkeeping | null): Promise<void>;
|
|
444
768
|
applySqlNoTx(sql: string): Promise<void>;
|
|
445
769
|
introspect(): Promise<SchemaSnapshot>;
|
|
446
770
|
close(): Promise<void>;
|
|
@@ -498,6 +822,11 @@ interface IntrospectSqliteOptions {
|
|
|
498
822
|
* a schema), not byte-exact drift against a code-first snapshot.
|
|
499
823
|
*/
|
|
500
824
|
declare function introspectSqlite(db: SqliteIntrospectDb, opts?: IntrospectSqliteOptions): SchemaSnapshot;
|
|
825
|
+
/**
|
|
826
|
+
* {@link introspectSqlite} over an async driver (libsql/Turso, Cloudflare D1):
|
|
827
|
+
* `query` runs one statement and resolves with its rows.
|
|
828
|
+
*/
|
|
829
|
+
declare function introspectSqliteAsync(query: (sql: string, params: unknown[]) => Promise<unknown[]>, opts?: IntrospectSqliteOptions): Promise<SchemaSnapshot>;
|
|
501
830
|
//#endregion
|
|
502
831
|
//#region src/migrate/introspect-mysql.d.ts
|
|
503
832
|
/** Minimal mysql2 surface introspection needs. Returns `[rows, fields]`. */
|
|
@@ -516,20 +845,13 @@ interface IntrospectMysqlOptions {
|
|
|
516
845
|
*/
|
|
517
846
|
declare function introspectMysql(db: MysqlIntrospectDb, opts?: IntrospectMysqlOptions): Promise<SchemaSnapshot>;
|
|
518
847
|
//#endregion
|
|
519
|
-
//#region src/migrate/drift.d.ts
|
|
520
|
-
type DriftBehavior = 'error' | 'warn' | 'ignore';
|
|
521
|
-
interface DriftLogger {
|
|
522
|
-
warn: (message: string) => void;
|
|
523
|
-
}
|
|
524
|
-
declare function checkDrift(liveSnapshot: SchemaSnapshot, expectedSnapshot: SchemaSnapshot, behavior: DriftBehavior, log?: DriftLogger): Promise<void>;
|
|
525
|
-
//#endregion
|
|
526
848
|
//#region src/adapter.d.ts
|
|
527
849
|
type MigrationsOnBoot = 'fail-if-pending' | 'apply' | 'ignore';
|
|
528
850
|
interface KickDbAdapterConfig {
|
|
529
851
|
/** The driver-bound MigrationAdapter — pgAdapter() in @forinda/kickjs-db/pg, etc. */
|
|
530
852
|
migrationAdapter: MigrationAdapter;
|
|
531
|
-
/** Directory containing the generated migrations + _journal.json. */
|
|
532
|
-
migrationsDir: string;
|
|
853
|
+
/** Directory containing the generated migrations + _journal.json — or several, run as one history. */
|
|
854
|
+
migrationsDir: string | readonly string[];
|
|
533
855
|
/** Boot policy. Default 'fail-if-pending' — mirror the operator-explicit philosophy. */
|
|
534
856
|
migrationsOnBoot?: MigrationsOnBoot;
|
|
535
857
|
/** Drift detection mode. Default 'error' outside dev. */
|
|
@@ -568,7 +890,7 @@ interface KickDbAdapterConfig {
|
|
|
568
890
|
* - 'apply': run migrateLatest() automatically. Useful for dev / preview
|
|
569
891
|
* environments where convenience matters more than safety.
|
|
570
892
|
* - 'ignore': boot regardless. Last-resort escape hatch.
|
|
571
|
-
* 2. On shutdown, close the migrationAdapter (
|
|
893
|
+
* 2. On shutdown, close the migrationAdapter (ends its pool only when created with `endPoolOnClose`).
|
|
572
894
|
* 3. Register the migrationAdapter under an optional DI token so adopters
|
|
573
895
|
* can pull it for ad-hoc tooling. The KickDbClient (Task 19b) registers
|
|
574
896
|
* separately under DB_PRIMARY.
|
|
@@ -584,51 +906,6 @@ declare const DB_REPLICA: InjectionToken<KickDbClient>;
|
|
|
584
906
|
*/
|
|
585
907
|
declare const DB_CLIENT: InjectionToken<KickDbClient<unknown>>;
|
|
586
908
|
//#endregion
|
|
587
|
-
//#region src/client/schema-types.d.ts
|
|
588
|
-
/**
|
|
589
|
-
* Pull each column's TS type and nullability into the row shape Kysely
|
|
590
|
-
* consumes as its `Database` interface.
|
|
591
|
-
*
|
|
592
|
-
* - Columns carrying the `GeneratedBrand` (set by serial / bigSerial /
|
|
593
|
-
* `default(...)` / `defaultNow()` / `defaultRandom()`) wrap in
|
|
594
|
-
* Kysely's `Generated<T>` so adopters can omit them on insert.
|
|
595
|
-
* - `notNull()` / `primaryKey()` stamp `NotNullBrand`, which drops the
|
|
596
|
-
* `| null` from the row type for that column.
|
|
597
|
-
* - `jsonb<{...}>()` carries the user-declared shape through without
|
|
598
|
-
* widening to `unknown`.
|
|
599
|
-
*
|
|
600
|
-
* The `Generated<T> | null` form for nullable + default columns models the
|
|
601
|
-
* SQL semantics: omitted on insert, the DB returns the default; if `null`
|
|
602
|
-
* is explicitly inserted, the DB stores null.
|
|
603
|
-
*/
|
|
604
|
-
type IsNullable<C> = C extends NotNullBrand ? false : true;
|
|
605
|
-
type ColumnTSType<C> = C extends ColumnBuilder<infer T> ? IsNullable<C> extends true ? C extends GeneratedBrand ? Generated<T> | null : T | null : C extends GeneratedBrand ? Generated<T> : T : never;
|
|
606
|
-
/**
|
|
607
|
-
* Table key Kysely sees. A table declared via `pgSchema('billing').table(...)`
|
|
608
|
-
* keys as `'billing.invoices'` — Kysely treats a dotted table name as
|
|
609
|
-
* schema-qualified, so `db.selectFrom('billing.invoices')` resolves without a
|
|
610
|
-
* `withSchema()` call. Unqualified tables keep their bare key, so existing
|
|
611
|
-
* `KickDbSchema['users']` lookups are unchanged.
|
|
612
|
-
*
|
|
613
|
-
* Matched on `__isTable` rather than on `TableDecl<...>` assignability: the
|
|
614
|
-
* schema generic makes a qualified table structurally incompatible with the
|
|
615
|
-
* unqualified default, which would silently drop it from the map.
|
|
616
|
-
*/
|
|
617
|
-
type TableKey<T> = T extends {
|
|
618
|
-
__name: infer N extends string;
|
|
619
|
-
} ? Extract<T extends {
|
|
620
|
-
__schema?: infer S;
|
|
621
|
-
} ? S : never, string> extends (infer Schema) ? [Schema] extends [never] ? N : Schema extends string ? `${Schema}.${N}` : N : never : never;
|
|
622
|
-
/** A schema-barrel export's table: itself, or a class form's `static table`. */
|
|
623
|
-
type TableOf<V> = V extends {
|
|
624
|
-
__isTable: true;
|
|
625
|
-
} ? V : V extends (abstract new (...args: never) => unknown) & {
|
|
626
|
-
table: infer T extends {
|
|
627
|
-
__isTable: true;
|
|
628
|
-
};
|
|
629
|
-
} ? T : never;
|
|
630
|
-
type SchemaToTypes<S> = { [K in keyof S as [TableOf<S[K]>] extends [never] ? never : TableKey<TableOf<S[K]>>]: TableOf<S[K]> extends TableDecl<string, infer C, string | undefined> ? { [Col in keyof C]: ColumnTSType<C[Col]>; } : never; };
|
|
631
|
-
//#endregion
|
|
632
909
|
//#region src/client/create.d.ts
|
|
633
910
|
declare function createDbClient<TSchema, DB = SchemaToTypes<TSchema>>(opts: CreateDbClientOptions<TSchema, DB>): KickDbClient<DB>;
|
|
634
911
|
//#endregion
|
|
@@ -675,7 +952,11 @@ declare function safeNullComparison(): KyselyPlugin;
|
|
|
675
952
|
//#region src/migrate/runner.d.ts
|
|
676
953
|
interface RunnerOptions {
|
|
677
954
|
adapter: MigrationAdapter;
|
|
678
|
-
|
|
955
|
+
/**
|
|
956
|
+
* The migrations folder — or several, run as one history ordered by
|
|
957
|
+
* migration id. Each keeps its own journal and snapshots.
|
|
958
|
+
*/
|
|
959
|
+
migrationsDir: string | readonly string[];
|
|
679
960
|
/** When true, refuse to apply migrations whose meta.json.reviewed is false. Defaults to true outside dev. */
|
|
680
961
|
requireReviewed?: boolean;
|
|
681
962
|
/** Owner string written into the lock table for diagnostics. */
|
|
@@ -695,11 +976,26 @@ interface AppliedSummary {
|
|
|
695
976
|
batch: number | null;
|
|
696
977
|
}
|
|
697
978
|
declare function migrateLatest(opts: RunnerOptions): Promise<AppliedSummary>;
|
|
698
|
-
|
|
979
|
+
/**
|
|
980
|
+
* Apply the next pending migration — or, with `to`, every pending one up to
|
|
981
|
+
* and including that migration.
|
|
982
|
+
*/
|
|
983
|
+
declare function migrateUp(opts: RunnerOptions & {
|
|
984
|
+
to?: string;
|
|
985
|
+
}): Promise<AppliedSummary>;
|
|
699
986
|
interface ReversedSummary {
|
|
987
|
+
/** The last migration reversed, or null when there was none. */
|
|
700
988
|
reversed: string | null;
|
|
989
|
+
/** Every migration reversed, in the order it happened. */
|
|
990
|
+
reversedAll: string[];
|
|
701
991
|
}
|
|
702
|
-
|
|
992
|
+
/**
|
|
993
|
+
* Reverse the most recent migration — or, with `to`, every one applied after
|
|
994
|
+
* that migration, which stays applied.
|
|
995
|
+
*/
|
|
996
|
+
declare function migrateDown(opts: RunnerOptions & {
|
|
997
|
+
to?: string;
|
|
998
|
+
}): Promise<ReversedSummary>;
|
|
703
999
|
interface RollbackSummary {
|
|
704
1000
|
reversed: string[];
|
|
705
1001
|
batch: number | null;
|
|
@@ -714,24 +1010,61 @@ interface StatusEntry {
|
|
|
714
1010
|
reviewed: boolean;
|
|
715
1011
|
}
|
|
716
1012
|
declare function migrateStatus(opts: Pick<RunnerOptions, 'adapter' | 'migrationsDir'>): Promise<StatusEntry[]>;
|
|
717
|
-
|
|
1013
|
+
/** Reverse the last batch — or, with `all`, every applied migration. */
|
|
1014
|
+
declare function migrateRollback(opts: RunnerOptions & {
|
|
1015
|
+
all?: boolean;
|
|
1016
|
+
}): Promise<RollbackSummary>;
|
|
1017
|
+
//#endregion
|
|
1018
|
+
//#region src/migrate/tenants.d.ts
|
|
1019
|
+
interface MigrateTenantsOptions extends Omit<RunnerOptions, 'adapter'> {
|
|
1020
|
+
/** The tenants to migrate, or a function returning them (read from the central database). */
|
|
1021
|
+
tenants: readonly string[] | (() => readonly string[] | Promise<readonly string[]>);
|
|
1022
|
+
/**
|
|
1023
|
+
* The migration adapter for one tenant: its database (`'database'`), or a
|
|
1024
|
+
* connection whose `search_path` is its schema (`'schema'`). Closed after
|
|
1025
|
+
* that tenant is migrated.
|
|
1026
|
+
*/
|
|
1027
|
+
adapterFor: (tenantId: string) => MigrationAdapter | Promise<MigrationAdapter>;
|
|
1028
|
+
/** Tenants migrated at once. Default 1. */
|
|
1029
|
+
concurrency?: number;
|
|
1030
|
+
/** Stop at the first failure. Default false: migrate the rest and report every failure. */
|
|
1031
|
+
stopOnError?: boolean;
|
|
1032
|
+
/** Called as each tenant finishes. */
|
|
1033
|
+
onTenant?: (result: TenantMigrationResult) => void;
|
|
1034
|
+
}
|
|
1035
|
+
interface TenantMigrationResult {
|
|
1036
|
+
tenant: string;
|
|
1037
|
+
/** What was applied, when it succeeded. */
|
|
1038
|
+
summary?: AppliedSummary;
|
|
1039
|
+
error?: unknown;
|
|
1040
|
+
}
|
|
1041
|
+
interface MigrateTenantsResult {
|
|
1042
|
+
results: TenantMigrationResult[];
|
|
1043
|
+
/** The tenants whose migration failed. */
|
|
1044
|
+
failed: string[];
|
|
1045
|
+
}
|
|
1046
|
+
/**
|
|
1047
|
+
* Run the same migrations for every tenant — schema- or database-per-tenant.
|
|
1048
|
+
* Each tenant keeps its own `kick_migrations`, so a tenant added later (or
|
|
1049
|
+
* one that failed) catches up on the next run.
|
|
1050
|
+
*/
|
|
1051
|
+
declare function migrateTenants(opts: MigrateTenantsOptions): Promise<MigrateTenantsResult>;
|
|
718
1052
|
//#endregion
|
|
719
1053
|
//#region src/migrate/review.d.ts
|
|
720
1054
|
interface ReviewResult {
|
|
721
1055
|
id: string;
|
|
722
|
-
/** True when the migration was already reviewed
|
|
1056
|
+
/** True when the migration was already reviewed — its hash is re-recorded. */
|
|
723
1057
|
alreadyReviewed: boolean;
|
|
724
1058
|
}
|
|
725
1059
|
/**
|
|
726
1060
|
* Mark a migration as reviewed: flip `meta.json.reviewed` to `true` —
|
|
727
|
-
* the
|
|
728
|
-
*
|
|
729
|
-
*
|
|
1061
|
+
* the review state the runner checks — and record the hash of the files
|
|
1062
|
+
* as reviewed in the journal, so hand-written or edited SQL applies and a
|
|
1063
|
+
* later edit doesn't.
|
|
730
1064
|
*
|
|
731
|
-
* Legacy migrations (generated before the banner) still carry
|
|
732
|
-
* `-- REVIEWED: false` markers inside the hashed files;
|
|
733
|
-
*
|
|
734
|
-
* hash so all three stay in sync.
|
|
1065
|
+
* Legacy migrations (generated before the provenance banner) still carry
|
|
1066
|
+
* `-- REVIEWED: false` markers inside the hashed files; those are swapped
|
|
1067
|
+
* first, so the recorded hash covers them.
|
|
735
1068
|
*/
|
|
736
1069
|
declare function reviewMigration(migrationsDir: string, id: string): Promise<ReviewResult>;
|
|
737
1070
|
//#endregion
|
|
@@ -791,38 +1124,6 @@ declare function emitSqlite(changes: ChangeSet, ctx?: SqliteEmitContext): string
|
|
|
791
1124
|
*/
|
|
792
1125
|
declare function emitMysql(changes: ChangeSet): string;
|
|
793
1126
|
//#endregion
|
|
794
|
-
//#region src/cli/config.d.ts
|
|
795
|
-
type MigrationAdapterFactory = () => MigrationAdapter | Promise<MigrationAdapter>;
|
|
796
|
-
interface DbConfig {
|
|
797
|
-
schemaPath: string;
|
|
798
|
-
migrationsDir: string;
|
|
799
|
-
dialect: Dialect$1;
|
|
800
|
-
/**
|
|
801
|
-
* How `kick db migrate` reacts when the live DB has schema not recorded
|
|
802
|
-
* in the migrations (someone ran DDL out of band): `'error'` (default —
|
|
803
|
-
* refuse), `'warn'` (log + continue), `'ignore'` (skip the check). The
|
|
804
|
-
* check is dialect-normalised, so SQLite/MySQL's lossy introspection
|
|
805
|
-
* doesn't false-positive.
|
|
806
|
-
*/
|
|
807
|
-
driftCheck?: DriftBehavior;
|
|
808
|
-
/**
|
|
809
|
-
* Postgres connection string for the built-in pgAdapter path. Read from
|
|
810
|
-
* `db.connectionString` in kick.config.ts, or falls back to the
|
|
811
|
-
* DATABASE_URL env var. The CLI uses this when no `adapter` factory is
|
|
812
|
-
* provided.
|
|
813
|
-
*/
|
|
814
|
-
connectionString?: string;
|
|
815
|
-
/**
|
|
816
|
-
* Escape hatch: a factory returning a fully-constructed MigrationAdapter.
|
|
817
|
-
* Takes precedence over `connectionString` when both are set. Use this
|
|
818
|
-
* for non-default adapter wiring (custom pool, neon-serverless, etc).
|
|
819
|
-
*/
|
|
820
|
-
adapter?: MigrationAdapterFactory;
|
|
821
|
-
}
|
|
822
|
-
declare function resolveDbConfig(opts: {
|
|
823
|
-
configPath: string;
|
|
824
|
-
}): Promise<DbConfig>;
|
|
825
|
-
//#endregion
|
|
826
1127
|
//#region src/cli/generate.d.ts
|
|
827
1128
|
interface GenerateOptions {
|
|
828
1129
|
name: string;
|
|
@@ -836,6 +1137,12 @@ interface GenerateOptions {
|
|
|
836
1137
|
* change the diff engine can't author. Matches knex's `migrate:make`.
|
|
837
1138
|
*/
|
|
838
1139
|
empty?: boolean;
|
|
1140
|
+
/**
|
|
1141
|
+
* Write the migration in TypeScript: a `migration.ts` exporting
|
|
1142
|
+
* `up(db)` / `down(db)` instead of SQL, for data changes that need code.
|
|
1143
|
+
* Like `empty`, the schema diff is skipped and the snapshot carried over.
|
|
1144
|
+
*/
|
|
1145
|
+
typescript?: boolean;
|
|
839
1146
|
/**
|
|
840
1147
|
* M4.C — generate-time gate for `removeEnumValue` changes. When the
|
|
841
1148
|
* diff produces one or more, this callback is invoked once per
|
|
@@ -847,6 +1154,25 @@ interface GenerateOptions {
|
|
|
847
1154
|
* required). The CLI wires this for `dialect=postgres` workflows.
|
|
848
1155
|
*/
|
|
849
1156
|
detectCompositeRefs?: (enumName: string) => Promise<readonly CompositeRef[]>;
|
|
1157
|
+
/** Renames known up front — `--rename-table` / `--rename-column`. */
|
|
1158
|
+
renames?: RenameHints;
|
|
1159
|
+
/**
|
|
1160
|
+
* Asked which dropped tables and columns are really renames, when the diff
|
|
1161
|
+
* has a drop and an add that could be one. Called first with table
|
|
1162
|
+
* candidates, then with column candidates (inside renamed tables too). What
|
|
1163
|
+
* it doesn't name is dropped. Without it, only `renames` and the
|
|
1164
|
+
* one-drop-one-add guess pair them.
|
|
1165
|
+
*/
|
|
1166
|
+
askRenames?: (candidates: RenameCandidates) => Promise<RenameHints>;
|
|
1167
|
+
/**
|
|
1168
|
+
* Told about each table or column the migration drops that could have been
|
|
1169
|
+
* a rename, when `askRenames` isn't given — so a non-interactive run can
|
|
1170
|
+
* still warn. `flag` is the `--rename-…` that would keep it.
|
|
1171
|
+
*/
|
|
1172
|
+
onPossibleRename?: (drop: {
|
|
1173
|
+
what: string;
|
|
1174
|
+
flag: string;
|
|
1175
|
+
}) => void;
|
|
850
1176
|
}
|
|
851
1177
|
interface GenerateResult {
|
|
852
1178
|
status: 'created' | 'no-changes';
|
|
@@ -856,15 +1182,98 @@ interface GenerateResult {
|
|
|
856
1182
|
}
|
|
857
1183
|
declare function generate(opts: GenerateOptions): Promise<GenerateResult>;
|
|
858
1184
|
//#endregion
|
|
1185
|
+
//#region src/migrate/code-migration.d.ts
|
|
1186
|
+
/** What a migration written in TypeScript runs with: Kysely on the migration's transaction. */
|
|
1187
|
+
type MigrationDb = Kysely<any>;
|
|
1188
|
+
/** A migration's code, from its `migration.ts`. */
|
|
1189
|
+
interface CodeMigration {
|
|
1190
|
+
up(db: MigrationDb): Promise<void>;
|
|
1191
|
+
down?(db: MigrationDb): Promise<void>;
|
|
1192
|
+
}
|
|
1193
|
+
//#endregion
|
|
1194
|
+
//#region src/cli/check.d.ts
|
|
1195
|
+
interface CheckResult {
|
|
1196
|
+
/** Changes in the schema that no migration covers yet — run `kick db generate`. */
|
|
1197
|
+
unmigratedChanges: number;
|
|
1198
|
+
/** Migrations not marked reviewed — the runner refuses them outside development. */
|
|
1199
|
+
unreviewed: string[];
|
|
1200
|
+
/** Reviewed migrations whose files changed after review — the runner refuses them. */
|
|
1201
|
+
modified: string[];
|
|
1202
|
+
ok: boolean;
|
|
1203
|
+
}
|
|
1204
|
+
/**
|
|
1205
|
+
* Everything `migrate latest` would refuse, found without a database — for
|
|
1206
|
+
* CI, before a deploy reaches one: the schema has changes no migration
|
|
1207
|
+
* covers, a migration is unreviewed, or a migration was edited after review.
|
|
1208
|
+
*/
|
|
1209
|
+
declare function checkMigrations(opts: {
|
|
1210
|
+
config: DbConfig;
|
|
1211
|
+
cwd: string;
|
|
1212
|
+
}): Promise<CheckResult>;
|
|
1213
|
+
//#endregion
|
|
1214
|
+
//#region src/cli/seed.d.ts
|
|
1215
|
+
interface SeedResult {
|
|
1216
|
+
/** The seed files run, in order. */
|
|
1217
|
+
ran: string[];
|
|
1218
|
+
}
|
|
1219
|
+
/** The seed files in `dir`, sorted by name — prefix them (`01_roles.ts`) to order them. */
|
|
1220
|
+
declare function listSeeds(dir: string): Promise<string[]>;
|
|
1221
|
+
/**
|
|
1222
|
+
* Run every seed in `dir`, or only `names` (file names, with or without the
|
|
1223
|
+
* extension), in name order. A seed that throws stops the run: the error
|
|
1224
|
+
* names the file and keeps the original as `cause`.
|
|
1225
|
+
*/
|
|
1226
|
+
declare function runSeeds(opts: {
|
|
1227
|
+
dir: string;
|
|
1228
|
+
names?: string[];
|
|
1229
|
+
}): Promise<SeedResult>;
|
|
1230
|
+
//#endregion
|
|
859
1231
|
//#region src/dsl/columns/builders.d.ts
|
|
860
1232
|
declare function serial(): ColumnBuilder<number> & GeneratedBrand & NotNullBrand;
|
|
1233
|
+
/** How `bigint` / `numeric` values are read back, and the type they get. */
|
|
1234
|
+
interface NumberModes {
|
|
1235
|
+
bigint: bigint;
|
|
1236
|
+
number: number;
|
|
1237
|
+
string: string;
|
|
1238
|
+
}
|
|
861
1239
|
declare function bigSerial(): ColumnBuilder<bigint> & GeneratedBrand & NotNullBrand;
|
|
862
1240
|
declare function smallSerial(): ColumnBuilder<number> & GeneratedBrand & NotNullBrand;
|
|
863
1241
|
declare function integer(): ColumnBuilder<number>;
|
|
1242
|
+
/**
|
|
1243
|
+
* A 64-bit integer. Drivers return it differently (`pg` a string,
|
|
1244
|
+
* better-sqlite3 a number), so pick how it reads back with `mode`:
|
|
1245
|
+
* `'bigint'` (exact), `'number'` (safe up to 2^53) or `'string'`. Without
|
|
1246
|
+
* `mode` the driver's value is returned, typed `bigint`.
|
|
1247
|
+
*/
|
|
864
1248
|
declare function bigint(): ColumnBuilder<bigint>;
|
|
1249
|
+
declare function bigint<M extends keyof NumberModes>(options: {
|
|
1250
|
+
mode: M;
|
|
1251
|
+
}): ColumnBuilder<NumberModes[M]>;
|
|
865
1252
|
declare function smallint(): ColumnBuilder<number>;
|
|
1253
|
+
/**
|
|
1254
|
+
* An optimistic-locking counter: an integer, not null, starting at 0, that
|
|
1255
|
+
* every update increments. Read it with the row, then update
|
|
1256
|
+
* `.where('version', '=', read)` — no row updated means someone else changed
|
|
1257
|
+
* it first.
|
|
1258
|
+
*/
|
|
1259
|
+
declare function version(): ColumnBuilder<number> & NotNullBrand & GeneratedBrand;
|
|
1260
|
+
type DecimalMode = {
|
|
1261
|
+
mode: 'number' | 'string';
|
|
1262
|
+
};
|
|
1263
|
+
/**
|
|
1264
|
+
* An exact decimal, read back as a string by default so no precision is lost.
|
|
1265
|
+
* `{ mode: 'number' }` reads it as a JS number: exact up to 15 significant
|
|
1266
|
+
* digits, which validators enforce on input (more is refused, not rounded).
|
|
1267
|
+
*/
|
|
866
1268
|
declare function decimal(precision?: number, scale?: number): ColumnBuilder<string>;
|
|
1269
|
+
declare function decimal<M extends DecimalMode['mode']>(precision: number | undefined, scale: number | undefined, options: {
|
|
1270
|
+
mode: M;
|
|
1271
|
+
}): ColumnBuilder<NumberModes[M]>;
|
|
1272
|
+
/** Same as {@link decimal}. */
|
|
867
1273
|
declare function numeric(precision?: number, scale?: number): ColumnBuilder<string>;
|
|
1274
|
+
declare function numeric<M extends DecimalMode['mode']>(precision: number | undefined, scale: number | undefined, options: {
|
|
1275
|
+
mode: M;
|
|
1276
|
+
}): ColumnBuilder<NumberModes[M]>;
|
|
868
1277
|
declare function real(): ColumnBuilder<number>;
|
|
869
1278
|
declare function doublePrecision(): ColumnBuilder<number>;
|
|
870
1279
|
declare function varchar(length?: number): ColumnBuilder<string>;
|
|
@@ -910,12 +1319,54 @@ declare function json<T = unknown>(): ColumnBuilder<T>;
|
|
|
910
1319
|
declare function jsonb<T = unknown>(): ColumnBuilder<T>;
|
|
911
1320
|
declare function bytea(): ColumnBuilder<Uint8Array>;
|
|
912
1321
|
//#endregion
|
|
1322
|
+
//#region src/dsl/view.d.ts
|
|
1323
|
+
/** What makes a table declaration a view: its SQL, and whether it's materialized. */
|
|
1324
|
+
interface ViewMarks {
|
|
1325
|
+
__isView: true;
|
|
1326
|
+
/** The `SELECT` the view is defined as, passed to the database as written. */
|
|
1327
|
+
__definition: string;
|
|
1328
|
+
__materialized: boolean;
|
|
1329
|
+
}
|
|
1330
|
+
type ViewDecl<TName extends string = string, C extends Record<string, ColumnBuilder> = Record<string, ColumnBuilder>, TSchema extends string | undefined = string | undefined> = TableDecl<TName, C, TSchema> & ViewMarks;
|
|
1331
|
+
interface ViewOptions {
|
|
1332
|
+
/** The `SELECT` the view is defined as, in your database's SQL. */
|
|
1333
|
+
as: string;
|
|
1334
|
+
}
|
|
1335
|
+
interface MaterializedViewOptions<C extends Record<string, ColumnBuilder>> extends ViewOptions {
|
|
1336
|
+
/**
|
|
1337
|
+
* Indexes on the materialized view — a unique one lets
|
|
1338
|
+
* `refreshMaterializedView(name, { concurrently: true })` run without
|
|
1339
|
+
* blocking reads.
|
|
1340
|
+
*/
|
|
1341
|
+
constraints?: (refs: TypedColumnRefs<C>) => Record<string, IndexDecl>;
|
|
1342
|
+
}
|
|
1343
|
+
/** @internal Shared by `view()` and `materializedView()`. */
|
|
1344
|
+
declare function buildView<TName extends string, C extends Record<string, ColumnBuilder>, TSchema extends string | undefined>(name: TName, columns: C, definition: string, materialized: boolean, constraints: ((refs: TypedColumnRefs<C>) => Record<string, IndexDecl>) | undefined, schema: TSchema): ViewDecl<TName, C, TSchema> & TypedColumnRefs<C>;
|
|
1345
|
+
/**
|
|
1346
|
+
* A view: a stored `SELECT` you query like a table. The columns declare what
|
|
1347
|
+
* it returns, for the typed client — they aren't checked against the SQL.
|
|
1348
|
+
*
|
|
1349
|
+
* ```ts
|
|
1350
|
+
* export const activeUsers = view(
|
|
1351
|
+
* 'active_users',
|
|
1352
|
+
* { id: integer().notNull(), email: text().notNull() },
|
|
1353
|
+
* { as: 'SELECT id, email FROM users WHERE deleted_at IS NULL' },
|
|
1354
|
+
* )
|
|
1355
|
+
* ```
|
|
1356
|
+
*
|
|
1357
|
+
* Migrations create it after the tables and drop it before them, and drop and
|
|
1358
|
+
* re-create it around a change to a table its SQL names.
|
|
1359
|
+
*/
|
|
1360
|
+
declare function view<TName extends string, C extends Record<string, ColumnBuilder>>(name: TName, columns: C, options: ViewOptions): ViewDecl<TName, C, undefined> & TypedColumnRefs<C>;
|
|
1361
|
+
/** Whether a declaration is a view. */
|
|
1362
|
+
declare function isView(value: unknown): value is ViewDecl;
|
|
1363
|
+
//#endregion
|
|
913
1364
|
//#region src/dsl/self-ref.d.ts
|
|
914
1365
|
declare function selfRef(column: string): () => ColumnRef;
|
|
915
1366
|
//#endregion
|
|
916
1367
|
//#region src/dsl/table-forms.d.ts
|
|
917
1368
|
type ColumnsRecord = Record<string, ColumnBuilder>;
|
|
918
|
-
type Constraints = (refs: never) => Record<string,
|
|
1369
|
+
type Constraints = (refs: never) => Record<string, TableConstraint>;
|
|
919
1370
|
type Rules = Record<string, ColumnRule | SchemaLike>;
|
|
920
1371
|
/** The Postgres schema of a table: `undefined` for none or `public`. */
|
|
921
1372
|
type SchemaOf<S> = S extends string ? (S extends 'public' ? undefined : `${S}`) : undefined;
|
|
@@ -934,8 +1385,8 @@ interface TableClass {
|
|
|
934
1385
|
readonly tableName: string;
|
|
935
1386
|
/** Postgres schema the table lives in — `pgSchema(schema).table(...)`. */
|
|
936
1387
|
readonly schema?: string;
|
|
937
|
-
/** Indexes
|
|
938
|
-
readonly indexes?: (refs: never) => Record<string,
|
|
1388
|
+
/** Indexes, unique constraints, `primaryKey()` and `check()`, over {@link ClassRefs} of the class. */
|
|
1389
|
+
readonly indexes?: (refs: never) => Record<string, TableConstraint>;
|
|
939
1390
|
}
|
|
940
1391
|
/** Column refs of a builder-field class, for its `static indexes`. */
|
|
941
1392
|
type ClassRefs<C extends new () => object> = TypedColumnRefs<BuilderFields<InstanceType<C>>>;
|
|
@@ -965,7 +1416,7 @@ type RowOf<C extends ColumnsRecord> = { [K in keyof C]: C[K] extends ColumnBuild
|
|
|
965
1416
|
declare function TableBase<const N extends string, C extends ColumnsRecord, const S extends string | undefined = undefined>(name: N, columns: C, options?: {
|
|
966
1417
|
schema?: S;
|
|
967
1418
|
rules?: { [K in keyof C]?: RuleFor<C[K]>; };
|
|
968
|
-
indexes?: (refs: TypedColumnRefs<C>) => Record<string,
|
|
1419
|
+
indexes?: (refs: TypedColumnRefs<C>) => Record<string, TableConstraint>;
|
|
969
1420
|
}): (abstract new () => RowOf<C>) & {
|
|
970
1421
|
readonly table: TableDecl<N, C, SchemaOf<S>> & TypedColumnRefs<C>;
|
|
971
1422
|
from<T>(this: new () => T, row: RowOf<C>): T;
|
|
@@ -992,7 +1443,7 @@ declare class TableDefinition<N extends string, C extends ColumnsRecord, S exten
|
|
|
992
1443
|
*/
|
|
993
1444
|
column<const K extends string, B extends ColumnBuilder>(key: K extends keyof C ? never : K, builder: B | ((refs: TypedColumnRefs<C>) => B), rule?: RuleFor<B>): TableDefinition<N, C & { [P in K]: B; }, S>;
|
|
994
1445
|
/** Indexes / unique constraints over the columns declared so far. Calls add up. */
|
|
995
|
-
index(constraints: (refs: TypedColumnRefs<C>) => Record<string,
|
|
1446
|
+
index(constraints: (refs: TypedColumnRefs<C>) => Record<string, TableConstraint>): TableDefinition<N, C, S>;
|
|
996
1447
|
build(): TableDecl<N, C, SchemaOf<S>> & TypedColumnRefs<C>;
|
|
997
1448
|
/**
|
|
998
1449
|
* Refs for `.column(key, (t) => ...)` callbacks. The table doesn't exist
|
|
@@ -1027,6 +1478,63 @@ declare function fk<T, B extends ColumnBuilder<T>>(builder: B & ColumnBuilder<T>
|
|
|
1027
1478
|
*/
|
|
1028
1479
|
declare function link<T>(column: TypedColumnRef<T>, target: () => TypedColumnRef<NoInfer<T>>, options?: Parameters<ColumnBuilder['references']>[1]): void;
|
|
1029
1480
|
//#endregion
|
|
1481
|
+
//#region src/dsl/alias.d.ts
|
|
1482
|
+
type Qualified<TName extends string, TSchema> = TSchema extends string ? `${TSchema}.${TName}` : TName;
|
|
1483
|
+
/** A table under a second name: its columns, plus `$from` for `selectFrom` / joins. */
|
|
1484
|
+
type AliasedTable<TName extends string, C extends Record<string, ColumnBuilder>, TSchema extends string | undefined, A extends string> = TypedColumnRefs<C> & {
|
|
1485
|
+
/** `'<table> as <alias>'` — what `selectFrom` and the joins take. */
|
|
1486
|
+
readonly $from: `${Qualified<TName, TSchema>} as ${A}`;
|
|
1487
|
+
};
|
|
1488
|
+
/**
|
|
1489
|
+
* The same table under another name, for self-joins and reading a table twice.
|
|
1490
|
+
* Its columns work with the condition helpers:
|
|
1491
|
+
*
|
|
1492
|
+
* const manager = alias(users, 'manager')
|
|
1493
|
+
* db.selectFrom('users')
|
|
1494
|
+
* .innerJoin(manager.$from, (j) => j.on(eq(manager.id, users.managerId)))
|
|
1495
|
+
* .select(['users.name', 'manager.name as managerName'])
|
|
1496
|
+
*/
|
|
1497
|
+
declare function alias<TName extends string, C extends Record<string, ColumnBuilder>, TSchema extends string | undefined, A extends string>(table: TableDecl<TName, C, TSchema>, name: A): AliasedTable<TName, C, TSchema, A>;
|
|
1498
|
+
//#endregion
|
|
1499
|
+
//#region src/query/operators.d.ts
|
|
1500
|
+
/** The value type an operand stands for. */
|
|
1501
|
+
type ValueOf<O> = O extends TypedColumnRef<infer T> ? T : O extends Expression<infer T> ? T : O;
|
|
1502
|
+
/** What may sit across from `O`: a value of its type, or anything standing for one. */
|
|
1503
|
+
type Comparable<O> = Operand<SelectType<ValueOf<O>>>;
|
|
1504
|
+
/** A column, a Kysely expression, or a value. */
|
|
1505
|
+
type Operand<T = unknown> = TypedColumnRef<T> | Expression<T> | T;
|
|
1506
|
+
type Condition = RawBuilder<SqlBool>;
|
|
1507
|
+
declare const eq: <L>(left: L, right: Comparable<L>) => Condition;
|
|
1508
|
+
declare const ne: <L>(left: L, right: Comparable<L>) => Condition;
|
|
1509
|
+
declare const gt: <L>(left: L, right: Comparable<L>) => Condition;
|
|
1510
|
+
declare const gte: <L>(left: L, right: Comparable<L>) => Condition;
|
|
1511
|
+
declare const lt: <L>(left: L, right: Comparable<L>) => Condition;
|
|
1512
|
+
declare const lte: <L>(left: L, right: Comparable<L>) => Condition;
|
|
1513
|
+
/** `left LIKE pattern` — escape user input with `escapeLike()`. */
|
|
1514
|
+
declare const like: <L>(left: L, pattern: Operand<string>) => Condition;
|
|
1515
|
+
declare const notLike: <L>(left: L, pattern: Operand<string>) => Condition;
|
|
1516
|
+
/** Case-insensitive `LIKE` (Postgres). */
|
|
1517
|
+
declare const ilike: <L>(left: L, pattern: Operand<string>) => Condition;
|
|
1518
|
+
declare const isNull: (operand: unknown) => Condition;
|
|
1519
|
+
declare const isNotNull: (operand: unknown) => Condition;
|
|
1520
|
+
/** `left IN (…)`. An empty list matches nothing, rather than being invalid SQL. */
|
|
1521
|
+
declare function inArray<L>(left: L, values: readonly Comparable<L>[]): Condition;
|
|
1522
|
+
/** `left NOT IN (…)`. An empty list matches everything. */
|
|
1523
|
+
declare function notInArray<L>(left: L, values: readonly Comparable<L>[]): Condition;
|
|
1524
|
+
declare const between: <L>(left: L, low: Comparable<L>, high: Comparable<L>) => Condition;
|
|
1525
|
+
/**
|
|
1526
|
+
* All of the conditions. `undefined` entries are skipped, so a filter can be
|
|
1527
|
+
* built conditionally: `and(eq(t.a, a), b ? eq(t.b, b) : undefined)`. With
|
|
1528
|
+
* none left it matches every row.
|
|
1529
|
+
*/
|
|
1530
|
+
declare function and(...conditions: (Expression<SqlBool> | undefined)[]): Condition;
|
|
1531
|
+
/** Any of the conditions; `undefined` entries are skipped. With none left it matches no row. */
|
|
1532
|
+
declare function or(...conditions: (Expression<SqlBool> | undefined)[]): Condition;
|
|
1533
|
+
declare const not: (condition: Expression<SqlBool>) => Condition;
|
|
1534
|
+
/** `EXISTS (subquery)` — pass a Kysely select; it brings its own parentheses. */
|
|
1535
|
+
declare const exists: (subquery: Expression<unknown>) => Condition;
|
|
1536
|
+
declare const notExists: (subquery: Expression<unknown>) => Condition;
|
|
1537
|
+
//#endregion
|
|
1030
1538
|
//#region src/dsl/relations.d.ts
|
|
1031
1539
|
/**
|
|
1032
1540
|
* Generic over the target table so the typegen plugin can pull
|
|
@@ -1049,6 +1557,13 @@ interface RelationOne<TTarget extends TableDecl<string, Record<string, ColumnBui
|
|
|
1049
1557
|
interface RelationMany<TTarget extends TableDecl<string, Record<string, ColumnBuilder>> = TableDecl<string, Record<string, ColumnBuilder>>> {
|
|
1050
1558
|
kind: 'many';
|
|
1051
1559
|
target: TTarget;
|
|
1560
|
+
/**
|
|
1561
|
+
* A many-to-many through a junction table: `many(tags, { through: postTags })`.
|
|
1562
|
+
* The junction's foreign keys to each side decide the join; when it has
|
|
1563
|
+
* more than one to a side (a self-referencing `follows`), name them:
|
|
1564
|
+
* `{ table: follows, from: [follows.followerId], to: [follows.followeeId] }`.
|
|
1565
|
+
*/
|
|
1566
|
+
through?: ThroughSpec;
|
|
1052
1567
|
/**
|
|
1053
1568
|
* Pairs with the matching `relationName` on the inverse `one`
|
|
1054
1569
|
* declaration. Required when the source table has multiple FKs
|
|
@@ -1057,6 +1572,11 @@ interface RelationMany<TTarget extends TableDecl<string, Record<string, ColumnBu
|
|
|
1057
1572
|
*/
|
|
1058
1573
|
relationName?: string;
|
|
1059
1574
|
}
|
|
1575
|
+
type ThroughSpec = TableDecl<string, Record<string, ColumnBuilder>> | {
|
|
1576
|
+
table: TableDecl<string, Record<string, ColumnBuilder>>;
|
|
1577
|
+
from: ColumnRef[];
|
|
1578
|
+
to: ColumnRef[];
|
|
1579
|
+
};
|
|
1060
1580
|
type Relation = RelationOne | RelationMany;
|
|
1061
1581
|
/**
|
|
1062
1582
|
* Generic so the typegen plugin can read the source table name and
|
|
@@ -1077,6 +1597,7 @@ interface Helpers {
|
|
|
1077
1597
|
}) => RelationOne<T>;
|
|
1078
1598
|
many: <T extends TableDecl<string, Record<string, ColumnBuilder>>>(target: T, opts?: {
|
|
1079
1599
|
relationName?: string;
|
|
1600
|
+
through?: ThroughSpec;
|
|
1080
1601
|
}) => RelationMany<T>;
|
|
1081
1602
|
}
|
|
1082
1603
|
/**
|
|
@@ -1139,15 +1660,6 @@ declare class CustomColumnBuilder<TJs> extends ColumnBuilder<TJs> {
|
|
|
1139
1660
|
*/
|
|
1140
1661
|
declare function customType<TJs>(opts: CustomTypeOptions<TJs>): () => CustomColumnBuilder<TJs>;
|
|
1141
1662
|
//#endregion
|
|
1142
|
-
//#region src/query/relations.d.ts
|
|
1143
|
-
type ResolvedRelation = RelationSnapshot;
|
|
1144
|
-
/**
|
|
1145
|
-
* Sidecar map: source table → relation name → resolved entry. Lives
|
|
1146
|
-
* on `SchemaSnapshot.relations` and is populated by
|
|
1147
|
-
* `extractRelations()` (`query/extract-relations.ts`).
|
|
1148
|
-
*/
|
|
1149
|
-
type ResolvedRelations = Record<string, Record<string, ResolvedRelation>>;
|
|
1150
|
-
//#endregion
|
|
1151
1663
|
//#region src/query/schema-relations-types.d.ts
|
|
1152
1664
|
/**
|
|
1153
1665
|
* Distribute over `S` (the schema record), keeping only the entries
|
|
@@ -1265,6 +1777,17 @@ declare class RelationalQueryMissingInverseError extends KickDbError {
|
|
|
1265
1777
|
readonly targetTable: string;
|
|
1266
1778
|
constructor(sourceTable: string, relationName: string, targetTable: string);
|
|
1267
1779
|
}
|
|
1780
|
+
/**
|
|
1781
|
+
* Thrown when a `many(target, { through })` relation can't be resolved: the
|
|
1782
|
+
* junction table doesn't have exactly one foreign key to each side (or the
|
|
1783
|
+
* columns given for `from` / `to` aren't a foreign key to that side).
|
|
1784
|
+
*/
|
|
1785
|
+
declare class RelationalQueryThroughError extends KickDbError {
|
|
1786
|
+
readonly sourceTable: string;
|
|
1787
|
+
readonly relationName: string;
|
|
1788
|
+
readonly junction: string;
|
|
1789
|
+
constructor(sourceTable: string, relationName: string, junction: string, problem: string);
|
|
1790
|
+
}
|
|
1268
1791
|
//#endregion
|
|
1269
1792
|
//#region src/query/like.d.ts
|
|
1270
1793
|
/**
|
|
@@ -1278,10 +1801,9 @@ declare class RelationalQueryMissingInverseError extends KickDbError {
|
|
|
1278
1801
|
* literally.
|
|
1279
1802
|
*
|
|
1280
1803
|
* Escapes `%`, `_`, and the escape character itself. The default escape
|
|
1281
|
-
* char is backslash, which Postgres and
|
|
1282
|
-
*
|
|
1283
|
-
*
|
|
1284
|
-
* it explicit.
|
|
1804
|
+
* char is backslash, which Postgres and MySQL use by default. SQLite has
|
|
1805
|
+
* no default escape character — add `ESCAPE '\'` to the LIKE there, or
|
|
1806
|
+
* the escapes are matched as literal backslashes.
|
|
1285
1807
|
*/
|
|
1286
1808
|
type LikeMatchMode = 'contains' | 'startsWith' | 'endsWith' | 'exact';
|
|
1287
1809
|
/**
|
|
@@ -1307,6 +1829,19 @@ declare function escapeLike(input: string, escapeChar?: string): string;
|
|
|
1307
1829
|
*/
|
|
1308
1830
|
declare function likePattern(input: string, mode?: LikeMatchMode, escapeChar?: string): string;
|
|
1309
1831
|
//#endregion
|
|
1832
|
+
//#region src/query/order.d.ts
|
|
1833
|
+
/**
|
|
1834
|
+
* Sort direction for a relational `orderBy`, which takes expressions:
|
|
1835
|
+
*
|
|
1836
|
+
* orderBy: (p, eb) => desc(eb.ref('publishedAt'))
|
|
1837
|
+
* orderBy: (p, eb) => [desc(eb.ref('priority')), asc(eb.ref('title'))]
|
|
1838
|
+
*
|
|
1839
|
+
* Works at the top level and inside `with`, on every dialect.
|
|
1840
|
+
*/
|
|
1841
|
+
declare function desc<T>(expression: Expression<T>): Expression<T>;
|
|
1842
|
+
/** Ascending order — the default, spelled out. See {@link desc}. */
|
|
1843
|
+
declare function asc<T>(expression: Expression<T>): Expression<T>;
|
|
1844
|
+
//#endregion
|
|
1310
1845
|
//#region src/dialect-marker.d.ts
|
|
1311
1846
|
/**
|
|
1312
1847
|
* Explicit dialect tagging for `createDbClient`'s dialect detection.
|
|
@@ -1339,5 +1874,5 @@ declare function markDialect<T extends object>(dialect: T, tag: DialectTag): T;
|
|
|
1339
1874
|
*/
|
|
1340
1875
|
declare function readDialectMark(dialect: object): DialectTag | undefined;
|
|
1341
1876
|
//#endregion
|
|
1342
|
-
export {
|
|
1343
|
-
//# sourceMappingURL=index-
|
|
1877
|
+
export { NumberRule as $, parseEnumDropHeader as $n, DropEnum as $r, generate as $t, Operand as A, introspectMysql as An, DiffOptions as Ar, json as At, isNull as B, KICK_MIGRATIONS_TABLE as Bn, AlterColumn as Br, timestamptz as Bt, customType as C, DriftLogger as Ci, DB_PRIMARY as Cn, CompositeQueryRunner as Cr, bytea as Ct, RelationsDecl as D, MigrationRow as Di, kickDbAdapter as Dn, RemovedValueAsDefaultError as Dr, doublePrecision as Dt, RelationOne as E, MigrationBookkeeping as Ei, MigrationsOnBoot as En, KickDbError as Er, decimal as Et, gt as F, introspectPg as Fn, AddCheck as Fr, smallSerial as Ft, not as G, Journal as Gn, CreateEnum as Gr, listSeeds as Gt, lt as H, lockTableName as Hn, AlterRole as Hr, varchar as Ht, gte as I, IntrospectPgOptions as In, AddColumn as Ir, smallint as It, notLike as J, computeMigrationHash as Jn, CreateSchema as Jr, checkMigrations as Jt, notExists as K, JournalEntry as Kn, CreatePolicy as Kr, runSeeds as Kt, ilike as L, PgQueryRunner as Ln, AddEnumValue as Lr, text as Lt, between as M, SqliteIntrospectDb as Mn, RenameHints as Mr, numeric as Mt, eq as N, introspectSqlite as Nn, diff as Nr, real as Nt, ThroughSpec as O, IntrospectMysqlOptions as On, hasAmbiguousReverse as Or, integer as Ot, exists as P, introspectSqliteAsync as Pn, findRenameCandidates as Pr, serial as Pt, ClassRefs as Q, enforceEnumDropGate as Qn, DropColumn as Qr, GenerateResult as Qt, inArray as R, MemoryMigrationAdapter as Rn, AddForeignKey as Rr, time as Rt, CustomTypeOptions as S, DriftBehavior as Si, DB_CLIENT as Sn, CompositeEnumReferenceError as Sr, boolean as St, RelationMany as T, MigrationAdapter as Ti, KickDbAdapterConfig as Tn, detectCompositeReferences as Tr, date as Tt, lte as U, migrationsTableDdl as Un, Change as Ur, version as Ut, like as V, lockTableDdl as Vn, AlterPrimaryKey as Vr, uuid as Vt, ne as W, quoteTable as Wn, ChangeSet as Wr, SeedResult as Wt, AliasedTable as X, verifyMigrationHash as Xn, CreateView as Xr, MigrationDb as Xt, or as Y, readJournal as Yn, CreateTable as Yr, CodeMigration as Yt, alias as Z, EnumDropHeader as Zn, DropCheck as Zr, GenerateOptions as Zt, RelationalQueryNotSupportedError as _, toKeyName as _i, migrateRollback as _n, UniqueViolationError as _r, view as _t, markDialect as a, PrimaryKeyShape as ai, reviewMigration as an, MigrationLockError as ar, TableDefinition as at, SchemaToRelationsRegister as b, TenantsConfig as bi, safeNullComparison as bn, ResolvedRelation as br, bigSerial as bt, desc as c, RenameTable as ci, TenantMigrationResult as cn, CheckViolationError as cr, link as ct, likePattern as d, SetTableComment as di, ReversedSummary as dn, DatabaseErrorInfo as dr, MaterializedViewOptions as dt, DropForeignKey as ei, emitMysql as en, MigrationDriftError as er, Rule as et, RelationalQueryAliasCollisionError as f, renderSchemaSource as fi, RollbackSummary as fn, DbDialect as fr, ViewDecl as ft, RelationalQueryMissingInverseError as g, toDbName as gi, migrateLatest as gn, SerializationFailureError as gr, isView as gt, RelationalQueryDepthError as h, Casing as hi, migrateDown as hn, NotNullViolationError as hr, buildView as ht, isDialectTag as i, DropView as ii, ReviewResult as in, MigrationHashError as ir, TableClass as it, and as j, IntrospectSqliteOptions as jn, RenameCandidates as jr, jsonb as jt, relations as k, MysqlIntrospectDb as kn, invertChanges as kr, interval as kt, LikeMatchMode as l, SetColumnComment as li, migrateTenants as ln, ConnectionError as lr, tableFromClass as lt, RelationalQueryCancelledError as m, extractSnapshot as mi, StatusEntry as mn, ForeignKeyViolationError as mr, ViewOptions as mt, DialectTag as n, DropPolicy as ni, emitSqlite as nn, MigrationError as nr, StringRule as nt, readDialectMark as o, RemoveEnumValue as oi, MigrateTenantsOptions as on, SchemaDiffSummary as or, defineTable as ot, RelationalQueryAmbiguousRelationNameError as p, fitIdentifier as pi, RunnerOptions as pn, DeadlockError as pr, ViewMarks as pt, notInArray as q, appendJournalEntry as qn, CreateRole as qr, CheckResult as qt, KICK_DIALECT as r, DropTable as ri, emitPg as rn, MigrationFailedError as rr, TableBase as rt, asc as s, RenameColumn as si, MigrateTenantsResult as sn, UnreviewedMigrationError as sr, fk as st, ReadonlyKysely as t, DropIndex as ti, SqliteRebuildRequiredError as tn, MigrationEnumDropError as tr, RuleFor as tt, escapeLike as u, SetRowLevelSecurity as ui, AppliedSummary as un, DatabaseError as ur, selfRef as ut, RelationalQueryThroughError as v, DbConfig as vi, migrateStatus as vn, translateDbError as vr, TimestampBuilder as vt, Relation as w, checkDrift as wi, DB_REPLICA as wn, CompositeRef as wr, char as wt, CustomColumnBuilder as x, resolveDbConfig as xi, createDbClient as xn, ResolvedRelations as xr, bigint as xt, RelationalQueryUnknownRelationError as y, MigrationAdapterFactory as yi, migrateUp as yn, TransactionFinishedError as yr, UuidBuilder as yt, isNotNull as z, KICK_LOCK_TABLE as zn, AddIndex as zr, timestamp as zt };
|
|
1878
|
+
//# sourceMappingURL=index-2fEnHqpn.d.mts.map
|