@sedrino/db-schema 0.1.1 → 0.1.2

package/docs/relations.md

@@ -0,0 +1,130 @@
+# Drizzle Relations
+
+`@sedrino/db-schema` can emit Drizzle soft relations alongside generated table definitions.
+
+## What is inferred today
+
+From a field reference like this:
+
+```ts
+t.reference("accountId", {
+  references: {
+    table: "account",
+    field: "accountId",
+    onDelete: "cascade",
+  },
+}).required();
+```
+
+the generator emits:
+
+- a forward `r.one.account(...)` relation on the source table
+- a reverse relation on the target table
+  - `r.many.sourceTable(...)` by default
+  - `r.one.sourceTable(...)` when the foreign key field is unique
+
+## One-to-many example
+
+```ts
+import {
+  compileSchemaToDrizzle,
+  compileSchemaToDrizzleRelations,
+  createMigration,
+  materializeSchema,
+} from "@sedrino/db-schema";
+
+const { schema } = materializeSchema({
+  migrations: [
+    createMigration(
+      {
+        id: "2026-04-08-001",
+        name: "Create account and contact tables",
+      },
+      (m) => {
+        m.createTable("account", (t) => {
+          t.id("accountId", { prefix: "acct" });
+        });
+
+        m.createTable("contact", (t) => {
+          t.id("contactId", { prefix: "ct" });
+          t.belongsTo("account", { required: true });
+        });
+      },
+    ),
+  ],
+});
+
+const relationsSource = compileSchemaToDrizzleRelations(schema);
+const fullDrizzleSource = compileSchemaToDrizzle(schema);
+```
+
+## Duplicate relations
+
+If a table has multiple foreign keys to the same target table, the generator emits Drizzle relation aliases automatically.
+
+Example:
+
+- `post.authorId -> user.userId`
+- `post.reviewerId -> user.userId`
+
+becomes:
+
+- `post.author`
+- `post.reviewer`
+- `user.authorPosts`
+- `user.reviewerPosts`
+
+with matching Drizzle aliases.
+
+## Many-to-many junction tables
+
+`createJunctionTable(...)` enables inferred Drizzle `through(...)` relations for simple many-to-many join tables.
+
+Example:
+
+```ts
+import {
+  compileSchemaToDrizzleRelations,
+  createMigration,
+  materializeSchema,
+} from "@sedrino/db-schema";
+
+const { schema } = materializeSchema({
+  migrations: [
+    createMigration(
+      {
+        id: "2026-04-08-001",
+        name: "Create users, groups, and memberships",
+      },
+      (m) => {
+        m.createTable("user", (t) => {
+          t.id("userId", { prefix: "usr" });
+        });
+
+        m.createTable("group", (t) => {
+          t.id("groupId", { prefix: "grp" });
+        });
+
+        m.createJunctionTable("userGroupMembership", {
+          left: { table: "user" },
+          right: { table: "group" },
+        });
+      },
+    ),
+  ],
+});
+
+const relationsSource = compileSchemaToDrizzleRelations(schema);
+```
+
+This emits:
+
+- direct `r.one.user(...)` / `r.one.group(...)` relations on the junction table
+- a `user.groups` relation using `through(...)`
+- a `group.users` relation using `through(...)`
+
+## Current limits
+
+- junction-table inference expects a simple 2-column join table
+- composite primary keys are still not modeled directly in the schema document
+- advanced polymorphic `where` relations are not emitted yet

package/docs/schema-document.md

@@ -18,12 +18,38 @@ type DatabaseSchemaDocument = {
 };
 ```
 
+## Important helpers
+
+The schema module exports a few small helpers around the document:
+
+- `createEmptySchema()`
+- `parseSchemaDocument(...)`
+- `validateSchemaDocument(...)`
+- `assertValidSchemaDocument(...)`
+- `schemaHash(...)`
+- `findTable(...)`
+- `findField(...)`
+
+The package also exports the underlying runtime schemas:
+
+- `schemaDocumentSchema`
+- `tableSpecSchema`
+- `fieldSpecSchema`
+- `logicalTypeSpecSchema`
+- `storageSpecSchema`
+- `defaultSpecSchema`
+- `fieldReferenceSpecSchema`
+- `indexSpecSchema`
+- `uniqueSpecSchema`
+- `foreignKeyActionSchema`
+
 ## Important v1 ideas
 
 - The schema document is the materialized current-state snapshot.
 - Migrations are still the authored change history.
 - Logical types are higher-level than physical column types.
 - Storage strategies make the SQLite representation explicit.
+- Foreign-key references can also drive generated Drizzle soft relations.
 
 ## Example
 
@@ -46,3 +72,39 @@ That compiles to:
 - runtime semantics: `Temporal.Instant`
 - physical storage: `INTEGER`
 - Drizzle helper: `temporalInstantEpochMs("created_at")`
+
+## Validation example
+
+```ts
+import {
+  assertValidSchemaDocument,
+  schemaDocumentSchema,
+  schemaHash,
+  validateSchemaDocument,
+} from "@sedrino/db-schema";
+
+const result = validateSchemaDocument({
+  version: 1,
+  dialect: "sqlite",
+  schemaId: "crm",
+  tables: [],
+});
+
+if (result.issues.length > 0) {
+  throw new Error(`Schema is invalid: ${JSON.stringify(result.issues, null, 2)}`);
+}
+
+const schema = assertValidSchemaDocument(result.schema);
+const hash = schemaHash(schema);
+const parsedAgain = schemaDocumentSchema.parse(schema);
+```
+
+## Lookup example
+
+```ts
+import { createEmptySchema, findField, findTable } from "@sedrino/db-schema";
+
+const schema = createEmptySchema("crm");
+const accountTable = findTable(schema, "account");
+const createdAtField = accountTable ? findField(accountTable, "createdAt") : null;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sedrino/db-schema",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "publishConfig": {
     "access": "public"
   },
@@ -14,7 +14,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "sedrino-db": "./src/cli.ts"
+    "sedrino-db": "./dist/cli.js"
   },
   "files": [
     "dist",
@@ -26,6 +26,7 @@
     "clean": "rm -rf dist",
     "build": "bun run clean && tsup",
     "test": "bun test",
+    "test:coverage": "bun test --coverage",
     "typecheck": "bunx -p @typescript/native-preview tsc --noEmit",
     "test:all": "bun test && bunx -p @typescript/native-preview tsc --noEmit"
   },

package/src/apply.ts

@@ -21,6 +21,19 @@ export type ApplyMigrationsResult = {
   currentSchemaHash: string;
 };
 
+export type MigrationStatusResult = {
+  localMigrationIds: string[];
+  appliedMigrationIds: string[];
+  pendingMigrationIds: string[];
+  unexpectedDatabaseMigrationIds: string[];
+  schemaHash: {
+    local: string;
+    database: string | null;
+    driftDetected: boolean;
+  };
+  metadataTablesPresent: boolean;
+};
+
 export type LibsqlConnectionOptions = {
   url: string;
   authToken?: string;
@@ -126,6 +139,44 @@ export async function listAppliedMigrations(client: Client) {
   }));
 }
 
+export async function inspectMigrationStatus(args: {
+  client?: Client;
+  connection?: LibsqlConnectionOptions;
+  migrations: MigrationDefinition[];
+  baseSchema?: DatabaseSchemaDocument;
+}) {
+  const client = args.client ?? createLibsqlClient(assertConnection(args.connection));
+  const metadataTablesPresent = await hasMetadataTables(client);
+  const appliedRows = metadataTablesPresent ? await listAppliedMigrations(client) : [];
+  const appliedIds = new Set(appliedRows.map((row) => row.migrationId));
+  const localMigrationIds = args.migrations.map((migration) => migration.meta.id);
+  const pendingMigrationIds = localMigrationIds.filter((id) => !appliedIds.has(id));
+  const unexpectedDatabaseMigrationIds = appliedRows
+    .map((row) => row.migrationId)
+    .filter((id) => !localMigrationIds.includes(id));
+  const appliedLocalMigrations = args.migrations.filter((migration) => appliedIds.has(migration.meta.id));
+  const expectedCurrent = materializeSchema({
+    baseSchema: args.baseSchema,
+    migrations: appliedLocalMigrations,
+  }).schema;
+  const currentState = metadataTablesPresent ? await getSchemaState(client) : null;
+  const localSchemaHash = schemaHash(expectedCurrent);
+  const databaseSchemaHash = currentState?.schemaHash ?? null;
+
+  return {
+    localMigrationIds,
+    appliedMigrationIds: appliedRows.map((row) => row.migrationId),
+    pendingMigrationIds,
+    unexpectedDatabaseMigrationIds,
+    schemaHash: {
+      local: localSchemaHash,
+      database: databaseSchemaHash,
+      driftDetected: databaseSchemaHash !== null && databaseSchemaHash !== localSchemaHash,
+    },
+    metadataTablesPresent,
+  } satisfies MigrationStatusResult;
+}
+
 export async function getSchemaState(client: Client): Promise<SchemaStateRow | null> {
   const result = await client.execute(
     `SELECT schema_hash, schema_json
@@ -172,6 +223,22 @@ async function ensureMetadataTables(client: Client) {
   );
 }
 
+async function hasMetadataTables(client: Client) {
+  const result = await client.execute({
+    sql: `SELECT name FROM sqlite_master
+          WHERE type = 'table' AND name IN (?, ?)`,
+    args: [MIGRATIONS_TABLE, STATE_TABLE],
+  });
+
+  const names = new Set(
+    (result.rows as Array<Record<string, unknown>>)
+      .map((row) => getString(row.name))
+      .filter((value): value is string => value !== null),
+  );
+
+  return names.has(MIGRATIONS_TABLE) && names.has(STATE_TABLE);
+}
+
 async function executePlan(client: Client, plan: PlannedMigration) {
   const appliedAt = Date.now();
   const statements: Array<string | { sql: string; args: SqlValue[] }> = [

package/src/cli.ts

@@ -1,12 +1,12 @@
-#!/usr/bin/env bun
-
 import path from "node:path";
 import { env, exit } from "node:process";
 import { compileSchemaToDrizzle } from "./drizzle";
-import { applyMigrations, createLibsqlClient } from "./apply";
+import { applyMigrations, createLibsqlClient, inspectMigrationStatus } from "./apply";
 import {
+  createMigrationScaffold,
   materializeProjectMigrations,
   resolveDbProjectLayout,
+  validateDbProject,
   writeDrizzleSchema,
   writeSchemaSnapshot,
 } from "./project";
@@ -29,9 +29,18 @@ async function main() {
     case "migrate plan":
       await handleMigratePlan(args);
       return;
+    case "migrate create":
+      await handleMigrateCreate(args);
+      return;
     case "migrate apply":
       await handleMigrateApply(args);
       return;
+    case "migrate validate":
+      await handleMigrateValidate(args);
+      return;
+    case "migrate status":
+      await handleMigrateStatus(args);
+      return;
     case "schema print":
       await handleSchemaPrint(args);
       return;
@@ -46,9 +55,11 @@ async function main() {
 async function handleMigratePlan(args: ParsedArgs) {
   const layout = resolveLayoutFromArgs(args);
   const { schema, plans } = await materializeProjectMigrations(layout);
+  const snapshotPath = path.resolve(getStringOption(args, "snapshot") ?? layout.snapshotPath);
+  const drizzleOutputPath = path.resolve(getStringOption(args, "drizzle-out") ?? layout.drizzlePath);
 
-  await writeSchemaSnapshot(schema, getStringOption(args, "snapshot") ?? layout.snapshotPath);
-  await writeDrizzleSchema(schema, getStringOption(args, "drizzle-out") ?? layout.drizzlePath);
+  await writeSchemaSnapshot(schema, snapshotPath);
+  await writeDrizzleSchema(schema, drizzleOutputPath);
 
   const warnings = plans.flatMap((plan) =>
     plan.sql.warnings.map((warning) => `${plan.migrationId}: ${warning}`),
@@ -56,8 +67,8 @@ async function handleMigratePlan(args: ParsedArgs) {
   const statementCount = plans.reduce((total, plan) => total + plan.sql.statements.length, 0);
 
   console.log(`Planned ${plans.length} migration(s)`);
-  console.log(`Schema snapshot: ${layout.snapshotPath}`);
-  console.log(`Drizzle output: ${layout.drizzlePath}`);
+  console.log(`Schema snapshot: ${snapshotPath}`);
+  console.log(`Drizzle output: ${drizzleOutputPath}`);
   console.log(`SQL statements: ${statementCount}`);
   console.log(`Schema hash: ${plans.at(-1)?.toSchemaHash ?? "schema_00000000"}`);
 
@@ -80,6 +91,21 @@ async function handleMigratePlan(args: ParsedArgs) {
   }
 }
 
+async function handleMigrateCreate(args: ParsedArgs) {
+  const layout = resolveLayoutFromArgs(args);
+  const rawName = args.positionals.slice(2).join(" ").trim();
+
+  if (!rawName) {
+    throw new Error("Missing migration name. Usage: sedrino-db migrate create <name> [--dir db]");
+  }
+
+  const created = await createMigrationScaffold(layout, rawName);
+
+  console.log(`Created migration: ${created.filePath}`);
+  console.log(`Migration id: ${created.migrationId}`);
+  console.log(`Migration name: ${created.migrationName}`);
+}
+
 async function handleMigrateApply(args: ParsedArgs) {
   const layout = resolveLayoutFromArgs(args);
   const { migrations } = await materializeProjectMigrations(layout);
@@ -117,6 +143,75 @@ async function handleMigrateApply(args: ParsedArgs) {
   }
 }
 
+async function handleMigrateValidate(args: ParsedArgs) {
+  const layout = resolveLayoutFromArgs(args);
+  const result = await validateDbProject(layout);
+
+  console.log(`Validated ${result.migrations.length} migration(s)`);
+  console.log(`Schema hash: ${result.plans.at(-1)?.toSchemaHash ?? "schema_00000000"}`);
+  console.log(`Snapshot up to date: ${result.artifacts.snapshotUpToDate ? "yes" : "no"}`);
+  console.log(`Drizzle output up to date: ${result.artifacts.drizzleUpToDate ? "yes" : "no"}`);
+
+  if (result.warnings.length > 0) {
+    console.log("");
+    console.log("Warnings:");
+    for (const warning of result.warnings) console.log(`- ${warning}`);
+  }
+
+  const hasIssues =
+    result.warnings.length > 0 ||
+    !result.artifacts.snapshotUpToDate ||
+    !result.artifacts.drizzleUpToDate;
+
+  if (hasIssues) {
+    exit(1);
+  }
+}
+
+async function handleMigrateStatus(args: ParsedArgs) {
+  const layout = resolveLayoutFromArgs(args);
+  const { migrations, plans } = await materializeProjectMigrations(layout);
+  console.log(`Local migrations: ${migrations.length}`);
+  console.log(`Local schema hash: ${plans.at(-1)?.toSchemaHash ?? "schema_00000000"}`);
+
+  const url = getStringOption(args, "url") ?? env.LIBSQL_URL;
+  const authToken = getStringOption(args, "auth-token") ?? env.LIBSQL_AUTH_TOKEN;
+  if (!url) {
+    return;
+  }
+
+  const status = await inspectMigrationStatus({
+    client: createLibsqlClient({ url, authToken }),
+    migrations,
+    baseSchema: undefined,
+  });
+
+  console.log(`Metadata tables present: ${status.metadataTablesPresent ? "yes" : "no"}`);
+  console.log(`Applied in database: ${status.appliedMigrationIds.length}`);
+  console.log(`Pending locally: ${status.pendingMigrationIds.length}`);
+  console.log(`Unexpected in database: ${status.unexpectedDatabaseMigrationIds.length}`);
+  console.log(
+    `Database schema hash: ${status.schemaHash.database ?? (status.metadataTablesPresent ? "missing" : "none")}`,
+  );
+  console.log(`Drift detected: ${status.schemaHash.driftDetected ? "yes" : "no"}`);
+
+  if (status.pendingMigrationIds.length > 0) {
+    console.log("");
+    console.log("Pending:");
+    for (const migrationId of status.pendingMigrationIds) console.log(`- ${migrationId}`);
+  }
+
+  if (status.unexpectedDatabaseMigrationIds.length > 0) {
+    console.log("");
+    console.log("Unexpected in database:");
+    for (const migrationId of status.unexpectedDatabaseMigrationIds) console.log(`- ${migrationId}`);
+  }
+
+  if (status.schemaHash.driftDetected || status.unexpectedDatabaseMigrationIds.length > 0) {
+    exit(1);
+  }
+}
+
 async function handleSchemaPrint(args: ParsedArgs) {
   const layout = resolveLayoutFromArgs(args);
   const { schema } = await materializeProjectMigrations(layout);
@@ -190,8 +285,11 @@ function printHelp() {
   console.log(`sedrino-db
 
 Usage:
+  sedrino-db migrate create <name> [--dir db]
   sedrino-db migrate plan [--dir db] [--sql] [--snapshot path] [--drizzle-out path]
   sedrino-db migrate apply --url <libsql-url> [--auth-token token] [--dir db]
+  sedrino-db migrate validate [--dir db]
+  sedrino-db migrate status [--dir db] [--url <libsql-url>] [--auth-token token]
   sedrino-db schema print [--dir db]
   sedrino-db schema drizzle [--dir db] [--out path]