@sedrino/db-schema 0.1.1 → 0.1.2

package/README.md

@@ -15,8 +15,9 @@ The first version focuses on the planning layer:
 - versioned schema document types
 - migration DSL with deterministic operation recording
 - schema materialization from migration history
-- SQLite DDL emission
+- rebuild-aware SQLite migration emission for supported table-shape changes
 - Drizzle source generation for a narrow SQLite + Temporal-aware subset
+- inferred Drizzle soft-relations generation from foreign keys
 - a libSQL-compatible apply runner with migration/state metadata tables
 - a Bun-first CLI for planning migrations, applying them, and emitting schema artifacts
 
@@ -26,14 +27,12 @@ The first version focuses on the planning layer:
 bun add @sedrino/db-schema
 ```
 
+The CLI is Bun-first. If you want to run `sedrino-db`, make sure `bun` is available on `PATH`.
+
 ## Example
 
 ```ts
-import {
-  compileSchemaToDrizzle,
-  createMigration,
-  planMigration,
-} from "@sedrino/db-schema";
+import { compileSchemaToDrizzle, createMigration, planMigration } from "@sedrino/db-schema";
 
 const migration = createMigration(
   {
@@ -53,17 +52,74 @@ const plan = planMigration({ migration });
 const drizzleSource = compileSchemaToDrizzle(plan.nextSchema);
 ```
 
+## Supported migration operations
+
+- create, drop, and rename tables
+- add, drop, rename, and alter fields
+- add and drop indexes
+- add and drop unique indexes
+
+The builder also supports higher-level relationship helpers:
+
+- `belongsTo("table", ...)` for indexed foreign keys
+- `createJunctionTable(...)` for many-to-many join tables with composite uniqueness and inferred `through(...)` relations
+
+For SQLite safety, field adds, drops, and supported field alterations are emitted as table rebuilds.
+Unsafe cases still produce planner warnings and `migrate apply` will refuse to run them.
+
+When a rebuild needs help populating 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"));
+  });
+});
+```
+
+Raw `backfillSql(...)` and `usingSql(...)` are still available as escape hatches.
+
+Relationship helpers look like:
+
+```ts
+m.createTable("contact", (t) => {
+  t.id("contactId", { prefix: "ct" });
+  t.belongsTo("account", {
+    required: true,
+    onDelete: "cascade",
+  });
+});
+
+m.createJunctionTable("userGroupMembership", {
+  left: { table: "user" },
+  right: { table: "group" },
+});
+```
+
 ## Docs
 
 - `docs/index.md`
 - `docs/schema-document.md`
 - `docs/migrations.md`
+- `docs/planning-and-apply.md`
+- `docs/expressions-and-transforms.md`
+- `docs/relations.md`
+- `docs/cli.md`
 
 ## CLI
 
 ```bash
+sedrino-db migrate create create-account --dir db
 sedrino-db migrate plan --dir db
 sedrino-db migrate apply --dir db --url file:./local.db
+sedrino-db migrate validate --dir db
+sedrino-db migrate status --dir db --url file:./local.db
 sedrino-db schema print --dir db
 sedrino-db schema drizzle --dir db --out db/schema/schema.generated.ts
 ```