@lobomfz/db 0.2.0 → 0.3.0

package/README.md

@@ -1,11 +1,11 @@
 # @lobomfz/db
 
-SQLite database with Arktype schemas and typed Kysely client.
+SQLite database with Arktype schemas and typed Kysely client for Bun.
 
 ## Install
 
 ```bash
-bun add @lobomfz/db
+bun add @lobomfz/db arktype kysely
 ```
 
 ## Usage
@@ -15,87 +15,94 @@ import { Database, generated, type } from "@lobomfz/db";
 
 const db = new Database({
 	path: "data.db",
-	tables: {
-		users: type({
-			id: generated("autoincrement"),
-			name: "string",
-			email: type("string").configure({ unique: true }),
-			"bio?": "string",
-			created_at: generated("now"),
-		}),
-		posts: type({
-			id: generated("autoincrement"),
-			user_id: type("number.integer").configure({ references: "users.id", onDelete: "cascade" }),
-			title: "string",
-			tags: "string[]",
-			status: type("string").default("draft"),
-		}),
+	schema: {
+		tables: {
+			users: type({
+				id: generated("autoincrement"),
+				name: "string",
+				email: type("string").configure({ unique: true }),
+				"bio?": "string", // optional → nullable in SQLite
+				active: type("boolean").default(true),
+				created_at: generated("now"), // defaults to current time
+			}),
+			posts: type({
+				id: generated("autoincrement"),
+				user_id: type("number.integer").configure({ references: "users.id", onDelete: "cascade" }),
+				title: "string",
+				published_at: "Date", // native Date support
+				tags: "string[]", // JSON columns just work
+				metadata: type({ source: "string", "priority?": "number" }), // validated on write by default
+				status: type.enumerated("draft", "published").default("draft"),
+			}),
+		},
+		indexes: {
+			posts: [{ columns: ["user_id", "status"] }, { columns: ["title"], unique: true }],
+		},
 	},
-	indexes: {
-		posts: [{ columns: ["user_id", "status"] }, { columns: ["title"], unique: true }],
+	pragmas: {
+		journal_mode: "wal",
+		synchronous: "normal",
 	},
 });
 
-// Fully typed Kysely client - fields with defaults are optional on insert
+// Fully typed Kysely client — generated/default fields are optional on insert
 await db.kysely.insertInto("users").values({ name: "John", email: "john@example.com" }).execute();
 
 const users = await db.kysely.selectFrom("users").selectAll().execute();
+// users[0].active     → true
+// users[0].created_at → Date
 ```
 
-## Features
+Booleans, dates, objects, arrays — everything round-trips as the type you declared. The schema is the source of truth for table creation, TypeScript types, and runtime coercion.
 
-- Tables auto-created from Arktype schemas
-- Full TypeScript inference (insert vs select types)
-- JSON columns with validation
-- Foreign keys, unique constraints, defaults
-- Composite indexes
-
-## Generated Fields
-
-Use `generated()` for SQL-generated values:
+## API
 
 ```typescript
-generated("autoincrement"); // INTEGER PRIMARY KEY AUTOINCREMENT
-generated("now"); // DEFAULT (unixepoch()) - Unix timestamp
+generated("autoincrement"); // auto-incrementing primary key
+generated("now"); // defaults to current timestamp, returned as Date
+type("string").default("pending"); // SQL DEFAULT
+type("string").configure({ unique: true }); // UNIQUE
+type("number.integer").configure({ references: "users.id", onDelete: "cascade" }); // FK
 ```
 
-## Default Values
-
-Use Arktype's `.default()` for JS defaults (also creates SQL DEFAULT):
+JSON columns are validated against the schema on write by default. To also validate on read, or to disable write validation:
 
 ```typescript
-type("string").default("pending");
-type("number").default(0);
+new Database({
+	// ...
+	validation: { onRead: true }, // default: { onRead: false, onWrite: true }
+});
 ```
 
-## Column Configuration
+## Migrations
 
-```typescript
-type("string").configure({ unique: true });
-type("number.integer").configure({ references: "users.id", onDelete: "cascade" });
-```
+Schema changes are applied automatically on startup. Every time `new Database(...)` runs, the library compares your Arktype schema against the actual SQLite database and applies the minimum set of operations to bring them in sync. No migration files, no version tracking — the database itself is the source of truth.
 
-`onDelete` options: `"cascade"`, `"set null"`, `"restrict"`
+### What's supported
 
-## Composite Indexes
+| Change | Strategy |
+|---|---|
+| New table | `CREATE TABLE` |
+| Removed table | `DROP TABLE` |
+| New nullable column | `ALTER TABLE ADD COLUMN` |
+| New NOT NULL column with DEFAULT | `ALTER TABLE ADD COLUMN` |
+| Removed column | Table rebuild |
+| Type change | Table rebuild |
+| Nullability change | Table rebuild |
+| DEFAULT change | Table rebuild |
+| UNIQUE added/removed | Table rebuild |
+| FK added/removed/changed | Table rebuild |
+| Index added | `CREATE INDEX` |
+| Index removed | `DROP INDEX` |
 
-```typescript
-const db = new Database({
-  tables: { ... },
-  indexes: {
-    posts: [
-      { columns: ["user_id", "category_id"], unique: true },
-      { columns: ["created_at"] },
-    ],
-  },
-});
-```
+Table rebuilds follow SQLite's [recommended procedure](https://www.sqlite.org/lang_altertable.html#otheralter): create a new table with the target schema, copy data from the old table, drop the old table, rename the new one. Foreign keys are disabled during rebuilds and validated via `PRAGMA foreign_key_check` before committing.
 
-## Errors
+### Safety rules
 
-```typescript
-import { JsonParseError, JsonValidationError } from "@lobomfz/db";
-```
+- Adding a NOT NULL column without DEFAULT to a table **with data** throws an error
+- Changing a nullable column to NOT NULL without DEFAULT throws if any row has NULL in that column
+- Nullable-to-NOT-NULL with DEFAULT uses `COALESCE` to fill existing NULLs
+- Column renames are treated as drop + add (data in the old column is not preserved)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lobomfz/db",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Bun SQLite database with Arktype schemas and typed Kysely client",
 	"keywords": [
 		"arktype",

package/src/database.ts

@@ -3,6 +3,7 @@ import { Kysely } from "kysely";
 import { BunSqliteDialect } from "./dialect/dialect";
 import type { Type } from "arktype";
 import type { GeneratedPreset } from "./generated";
+import type { DbFieldMeta } from "./env";
 import { DeserializePlugin, type ColumnCoercion, type ColumnsMap } from "./plugin";
 import type {
 	DatabaseOptions,
@@ -11,6 +12,9 @@ import type {
 	TablesFromSchemas,
 	DatabasePragmas,
 } from "./types";
+import { Introspector } from "./migration/introspect";
+import { Differ, type DesiredTable } from "./migration/diff";
+import { Executor } from "./migration/execute";
 
 type ArkBranch = {
 	domain?: string;
@@ -26,7 +30,7 @@ type StructureProp = {
 	value: Type & {
 		branches: ArkBranch[];
 		proto?: unknown;
-		meta: Record<string, unknown>;
+		meta: DbFieldMeta & { _generated?: GeneratedPreset };
 	};
 	inner: { default?: unknown };
 };
@@ -41,7 +45,7 @@ type Prop = {
 	isDate?: boolean;
 	isJson?: boolean;
 	jsonSchema?: Type;
-	meta?: Record<string, unknown>;
+	meta?: DbFieldMeta;
 	generated?: GeneratedPreset;
 	defaultValue?: unknown;
 };
@@ -69,11 +73,16 @@ export class Database<T extends SchemaRecord> {
 
 		this.applyPragmas();
 
-		this.createTables();
+		this.migrate();
+
+		const validation = {
+			onRead: options.validation?.onRead ?? false,
+			onWrite: options.validation?.onWrite ?? true,
+		};
 
 		this.kysely = new Kysely<TablesFromSchemas<T>>({
 			dialect: new BunSqliteDialect({ database: this.sqlite }),
-			plugins: [new DeserializePlugin(this.columns)],
+			plugins: [new DeserializePlugin(this.columns, validation)],
 		});
 	}
 
@@ -95,10 +104,10 @@ export class Database<T extends SchemaRecord> {
 		}
 	}
 
-	private normalizeProp(structureProp: StructureProp, parentSchema: Type): Prop {
+	private normalizeProp(structureProp: StructureProp, parentSchema: Type) {
 		const { key, value: v, inner } = structureProp;
-		const kind = structureProp.required ? "required" : "optional";
-		const generated = v.meta._generated as GeneratedPreset | undefined;
+		const kind: Prop["kind"] = structureProp.required ? "required" : "optional";
+		const generated = v.meta._generated;
 		const defaultValue = inner.default;
 
 		const nonNull = v.branches.filter((b) => b.unit !== null);
@@ -155,7 +164,7 @@ export class Database<T extends SchemaRecord> {
 		return "TEXT";
 	}
 
-	private columnConstraint(prop: Prop): string | null {
+	private columnConstraint(prop: Prop) {
 		if (prop.generated === "autoincrement") {
 			return "PRIMARY KEY AUTOINCREMENT";
 		}
@@ -171,7 +180,7 @@ export class Database<T extends SchemaRecord> {
 		return null;
 	}
 
-	private defaultClause(prop: Prop): string | null {
+	private defaultClause(prop: Prop) {
 		if (prop.generated === "now") {
 			return "DEFAULT (unixepoch())";
 		}
@@ -192,7 +201,7 @@ export class Database<T extends SchemaRecord> {
 			return `DEFAULT ${prop.defaultValue}`;
 		}
 
-		return `DEFAULT '${String(prop.defaultValue)}'`;
+		throw new Error(`Unsupported default value type: ${typeof prop.defaultValue}`);
 	}
 
 	private columnDef(prop: Prop) {
@@ -208,7 +217,7 @@ export class Database<T extends SchemaRecord> {
 	}
 
 	private foreignKey(prop: Prop) {
-		const ref = prop.meta?.references as string | undefined;
+		const ref = prop.meta?.references;
 
 		if (!ref) {
 			return null;
@@ -218,7 +227,7 @@ export class Database<T extends SchemaRecord> {
 
 		let fk = `FOREIGN KEY ("${prop.key}") REFERENCES "${table}"("${column}")`;
 
-		const onDelete = prop.meta?.onDelete as string | undefined;
+		const onDelete = prop.meta?.onDelete;
 
 		if (onDelete) {
 			fk += ` ON DELETE ${onDelete.toUpperCase()}`;
@@ -227,6 +236,23 @@ export class Database<T extends SchemaRecord> {
 		return fk;
 	}
 
+	private addColumnDef(prop: Prop) {
+		let def = this.columnDef(prop);
+
+		const ref = prop.meta?.references;
+
+		if (ref) {
+			const [table, column] = ref.split(".");
+			def += ` REFERENCES "${table}"("${column}")`;
+
+			if (prop.meta?.onDelete) {
+				def += ` ON DELETE ${prop.meta.onDelete.toUpperCase()}`;
+			}
+		}
+
+		return def;
+	}
+
 	private parseSchemaProps(schema: Type) {
 		const structureProps = (schema as any).structure?.props as StructureProp[] | undefined;
 
@@ -278,15 +304,47 @@ export class Database<T extends SchemaRecord> {
 		return `CREATE TABLE IF NOT EXISTS "${tableName}" (${columns.concat(fks).join(", ")})`;
 	}
 
-	private createTables() {
+	private migrate() {
+		const desiredTables: DesiredTable[] = [];
+		const schemaIndexes = this.options.schema.indexes;
+
 		for (const [name, schema] of Object.entries(this.options.schema.tables)) {
 			const props = this.parseSchemaProps(schema);
 
 			this.registerColumns(name, props);
-			this.sqlite.run(this.generateCreateTableSQL(name, props));
+
+			const columns = props.map((prop) => {
+				const isNotNull = this.columnConstraint(prop) === "NOT NULL";
+				const defaultClause = this.defaultClause(prop);
+				const hasLiteralDefault = prop.generated !== "now" && defaultClause !== null;
+
+				return {
+					name: prop.key,
+					addable: !isNotNull || hasLiteralDefault,
+					columnDef: this.addColumnDef(prop),
+					type: this.sqlType(prop),
+					notnull: isNotNull,
+					defaultValue: defaultClause
+					? defaultClause.replace("DEFAULT ", "").replace(/^\((.+)\)$/, "$1")
+					: null,
+					unique: !!prop.meta?.unique,
+					references: prop.meta?.references ?? null,
+					onDelete: prop.meta?.onDelete?.toUpperCase() ?? null,
+				};
+			});
+
+			const indexes = (schemaIndexes?.[name] ?? []).map((indexDef) => ({
+				name: this.generateIndexName(name, indexDef.columns, indexDef.unique ?? false),
+				sql: this.generateCreateIndexSQL(name, indexDef),
+			}));
+
+			desiredTables.push({ name, sql: this.generateCreateTableSQL(name, props), columns, indexes });
 		}
 
-		this.createIndexes();
+		const existing = new Introspector(this.sqlite).introspect();
+		const ops = new Differ(desiredTables, existing).diff();
+
+		new Executor(this.sqlite, ops).execute();
 	}
 
 	private generateIndexName(tableName: string, columns: string[], unique: boolean) {
@@ -300,25 +358,7 @@ export class Database<T extends SchemaRecord> {
 		const unique = indexDef.unique ? "UNIQUE " : "";
 		const columns = indexDef.columns.map((c) => `"${c}"`).join(", ");
 
-		return `CREATE ${unique}INDEX IF NOT EXISTS "${indexName}" ON "${tableName}" (${columns})`;
-	}
-
-	private createIndexes() {
-		const indexes = this.options.schema.indexes;
-
-		if (!indexes) {
-			return;
-		}
-
-		for (const [tableName, tableIndexes] of Object.entries(indexes)) {
-			if (!tableIndexes) {
-				continue;
-			}
-
-			for (const indexDef of tableIndexes) {
-				this.sqlite.run(this.generateCreateIndexSQL(tableName, indexDef));
-			}
-		}
+		return `CREATE ${unique}INDEX "${indexName}" ON "${tableName}" (${columns})`;
 	}
 
 	reset(table?: keyof T & string): void {
@@ -328,5 +368,4 @@ export class Database<T extends SchemaRecord> {
 			this.sqlite.run(`DELETE FROM "${t}"`);
 		}
 	}
-
 }

package/src/dialect/connection.ts

@@ -1,4 +1,4 @@
-import { Database } from "bun:sqlite";
+import type { Database } from "bun:sqlite";
 import type { CompiledQuery, DatabaseConnection, QueryResult } from "kysely";
 import { serializeParam } from "./serialize";
 
@@ -9,30 +9,30 @@ export class BunSqliteConnection implements DatabaseConnection {
 		this.#db = db;
 	}
 
-	executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>> {
-		const { sql, parameters } = compiledQuery;
-		const serializedParams = parameters.map(serializeParam);
-		const stmt = this.#db.query(sql);
+	async executeQuery<O>(compiled: CompiledQuery): Promise<QueryResult<O>> {
+		const serializedParams = compiled.parameters.map(serializeParam);
+
+		const stmt = this.#db.query(compiled.sql);
 
 		if (stmt.columnNames.length > 0) {
-			return Promise.resolve({
+			return {
 				rows: stmt.all(serializedParams as any) as O[],
-			});
+			};
 		}
 
 		const results = stmt.run(serializedParams as any);
 
-		return Promise.resolve({
+		return {
 			insertId: BigInt(results.lastInsertRowid),
 			numAffectedRows: BigInt(results.changes),
 			rows: [],
-		});
+		};
 	}
 
 	async *streamQuery<R>(compiledQuery: CompiledQuery): AsyncIterableIterator<QueryResult<R>> {
-		const { sql, parameters } = compiledQuery;
-		const serializedParams = parameters.map(serializeParam);
-		const stmt = this.#db.prepare(sql);
+		const serializedParams = compiledQuery.parameters.map(serializeParam);
+
+		const stmt = this.#db.prepare(compiledQuery.sql);
 
 		for await (const row of stmt.iterate(serializedParams as any)) {
 			yield { rows: [row as R] };

package/src/dialect/driver.ts

@@ -1,4 +1,4 @@
-import { Database } from "bun:sqlite";
+import type { Database } from "bun:sqlite";
 import { CompiledQuery, type DatabaseConnection, type Driver } from "kysely";
 import type { BunSqliteDialectConfig } from "./config";
 import { BunSqliteConnection } from "./connection";
@@ -38,12 +38,10 @@ export class BunSqliteDriver implements Driver {
 		await connection.executeQuery(CompiledQuery.raw("rollback"));
 	}
 
-	// oxlint-disable-next-line require-await
 	async releaseConnection(): Promise<void> {
 		this.#connectionMutex.unlock();
 	}
 
-	// oxlint-disable-next-line require-await
 	async destroy(): Promise<void> {
 		this.#db?.close();
 	}

package/src/generated.ts

@@ -13,6 +13,8 @@ const generatedTypes = {
 			.default(() => new Date(0)),
 };
 
-export function generated<P extends GeneratedPreset>(preset: P): ReturnType<(typeof generatedTypes)[P]> {
+export function generated<P extends GeneratedPreset>(
+	preset: P,
+): ReturnType<(typeof generatedTypes)[P]> {
 	return generatedTypes[preset]() as ReturnType<(typeof generatedTypes)[P]>;
 }

package/src/index.ts

@@ -14,5 +14,6 @@ export type {
 	IndexesConfig,
 	DatabasePragmas,
 	DatabaseSchema,
+	JsonValidation,
 	SqliteMasterRow,
 } from "./types";

package/src/migration/diff.ts

@@ -0,0 +1,193 @@
+import type { ColumnSchema, IntrospectedTable, ColumnCopy, MigrationOp } from "./types";
+
+export interface DesiredColumn extends ColumnSchema {
+	addable: boolean;
+	columnDef: string;
+}
+
+export type DesiredIndex = {
+	name: string;
+	sql: string;
+};
+
+export type DesiredTable = {
+	name: string;
+	sql: string;
+	columns: DesiredColumn[];
+	indexes?: DesiredIndex[];
+};
+
+export class Differ {
+	private ops: MigrationOp[] = [];
+	private desiredNames: Set<string>;
+	private rebuiltTables = new Set<string>();
+
+	constructor(
+		private desired: DesiredTable[],
+		private existing: Map<string, IntrospectedTable>,
+	) {
+		this.desiredNames = new Set(desired.map((t) => t.name));
+	}
+
+	diff() {
+		this.diffTables();
+		this.dropOrphans();
+		this.diffIndexes();
+		return this.ops;
+	}
+
+	private diffTables() {
+		for (const table of this.desired) {
+			const existingTable = this.existing.get(table.name);
+
+			if (!existingTable) {
+				this.ops.push({ type: "CreateTable", table: table.name, sql: table.sql });
+				this.rebuiltTables.add(table.name);
+				continue;
+			}
+
+			this.diffColumns(table, existingTable);
+		}
+	}
+
+	private diffColumns(table: DesiredTable, existingTable: IntrospectedTable) {
+		const desiredNames = new Set(table.columns.map((c) => c.name));
+		const hasRemovedColumns = [...existingTable.columns.keys()].some(
+			(name) => !desiredNames.has(name),
+		);
+		const hasChangedColumns = table.columns.some((col) => {
+			const existing = existingTable.columns.get(col.name);
+
+			if (!existing) {
+				return false;
+			}
+
+			return this.columnChanged(col, existing);
+		});
+
+		if (hasRemovedColumns || hasChangedColumns) {
+			this.buildRebuild(table, existingTable);
+			return;
+		}
+
+		this.buildAddColumns(table, existingTable);
+	}
+
+	private buildRebuild(table: DesiredTable, existingTable: IntrospectedTable) {
+		const columnCopies: ColumnCopy[] = [];
+
+		for (const col of table.columns) {
+			const existing = existingTable.columns.get(col.name);
+
+			if (!existing) {
+				continue;
+			}
+
+			if (col.type !== existing.type) {
+				if (col.notnull && col.defaultValue === null && existingTable.hasData) {
+					throw new Error(
+						`Cannot change type of NOT NULL column "${col.name}" without DEFAULT in table "${table.name}" with existing data`,
+					);
+				}
+
+				continue;
+			}
+
+			if (!existing.notnull && col.notnull && col.defaultValue === null && existing.hasNulls) {
+				throw new Error(
+					`Cannot make column "${col.name}" NOT NULL without DEFAULT in table "${table.name}" with existing data`,
+				);
+			}
+
+			if (!existing.notnull && col.notnull && col.defaultValue !== null) {
+				columnCopies.push({ name: col.name, expr: `COALESCE("${col.name}", ${col.defaultValue})` });
+			} else {
+				columnCopies.push({ name: col.name, expr: `"${col.name}"` });
+			}
+		}
+
+		this.ops.push({ type: "RebuildTable", table: table.name, createSql: table.sql, columnCopies });
+		this.rebuiltTables.add(table.name);
+	}
+
+	private buildAddColumns(table: DesiredTable, existingTable: IntrospectedTable) {
+		const newColumns = table.columns.filter((c) => !existingTable.columns.has(c.name));
+
+		if (newColumns.length === 0) {
+			return;
+		}
+
+		const nonAddable = newColumns.filter((c) => !c.addable);
+
+		if (nonAddable.length > 0) {
+			if (existingTable.hasData) {
+				throw new Error(
+					`Cannot add NOT NULL column "${nonAddable[0]!.name}" without DEFAULT to table "${table.name}" with existing data`,
+				);
+			}
+
+			this.ops.push({ type: "DropTable", table: table.name });
+			this.ops.push({ type: "CreateTable", table: table.name, sql: table.sql });
+			this.rebuiltTables.add(table.name);
+			return;
+		}
+
+		for (const col of newColumns) {
+			this.ops.push({ type: "AddColumn", table: table.name, columnDef: col.columnDef });
+		}
+	}
+
+	private columnChanged(desired: ColumnSchema, existing: ColumnSchema) {
+		return (
+			desired.type !== existing.type ||
+			desired.notnull !== existing.notnull ||
+			desired.defaultValue !== existing.defaultValue ||
+			desired.unique !== existing.unique ||
+			desired.references !== existing.references ||
+			desired.onDelete !== existing.onDelete
+		);
+	}
+
+	private dropOrphans() {
+		for (const [name] of this.existing) {
+			if (!this.desiredNames.has(name)) {
+				this.ops.push({ type: "DropTable", table: name });
+			}
+		}
+	}
+
+	private diffIndexes() {
+		for (const table of this.desired) {
+			const tableIndexes = table.indexes ?? [];
+
+			if (this.rebuiltTables.has(table.name)) {
+				for (const idx of tableIndexes) {
+					this.ops.push({ type: "CreateIndex", sql: idx.sql });
+				}
+
+				continue;
+			}
+
+			const existingTable = this.existing.get(table.name);
+
+			if (!existingTable) {
+				continue;
+			}
+
+			const existingNames = new Set(existingTable.indexes.map((i) => i.name));
+			const desiredNames = new Set(tableIndexes.map((i) => i.name));
+
+			for (const idx of tableIndexes) {
+				if (!existingNames.has(idx.name)) {
+					this.ops.push({ type: "CreateIndex", sql: idx.sql });
+				}
+			}
+
+			for (const idx of existingTable.indexes) {
+				if (!desiredNames.has(idx.name)) {
+					this.ops.push({ type: "DropIndex", index: idx.name });
+				}
+			}
+		}
+	}
+}

package/src/migration/execute.ts

@@ -0,0 +1,93 @@
+import type { Database } from "bun:sqlite";
+import type { MigrationOp, RebuildTableOp } from "./types";
+
+export class Executor {
+	constructor(
+		private db: Database,
+		private ops: MigrationOp[],
+	) {}
+
+	execute() {
+		if (this.ops.length === 0) {
+			return;
+		}
+
+		const hasRebuild = this.ops.some((op) => op.type === "RebuildTable");
+
+		let restoreFk = false;
+
+		if (hasRebuild) {
+			const { foreign_keys } = this.db.prepare("PRAGMA foreign_keys").get() as {
+				foreign_keys: number;
+			};
+
+			if (foreign_keys === 1) {
+				this.db.run("PRAGMA foreign_keys = OFF");
+				restoreFk = true;
+			}
+		}
+
+		try {
+			this.db.transaction(() => {
+				for (const op of this.ops) {
+					this.executeOp(op);
+				}
+
+				if (restoreFk) {
+					const violations = this.db.prepare("PRAGMA foreign_key_check").all();
+
+					if (violations.length > 0) {
+						throw new Error("Foreign key check failed after rebuild");
+					}
+				}
+			})();
+		} finally {
+			if (restoreFk) {
+				this.db.run("PRAGMA foreign_keys = ON");
+			}
+		}
+	}
+
+	private executeOp(op: MigrationOp) {
+		switch (op.type) {
+			case "CreateTable": {
+				return this.db.run(op.sql);
+			}
+			case "DropTable": {
+				return this.db.run(`DROP TABLE "${op.table}"`);
+			}
+			case "AddColumn": {
+				return this.db.run(`ALTER TABLE "${op.table}" ADD COLUMN ${op.columnDef}`);
+			}
+			case "RebuildTable": {
+				return this.rebuildTable(op);
+			}
+			case "CreateIndex": {
+				return this.db.run(op.sql);
+			}
+			case "DropIndex": {
+				return this.db.run(`DROP INDEX "${op.index}"`);
+			}
+		}
+	}
+
+	private rebuildTable(op: RebuildTableOp) {
+		const tempName = `__new_${op.table}`;
+		const tempSql = op.createSql.replace(
+			`CREATE TABLE IF NOT EXISTS "${op.table}"`,
+			`CREATE TABLE "${tempName}"`,
+		);
+
+		this.db.run(tempSql);
+
+		if (op.columnCopies.length > 0) {
+			const destCols = op.columnCopies.map((c) => `"${c.name}"`).join(", ");
+			const srcExprs = op.columnCopies.map((c) => c.expr).join(", ");
+
+			this.db.run(`INSERT INTO "${tempName}" (${destCols}) SELECT ${srcExprs} FROM "${op.table}"`);
+		}
+
+		this.db.run(`DROP TABLE "${op.table}"`);
+		this.db.run(`ALTER TABLE "${tempName}" RENAME TO "${op.table}"`);
+	}
+}

package/src/migration/introspect.ts

@@ -0,0 +1,140 @@
+import type { Database } from "bun:sqlite";
+import type { IntrospectedColumn, IntrospectedIndex, IntrospectedTable } from "./types";
+
+type TableListRow = {
+	name: string;
+	type: string;
+};
+
+type TableXInfoRow = {
+	name: string;
+	type: string;
+	notnull: number;
+	dflt_value: string | null;
+};
+
+type IndexListRow = {
+	name: string;
+	unique: number;
+	origin: string;
+};
+
+type IndexInfoRow = {
+	name: string;
+};
+
+type ForeignKeyListRow = {
+	from: string;
+	table: string;
+	to: string;
+	on_delete: string;
+};
+
+export class Introspector {
+	constructor(private db: Database) {}
+
+	introspect() {
+		const tables = new Map<string, IntrospectedTable>();
+		const tableRows = this.db.prepare("PRAGMA table_list").all() as TableListRow[];
+
+		for (const row of tableRows) {
+			if (row.type !== "table" || row.name.startsWith("sqlite_")) {
+				continue;
+			}
+
+			const indexRows = this.db.prepare(`PRAGMA index_list("${row.name}")`).all() as IndexListRow[];
+			const uniqueCols = this.uniqueColumns(indexRows);
+			const fkMap = this.foreignKeys(row.name);
+			const columns = this.columns(row.name, uniqueCols, fkMap);
+			const indexes = this.indexes(indexRows);
+			const hasData = this.db.prepare(`SELECT 1 FROM "${row.name}" LIMIT 1`).get() !== null;
+
+			tables.set(row.name, { columns, indexes, hasData });
+		}
+
+		return tables;
+	}
+
+	private uniqueColumns(indexRows: IndexListRow[]) {
+		const unique = new Set<string>();
+
+		for (const idx of indexRows) {
+			if (idx.unique !== 1 || idx.origin !== "u") {
+				continue;
+			}
+
+			const idxCols = this.db.prepare(`PRAGMA index_info("${idx.name}")`).all() as IndexInfoRow[];
+
+			if (idxCols.length === 1) {
+				unique.add(idxCols[0]!.name);
+			}
+		}
+
+		return unique;
+	}
+
+	private indexes(indexRows: IndexListRow[]) {
+		const indexes: IntrospectedIndex[] = [];
+
+		for (const idx of indexRows) {
+			if (idx.origin !== "c") {
+				continue;
+			}
+
+			const idxCols = this.db.prepare(`PRAGMA index_info("${idx.name}")`).all() as IndexInfoRow[];
+
+			indexes.push({
+				name: idx.name,
+				columns: idxCols.map((c) => c.name),
+				unique: idx.unique === 1,
+			});
+		}
+
+		return indexes;
+	}
+
+	private foreignKeys(table: string) {
+		const fkRows = this.db
+			.prepare(`PRAGMA foreign_key_list("${table}")`)
+			.all() as ForeignKeyListRow[];
+		const fkMap = new Map<string, { references: string; onDelete: string | null }>();
+
+		for (const fk of fkRows) {
+			fkMap.set(fk.from, {
+				references: `${fk.table}.${fk.to}`,
+				onDelete: fk.on_delete === "NO ACTION" ? null : fk.on_delete,
+			});
+		}
+
+		return fkMap;
+	}
+
+	private columns(
+		table: string,
+		uniqueCols: Set<string>,
+		fkMap: Map<string, { references: string; onDelete: string | null }>,
+	) {
+		const colRows = this.db.prepare(`PRAGMA table_xinfo("${table}")`).all() as TableXInfoRow[];
+		const columns = new Map<string, IntrospectedColumn>();
+
+		for (const col of colRows) {
+			const fk = fkMap.get(col.name);
+			const isNotnull = col.notnull === 1;
+
+			columns.set(col.name, {
+				name: col.name,
+				type: col.type,
+				notnull: isNotnull,
+				defaultValue: col.dflt_value,
+				unique: uniqueCols.has(col.name),
+				references: fk?.references ?? null,
+				onDelete: fk?.onDelete ?? null,
+				hasNulls:
+					!isNotnull &&
+					this.db.prepare(`SELECT 1 FROM "${table}" WHERE "${col.name}" IS NULL LIMIT 1`).get() !== null,
+			});
+		}
+
+		return columns;
+	}
+}

package/src/migration/types.ts

@@ -0,0 +1,72 @@
+export type CreateTableOp = {
+	type: "CreateTable";
+	table: string;
+	sql: string;
+};
+
+export type DropTableOp = {
+	type: "DropTable";
+	table: string;
+};
+
+export type AddColumnOp = {
+	type: "AddColumn";
+	table: string;
+	columnDef: string;
+};
+
+export type ColumnCopy = {
+	name: string;
+	expr: string;
+};
+
+export type RebuildTableOp = {
+	type: "RebuildTable";
+	table: string;
+	createSql: string;
+	columnCopies: ColumnCopy[];
+};
+
+export type CreateIndexOp = {
+	type: "CreateIndex";
+	sql: string;
+};
+
+export type DropIndexOp = {
+	type: "DropIndex";
+	index: string;
+};
+
+export type MigrationOp =
+	| CreateTableOp
+	| DropTableOp
+	| AddColumnOp
+	| RebuildTableOp
+	| CreateIndexOp
+	| DropIndexOp;
+
+export type ColumnSchema = {
+	name: string;
+	type: string;
+	notnull: boolean;
+	defaultValue: string | null;
+	unique: boolean;
+	references: string | null;
+	onDelete: string | null;
+};
+
+export interface IntrospectedColumn extends ColumnSchema {
+	hasNulls: boolean;
+}
+
+export type IntrospectedIndex = {
+	name: string;
+	columns: string[];
+	unique: boolean;
+};
+
+export type IntrospectedTable = {
+	columns: Map<string, IntrospectedColumn>;
+	indexes: IntrospectedIndex[];
+	hasData: boolean;
+};

package/src/plugin.ts

@@ -1,40 +1,71 @@
-import { type KyselyPlugin, type RootOperationNode, type UnknownRow } from "kysely";
+import {
+	type KyselyPlugin,
+	type RootOperationNode,
+	type UnknownRow,
+	type QueryId,
+	TableNode,
+	AliasNode,
+	ValuesNode,
+	ValueNode,
+	ColumnNode,
+} from "kysely";
 import { type } from "arktype";
 import type { Type } from "arktype";
 import { JsonParseError } from "./errors";
 import { JsonValidationError } from "./validation-error";
+import type { JsonValidation } from "./types";
 
 export type ColumnCoercion = "boolean" | "date" | { type: "json"; schema: Type };
 export type ColumnsMap = Map<string, Map<string, ColumnCoercion>>;
 
 export class DeserializePlugin implements KyselyPlugin {
-	private queryNodes = new Map<unknown, RootOperationNode>();
+	private queryNodes = new WeakMap<QueryId, RootOperationNode>();
 
-	constructor(private columns: ColumnsMap) {}
+	constructor(
+		private columns: ColumnsMap,
+		private validation: Required<JsonValidation>,
+	) {}
 
 	transformQuery: KyselyPlugin["transformQuery"] = (args) => {
 		this.queryNodes.set(args.queryId, args.node);
 
+		if (this.validation.onWrite) {
+			this.validateWriteNode(args.node);
+		}
+
 		return args.node;
 	};
 
-	private getTableFromNode(node: RootOperationNode): string | null {
+	private getTableFromNode(node: RootOperationNode) {
 		switch (node.kind) {
 			case "InsertQueryNode":
-				return (node as any).into?.table?.identifier?.name ?? null;
+				return node.into?.table.identifier.name ?? null;
 
-			case "UpdateQueryNode":
-				return (node as any).table?.table?.identifier?.name ?? null;
+			case "UpdateQueryNode": {
+				if (node.table && TableNode.is(node.table)) {
+					return node.table.table.identifier.name;
+				}
+
+				return null;
+			}
 
 			case "SelectQueryNode":
 			case "DeleteQueryNode": {
-				const fromNode = (node as any).from?.froms?.[0];
+				const fromNode = node.from?.froms[0];
+
+				if (!fromNode) {
+					return null;
+				}
+
+				if (AliasNode.is(fromNode) && TableNode.is(fromNode.node)) {
+					return fromNode.node.table.identifier.name;
+				}
 
-				if (fromNode?.kind === "AliasNode") {
-					return fromNode.node?.table?.identifier?.name ?? null;
+				if (TableNode.is(fromNode)) {
+					return fromNode.table.identifier.name;
 				}
 
-				return fromNode?.table?.identifier?.name ?? null;
+				return null;
 			}
 
 			default:
@@ -42,6 +73,82 @@ export class DeserializePlugin implements KyselyPlugin {
 		}
 	}
 
+	private validateJsonValue(table: string, col: string, value: unknown, schema: Type) {
+		if (value === null || value === undefined) {
+			return;
+		}
+
+		const result = schema(value);
+
+		if (result instanceof type.errors) {
+			throw new JsonValidationError(table, col, result.summary);
+		}
+	}
+
+	private validateWriteNode(node: RootOperationNode) {
+		if (node.kind !== "InsertQueryNode" && node.kind !== "UpdateQueryNode") {
+			return;
+		}
+
+		const table = this.getTableFromNode(node);
+
+		if (!table) {
+			return;
+		}
+
+		const cols = this.columns.get(table);
+
+		if (!cols) {
+			return;
+		}
+
+		for (const [col, value] of this.writeValues(node)) {
+			const coercion = cols.get(col);
+
+			if (!coercion || typeof coercion === "string") {
+				continue;
+			}
+
+			this.validateJsonValue(table, col, value, coercion.schema);
+		}
+	}
+
+	private *writeValues(node: RootOperationNode) {
+		if (node.kind === "InsertQueryNode") {
+			const columns = node.columns?.map((c) => c.column.name);
+
+			if (!columns || !node.values || !ValuesNode.is(node.values)) {
+				return;
+			}
+
+			for (const valueList of node.values.values) {
+				for (let i = 0; i < columns.length; i++) {
+					const col = columns[i]!;
+
+					if (valueList.kind === "PrimitiveValueListNode") {
+						yield [col, valueList.values[i]] as [string, unknown];
+						continue;
+					}
+
+					const raw = valueList.values[i];
+					yield [col, raw && ValueNode.is(raw) ? raw.value : raw] as [string, unknown];
+				}
+			}
+
+			return;
+		}
+
+		if (node.kind !== "UpdateQueryNode" || !node.updates) {
+			return;
+		}
+
+		for (const update of node.updates) {
+			if (ColumnNode.is(update.column) && ValueNode.is(update.value)) {
+				yield [update.column.column.name, update.value.value] as [string, unknown];
+			}
+		}
+	}
+
 	private coerceRow(table: string, row: UnknownRow, cols: Map<string, ColumnCoercion>) {
 		for (const [col, coercion] of cols) {
 			if (!(col in row)) {
@@ -78,17 +185,14 @@ export class DeserializePlugin implements KyselyPlugin {
 				throw new JsonParseError(table, col, value, e);
 			}
 
-			const validated = coercion.schema(parsed);
-
-			if (validated instanceof type.errors) {
-				throw new JsonValidationError(table, col, validated.summary);
+			if (this.validation.onRead) {
+				this.validateJsonValue(table, col, parsed, coercion.schema);
 			}
 
-			row[col] = validated;
+			row[col] = parsed;
 		}
 	}
 
-	// oxlint-disable-next-line require-await
 	transformResult: KyselyPlugin["transformResult"] = async (args) => {
 		const node = this.queryNodes.get(args.queryId);
 

package/src/types.ts

@@ -58,8 +58,14 @@ export type DatabaseSchema<T extends SchemaRecord> = {
 	indexes?: IndexesConfig<T>;
 };
 
+export type JsonValidation = {
+	onRead?: boolean;
+	onWrite?: boolean;
+};
+
 export type DatabaseOptions<T extends SchemaRecord> = {
 	path: string;
 	schema: DatabaseSchema<T>;
 	pragmas?: DatabasePragmas;
+	validation?: JsonValidation;
 };