@lobomfz/db 0.4.0 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@ bun add @lobomfz/db
 ```typescript
 import { Database, generated, type } from "@lobomfz/db";
 
-const db = new Database({
+const db = await Database.open({
 	path: "data.db",
 	schema: {
 		tables: {
@@ -68,7 +68,7 @@ type("number.integer").configure({ references: "users.id", onDelete: "cascade" }
 JSON columns are validated against the schema on write by default. To also validate on read:
 
 ```typescript
-new Database({
+await Database.open({
 	// ...
 	validation: { onRead: true }, // default: { onRead: false }
 });
@@ -76,7 +76,7 @@ new Database({
 
 ## 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.
+Schema changes are applied automatically on startup. `Database.open(...)` is async because migrations run before it resolves: 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
 
@@ -102,7 +102,58 @@ Table rebuilds follow SQLite's [recommended procedure](https://www.sqlite.org/la
 - 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)
+- Without a guided migration, column renames are treated as drop + add (data in the old column is not preserved)
+
+### Refusing destructive changes
+
+By default the diff applies whatever brings the database in sync, including drops. Set `failOnDataLoss` to turn dropping a table, dropping a column, or a data-discarding type change into a thrown `DataLossError` instead — the database is left untouched.
+
+```typescript
+await Database.open({
+	// ...
+	failOnDataLoss: true,
+});
+```
+
+Configuring a `migration` (see below) routes through the guided path instead, where the drops are intrinsic to the restructure. The gate does not apply there; the drops are logged via `console.warn` so they are still visible.
+
+### Guided data migrations
+
+The automatic diff can rename or restructure a table only by dropping the old shape. When you need to preserve and transform the data — rename a column, split one column into two, convert a type — pass a `migration` with a stable `id` and a `run` function. It receives the same typed Kysely client and runs inside the migration transaction.
+
+```typescript
+await Database.open({
+	path: "data.db",
+	schema: {
+		tables: {
+			users: type({ id: generated("autoincrement"), name: "string", email: "string" }),
+		},
+	},
+	migration: {
+		id: "rename-user-fields",
+		run: async ({ db }) => {
+			const rows = await db
+				.selectFrom("users")
+				.select(["id", sql<string>`full_name`.as("full_name")])
+				.execute();
+
+			for (const row of rows) {
+				await db.updateTable("users").set({ name: row.full_name }).where("id", "=", row.id).execute();
+			}
+		},
+	},
+});
+```
+
+The migration runs as expand then contract, all in one transaction:
+
+1. New tables and new columns are added (new columns nullable, so the backfill can write them).
+2. Your `run` backfills and transforms the data, reading old columns with raw `sql` and writing the new ones through the typed client.
+3. The schema is reconciled to the target: leftover columns and tables are dropped (logged via `console.warn`) and `NOT NULL` is tightened.
+
+`run` already executes inside the migration transaction, so do not open your own with `db.transaction(...)`. Your reads and writes are already atomic with the rest of the migration; if `run` throws, the whole transaction rolls back and the database is left exactly as it was. Referential integrity is checked with `PRAGMA foreign_key_check` before the commit, even when `foreign_keys` is disabled.
+
+Each `id` runs at most once. The applied set lives in a `__migrations` table; a fresh database records the `id` as a baseline without running it (the schema is created directly). Editing the body of an already-applied migration throws `MigrationDriftError` — migrations are immutable once applied, so give new logic a fresh `id`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lobomfz/db",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Bun SQLite database with Arktype schemas and typed Kysely client",
 	"keywords": [
 		"arktype",
@@ -32,15 +32,18 @@
 	},
 	"dependencies": {},
 	"devDependencies": {
-		"@types/bun": "^1.3.11",
-		"@typescript/native-preview": "^7.0.0-dev.20260324.1",
-		"oxfmt": "^0.42.0",
-		"oxlint": "^1.57.0"
+		"@types/bun": "^1.3.12",
+		"@typescript/native-preview": "^7.0.0-dev.20260417.1",
+		"oxfmt": "^0.45.0",
+		"oxlint": "^1.60.0"
 	},
 	"peerDependencies": {
 		"@ark/schema": ">=0.56.0",
 		"@ark/util": ">=0.56.0",
 		"arktype": "^2.1.29",
 		"kysely": "^0.28.14"
+	},
+	"optionalDependencies": {
+		"sqlite-vec": "^0.1.9"
 	}
 }