@lobomfz/db 0.2.1 → 0.3.0

package/README.md

@@ -14,35 +14,35 @@ bun add @lobomfz/db arktype kysely
 import { Database, generated, type } from "@lobomfz/db";
 
 const db = new Database({
-  path: "data.db",
-  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 }],
-    },
-  },
-  pragmas: {
-    journal_mode: "wal",
-    synchronous: "normal",
-  },
+	path: "data.db",
+	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 }],
+		},
+	},
+	pragmas: {
+		journal_mode: "wal",
+		synchronous: "normal",
+	},
 });
 
 // Fully typed Kysely client — generated/default fields are optional on insert
@@ -58,10 +58,10 @@ Booleans, dates, objects, arrays — everything round-trips as the type you decl
 ## API
 
 ```typescript
-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
+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
 ```
 
@@ -69,12 +69,40 @@ JSON columns are validated against the schema on write by default. To also valid
 
 ```typescript
 new Database({
-  // ...
-  validation: { onRead: true },  // default: { onRead: false, onWrite: true }
+	// ...
+	validation: { onRead: true }, // default: { onRead: false, onWrite: true }
 });
 ```
 
-> **Note:** Migrations are not supported yet. Tables are created with `CREATE TABLE IF NOT EXISTS`.
+## Migrations
+
+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.
+
+### What's supported
+
+| 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` |
+
+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.
+
+### Safety rules
+
+- 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.1",
+	"version": "0.3.0",
 	"description": "Bun SQLite database with Arktype schemas and typed Kysely client",
 	"keywords": [
 		"arktype",

package/src/database.ts

@@ -12,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;
@@ -70,7 +73,7 @@ export class Database<T extends SchemaRecord> {
 
 		this.applyPragmas();
 
-		this.createTables();
+		this.migrate();
 
 		const validation = {
 			onRead: options.validation?.onRead ?? false,
@@ -233,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;
 
@@ -284,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) {
@@ -306,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 {
@@ -334,5 +368,4 @@ export class Database<T extends SchemaRecord> {
 			this.sqlite.run(`DELETE FROM "${t}"`);
 		}
 	}
-
 }

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/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;
+};