@sedrino/db-schema 0.1.1 → 0.1.2

package/docs/cli.md

@@ -2,6 +2,8 @@
 
 The package ships a Bun-first CLI named `sedrino-db`.
 
+The published CLI expects `bun` to be installed because the generated executable uses a Bun shebang.
+
 ## Default project layout
 
 ```text
@@ -14,6 +16,40 @@ db/
 
 ## Commands
 
+### Create
+
+```bash
+sedrino-db migrate create create-account --dir db
+```
+
+This:
+
+- creates `db/migrations` if it does not exist yet
+- assigns the next migration id using the local date plus a zero-padded sequence
+- writes a new TypeScript migration scaffold
+
+Example output file:
+
+```text
+db/migrations/2026-04-08-001-create-account.ts
+```
+
+Generated scaffold:
+
+```ts
+import { createMigration } from "@sedrino/db-schema";
+
+export default createMigration(
+  {
+    id: "2026-04-08-001-create-account",
+    name: "Create account",
+  },
+  (m) => {
+    // TODO: define migration operations.
+  },
+);
+```
+
 ### Plan
 
 ```bash
@@ -29,6 +65,15 @@ This:
 
 Add `--sql` to print the SQLite statements per migration.
 
+You can override the generated artifact paths explicitly:
+
+```bash
+sedrino-db migrate plan \
+  --dir db \
+  --snapshot db/schema/custom.snapshot.json \
+  --drizzle-out db/schema/custom.generated.ts
+```
+
 ### Apply
 
 ```bash
@@ -40,6 +85,7 @@ This:
 - reads local migrations
 - compares them with applied migrations recorded in the database
 - applies pending migrations
+- refuses to run migrations whose plan still contains safety warnings
 - updates the stored schema metadata tables
 - writes the local snapshot and generated Drizzle file
 
@@ -53,6 +99,47 @@ URL resolution order:
 - `--url`
 - `LIBSQL_URL`
 
+Example with environment variables:
+
+```bash
+export LIBSQL_URL=libsql://my-db.turso.io
+export LIBSQL_AUTH_TOKEN=secret
+
+sedrino-db migrate apply --dir db
+```
+
+### Validate
+
+```bash
+sedrino-db migrate validate --dir db
+```
+
+This:
+
+- materializes the schema from local migrations
+- reports planner warnings that would block apply
+- checks whether `schema.snapshot.json` is up to date
+- checks whether `schema.generated.ts` is up to date
+
+The command exits non-zero if warnings are present or generated artifacts are stale.
+
+### Status
+
+```bash
+sedrino-db migrate status --dir db --url libsql://...
+```
+
+This:
+
+- reports the local migration count and local schema hash
+- optionally inspects the connected database
+- reports applied, pending, and unexpected database migrations
+- reports schema drift based on the stored schema hash
+
+The command exits non-zero if drift is detected or the database contains migrations that are not present locally.
+
+If `--url` or `LIBSQL_URL` is omitted, the command still prints local migration status and local schema hash.
+
 ### Print schema
 
 ```bash
@@ -68,3 +155,9 @@ sedrino-db schema drizzle --dir db --out db/schema/schema.generated.ts
 ```
 
 Prints generated Drizzle source to stdout unless `--out` is provided.
+
+Stdout example:
+
+```bash
+sedrino-db schema drizzle --dir db
+```

package/docs/expressions-and-transforms.md

@@ -0,0 +1,165 @@
+# SQL Expressions And Transforms
+
+The package exposes two layers for rebuild-time data movement:
+
+- low-level SQL expression helpers
+- higher-level migration intent transforms
+
+## Low-level expression helpers
+
+Use these when you want full control over the SQL fragment used in `backfill(...)` or `using(...)`.
+
+Exports:
+
+- `sqlExpression(...)`
+- `raw(...)`
+- `column(...)`
+- `literal(...)`
+- `lower(...)`
+- `trim(...)`
+- `replace(...)`
+- `cast(...)`
+- `unixepoch(...)`
+- `date(...)`
+- `multiply(...)`
+- `coalesce(...)`
+- `concat(...)`
+- `sqlExpr.*`
+
+Example:
+
+```ts
+import { sqlExpr } from "@sedrino/db-schema";
+
+const expression = sqlExpr.multiply(
+  sqlExpr.cast(sqlExpr.unixepoch(sqlExpr.column("createdAt")), "INTEGER"),
+  1000,
+);
+```
+
+This produces:
+
+```sql
+CAST(unixepoch("created_at") AS INTEGER) * 1000
+```
+
+## Raw migration examples
+
+`backfill(...)` and `using(...)` accept either strings or expression objects:
+
+```ts
+import { createMigration, sqlExpr } from "@sedrino/db-schema";
+
+export default createMigration(
+  {
+    id: "2026-04-08-001",
+    name: "Backfill slug and convert createdAt",
+  },
+  (m) => {
+    m.alterTable("account", (t) => {
+      t.string("slug")
+        .required()
+        .backfill(sqlExpr.lower(sqlExpr.replace(sqlExpr.trim(sqlExpr.column("name")), " ", "-")));
+
+      t.alterField("createdAt", (f) => {
+        f.temporalInstant().using(
+          sqlExpr.multiply(
+            sqlExpr.cast(sqlExpr.unixepoch(sqlExpr.column("createdAt")), "INTEGER"),
+            1000,
+          ),
+        );
+      });
+    });
+  },
+);
+```
+
+## Higher-level transforms
+
+Use `transforms.*` when you want the migration to read as intent instead of hand-built SQL.
+
+Exports:
+
+- `copy(...)`
+- `lowercase(...)`
+- `trimmed(...)`
+- `slugFrom(...)`
+- `concatFields(...)`
+- `coalesceFields(...)`
+- `epochMsFromIsoString(...)`
+- `plainDateFromIsoString(...)`
+- `integerFromText(...)`
+- `realFromText(...)`
+- `transforms`
+
+Example:
+
+```ts
+import { createMigration, transforms } from "@sedrino/db-schema";
+
+export default createMigration(
+  {
+    id: "2026-04-08-001",
+    name: "Normalize account fields",
+  },
+  (m) => {
+    m.alterTable("account", (t) => {
+      t.string("slug")
+        .required()
+        .backfill(transforms.slugFrom("name"));
+
+      t.string("searchName")
+        .required()
+        .backfill(transforms.lowercase("displayName"));
+
+      t.alterField("createdAt", (f) => {
+        f.temporalInstant().using(transforms.epochMsFromIsoString("createdAt"));
+      });
+    });
+  },
+);
+```
+
+## Common patterns
+
+### Copy a field directly
+
+```ts
+transforms.copy("accountId");
+```
+
+### Join fields together
+
+```ts
+transforms.concatFields(["firstName", "lastName"], { separator: " " });
+```
+
+### Use the first populated field
+
+```ts
+transforms.coalesceFields(["nickname", "name"], "Unknown");
+```
+
+### Parse numbers from legacy text columns
+
+```ts
+transforms.integerFromText("priority");
+transforms.realFromText("amount");
+```
+
+### Convert ISO date/time strings
+
+```ts
+transforms.epochMsFromIsoString("createdAt");
+transforms.plainDateFromIsoString("birthday");
+```
+
+## When to use which layer
+
+Use `transforms.*` first when a helper already matches the migration intent.
+
+Drop down to `sqlExpr.*` or raw strings when:
+
+- you need a custom SQL function
+- you need a composition the built-in transforms do not cover yet
+- you are prototyping a new reusable transform before promoting it into `transforms.*`

package/docs/index.md

@@ -6,6 +6,9 @@ Reference index for the migration-first schema planning package.
 
 | Topic | File |
 | --- | --- |
-| Schema document model | [`schema-document.md`](./schema-document.md) |
-| Migration DSL and planning flow | [`migrations.md`](./migrations.md) |
+| Schema document model and validation helpers | [`schema-document.md`](./schema-document.md) |
+| Migration DSL and authoring helpers | [`migrations.md`](./migrations.md) |
+| Planning, apply, and project APIs | [`planning-and-apply.md`](./planning-and-apply.md) |
+| SQL expression and transform helpers | [`expressions-and-transforms.md`](./expressions-and-transforms.md) |
+| Drizzle relations generation | [`relations.md`](./relations.md) |
 | CLI commands | [`cli.md`](./cli.md) |

package/docs/migrations.md

@@ -36,9 +36,64 @@ export default createMigration(
 );
 ```
 
+## Core authoring surface
+
+The migration builder supports:
+
+- `createTable(...)`
+- `createJunctionTable(...)`
+- `dropTable(...)`
+- `renameTable(...)`
+- `alterTable(...)`
+
+Inside `createTable(...)`, the table builder supports:
+
+- field builders:
+  - `id(...)`
+  - `string(...)`
+  - `text(...)`
+  - `boolean(...)`
+  - `integer(...)`
+  - `number(...)`
+  - `enum(...)`
+  - `json(...)`
+  - `temporalInstant(...)`
+  - `temporalPlainDate(...)`
+  - `reference(...)`
+  - `belongsTo(...)`
+- table metadata:
+  - `description(...)`
+  - `index(...)`
+  - `unique(...)`
+
+Inside `alterTable(...)`, the alter builder supports:
+
+- add field:
+  - `string(...)`
+  - `text(...)`
+  - `boolean(...)`
+  - `integer(...)`
+  - `number(...)`
+  - `enum(...)`
+  - `json(...)`
+  - `temporalInstant(...)`
+  - `temporalPlainDate(...)`
+  - `reference(...)`
+  - `belongsTo(...)`
+- change structure:
+  - `dropField(...)`
+  - `renameField(...)`
+  - `alterField(...)`
+  - `addIndex(...)`
+  - `dropIndex(...)`
+  - `addUnique(...)`
+  - `dropUnique(...)`
+
 ## Planning flow
 
 ```ts
+import { planMigration } from "@sedrino/db-schema";
+
 const plan = planMigration({
   currentSchema,
   migration,
@@ -49,8 +104,14 @@ The result includes:
 
 - ordered semantic operations
 - next schema snapshot JSON
-- SQLite migration statements where v1 can emit them safely
-- warnings for operations that still need rebuild-aware emitters
+- SQLite migration statements, including rebuild-based statements for supported shape changes
+- warnings for operations that still require explicit data transforms or multi-step backfills
+
+The `nextSchema` output is then what you pass to:
+
+- `compileSchemaToDrizzle(...)`
+- `compileSchemaToDrizzleRelations(...)`
+- `compileSchemaToSqlite(...)`
 
 For project-style usage, the CLI wraps this flow:
 
@@ -58,8 +119,127 @@ For project-style usage, the CLI wraps this flow:
 sedrino-db migrate plan --dir db
 ```
 
+## Field alterations
+
+The v1 migration DSL now supports conservative field alteration through `alterField(...)`.
+
+```ts
+m.alterTable("account", (t) => {
+  t.alterField("nickname", (f) => {
+    f.required().default("unknown").description("Display nickname");
+  });
+});
+```
+
+Supported `alterField(...)` changes are materialized into the schema snapshot and emitted as a SQLite table rebuild.
+
+For rebuilds that need help moving data, the preferred API is higher-level transform helpers:
+
+```ts
+import { transforms } from "@sedrino/db-schema";
+
+m.alterTable("account", (t) => {
+  t.string("slug")
+    .required()
+    .backfill(transforms.slugFrom("name"));
+
+  t.alterField("createdAt", (f) => {
+    f.temporalInstant().using(transforms.epochMsFromIsoString("createdAt"));
+  });
+});
+```
+
+The lower-level `backfillSql(...)` and `usingSql(...)` methods are still available when a migration needs a custom expression.
+
+Built-in helpers currently cover:
+
+- `transforms.copy("fieldName")`
+- `transforms.lowercase("fieldName")`
+- `transforms.trimmed("fieldName")`
+- `transforms.slugFrom("fieldName")`
+- `transforms.concatFields(["firstName", "lastName"], { separator: " " })`
+- `transforms.coalesceFields(["nickname", "name"], "Unknown")`
+- `transforms.epochMsFromIsoString("createdAt")`
+- `transforms.plainDateFromIsoString("birthday")`
+- `transforms.integerFromText("priority")`
+- `transforms.realFromText("amount")`
+
+The planner intentionally warns and blocks apply for cases that still do not have an explicit safe path, for example:
+
+- adding a required field without a default
+- changing the underlying storage strategy without `using(...)`
+
+## Table operations example
+
+```ts
+import { createMigration } from "@sedrino/db-schema";
+
+export default createMigration(
+  {
+    id: "2026-04-08-002-reshape-crm",
+    name: "Reshape CRM tables",
+  },
+  (m) => {
+    m.renameTable("account", "organization");
+
+    m.alterTable("contact", (t) => {
+      t.renameField("fullName", "displayName");
+      t.dropField("legacyNotes");
+      t.string("slug").required().backfill("lower(replace(trim(\"display_name\"), ' ', '-'))");
+      t.addIndex(["slug"], { name: "contact_slug_idx" });
+      t.addUnique(["organizationId", "email"], {
+        name: "contact_org_email_unique",
+      });
+    });
+  },
+);
+```
+
+## Relationship helpers
+
+The DSL now includes higher-level helpers for common relational patterns.
+
+### `belongsTo(...)`
+
+Use `belongsTo(...)` when a table owns a foreign key to another table:
+
+```ts
+m.createTable("contact", (t) => {
+  t.id("contactId", { prefix: "ct" });
+  t.belongsTo("account", {
+    required: true,
+    onDelete: "cascade",
+  });
+});
+```
+
+By default this:
+
+- creates a field like `accountId`
+- references `account.accountId`
+- can mark the field required or unique
+- adds a single-column index unless the relation is unique
+
+### `createJunctionTable(...)`
+
+Use `createJunctionTable(...)` for many-to-many structures:
+
+```ts
+m.createJunctionTable("userGroupMembership", {
+  left: { table: "user" },
+  right: { table: "group" },
+});
+```
+
+By default this:
+
+- creates required foreign keys like `userId` and `groupId`
+- adds indexes on both foreign key fields
+- adds a composite unique constraint across the pair
+- enables inferred Drizzle `through(...)` many-to-many relations
+
 ## Current v1 limits
 
-- no rebuild-aware SQL emission for destructive field changes
 - no composite primary keys
 - SQLite-only
+- destructive/shape-changing migrations are expressed as rebuilds rather than native `ALTER` operations

package/docs/planning-and-apply.md

@@ -0,0 +1,200 @@
+# Planning And Apply
+
+This guide covers the runtime-facing library APIs beyond the migration DSL itself.
+
+## Plan a single migration
+
+Use `planMigration(...)` when you already have a current schema and want:
+
+- the semantic operation list
+- the next schema snapshot
+- emitted SQLite statements
+- planner warnings
+
+```ts
+import { createMigration, planMigration } from "@sedrino/db-schema";
+
+const migration = createMigration(
+  {
+    id: "2026-04-08-001-add-slug",
+    name: "Add account slug",
+  },
+  (m) => {
+    m.alterTable("account", (t) => {
+      t.string("slug").required().backfill(`lower(replace(trim("name"), ' ', '-'))`);
+    });
+  },
+);
+
+const plan = planMigration({
+  currentSchema,
+  migration,
+});
+```
+
+## Materialize a whole migration chain
+
+Use `materializeSchema(...)` to replay every migration and get the current schema plus every intermediate plan:
+
+```ts
+import { materializeSchema } from "@sedrino/db-schema";
+
+const { schema, plans } = materializeSchema({
+  migrations,
+});
+```
+
+## Apply semantic operations directly
+
+If you already have a list of `MigrationOperation`s, use `applyOperationsToSchema(...)`:
+
+```ts
+import { applyOperationsToSchema } from "@sedrino/db-schema";
+
+const nextSchema = applyOperationsToSchema(currentSchema, operations);
+```
+
+## Emit SQLite directly
+
+The package can emit both full-schema DDL and incremental migration SQL:
+
+```ts
+import {
+  compileSchemaToSqlite,
+  createMigration,
+  materializeSchema,
+  renderSqliteMigration,
+} from "@sedrino/db-schema";
+
+const { schema } = materializeSchema({ migrations });
+const ddl = compileSchemaToSqlite(schema);
+
+const migration = createMigration(
+  {
+    id: "2026-04-08-002",
+    name: "Add slug",
+  },
+  (m) => {
+    m.alterTable("account", (t) => {
+      t.string("slug");
+    });
+  },
+);
+
+const sql = renderSqliteMigration(migration.buildOperations(), {
+  currentSchema: schema,
+});
+```
+
+## Emit Drizzle source
+
+Use `compileSchemaToDrizzle(...)` for full table + relation source, or `compileSchemaToDrizzleRelations(...)` for relations only:
+
+```ts
+import {
+  compileSchemaToDrizzle,
+  compileSchemaToDrizzleRelations,
+} from "@sedrino/db-schema";
+
+const source = compileSchemaToDrizzle(schema);
+const relationsOnly = compileSchemaToDrizzleRelations(schema);
+```
+
+## Apply migrations to libSQL or Turso
+
+Use `applyMigrations(...)` when you want the library to:
+
+- ensure metadata tables exist
+- compare local and database migration history
+- detect drift
+- apply pending migrations
+- persist the updated schema snapshot and schema hash
+
+```ts
+import { applyMigrations, createLibsqlClient } from "@sedrino/db-schema";
+
+const client = createLibsqlClient({
+  url: "file:./local.db",
+});
+
+const result = await applyMigrations({
+  client,
+  migrations,
+});
+```
+
+You can also pass `connection` instead of a prebuilt client:
+
+```ts
+await applyMigrations({
+  connection: {
+    url: process.env.LIBSQL_URL!,
+    authToken: process.env.LIBSQL_AUTH_TOKEN,
+  },
+  migrations,
+});
+```
+
+## Inspect migration status
+
+Use `inspectMigrationStatus(...)` for non-mutating status checks:
+
+```ts
+import { inspectMigrationStatus } from "@sedrino/db-schema";
+
+const status = await inspectMigrationStatus({
+  client,
+  migrations,
+});
+```
+
+The result includes:
+
+- local migration ids
+- applied migration ids
+- pending migration ids
+- unexpected database migration ids
+- local schema hash
+- database schema hash
+- drift status
+
+## Read metadata tables
+
+Lower-level helpers are available if you want the raw metadata state:
+
+```ts
+import { getSchemaState, listAppliedMigrations } from "@sedrino/db-schema";
+
+const applied = await listAppliedMigrations(client);
+const state = await getSchemaState(client);
+```
+
+## Project layout helpers
+
+For file-based projects, the package exports helpers around the default `db/` structure:
+
+```ts
+import {
+  loadMigrationDefinitionsFromDirectory,
+  materializeProjectMigrations,
+  resolveDbProjectLayout,
+  validateDbProject,
+  writeDrizzleSchema,
+  writeSchemaSnapshot,
+} from "@sedrino/db-schema";
+
+const layout = resolveDbProjectLayout("db");
+const migrations = await loadMigrationDefinitionsFromDirectory(layout.migrationsDir);
+const materialized = await materializeProjectMigrations(layout);
+const validation = await validateDbProject(layout);
+
+await writeSchemaSnapshot(materialized.schema, layout.snapshotPath);
+await writeDrizzleSchema(materialized.schema, layout.drizzlePath);
+```
+
+`validateDbProject(...)` is especially useful in CI because it tells you whether:
+
+- migrations are internally valid
+- the generated schema snapshot is up to date
+- the generated Drizzle source is up to date
+- planner warnings would block apply