@sedrino/db-schema 0.1.1

package/src/apply.ts

@@ -0,0 +1,234 @@
+import { createClient, type Client } from "@libsql/client";
+import type { DatabaseSchemaDocument } from "./types";
+import type { MigrationDefinition } from "./migration";
+import { materializeSchema, planMigration, type PlannedMigration } from "./planner";
+import { schemaHash } from "./schema";
+
+const MIGRATIONS_TABLE = "_sedrino_schema_migrations";
+const STATE_TABLE = "_sedrino_schema_state";
+
+type SqlValue = string | number | null;
+
+type SchemaStateRow = {
+  schemaHash: string;
+  schemaJson: string;
+};
+
+export type ApplyMigrationsResult = {
+  appliedPlans: PlannedMigration[];
+  skippedMigrationIds: string[];
+  currentSchema: DatabaseSchemaDocument;
+  currentSchemaHash: string;
+};
+
+export type LibsqlConnectionOptions = {
+  url: string;
+  authToken?: string;
+};
+
+export function createLibsqlClient(options: LibsqlConnectionOptions) {
+  return createClient({
+    url: options.url,
+    authToken: options.authToken,
+    concurrency: 0,
+  });
+}
+
+export async function applyMigrations(args: {
+  client?: Client;
+  connection?: LibsqlConnectionOptions;
+  migrations: MigrationDefinition[];
+  baseSchema?: DatabaseSchemaDocument;
+}) {
+  const client = args.client ?? createLibsqlClient(assertConnection(args.connection));
+
+  await ensureMetadataTables(client);
+
+  const appliedRows = await listAppliedMigrations(client);
+  const appliedIds = new Set(appliedRows.map((row) => row.migrationId));
+  const migrationMap = new Map(args.migrations.map((migration) => [migration.meta.id, migration]));
+
+  for (const applied of appliedRows) {
+    if (!migrationMap.has(applied.migrationId)) {
+      throw new Error(
+        `Database contains applied migration ${applied.migrationId}, but it is not present locally`,
+      );
+    }
+  }
+
+  const appliedLocalMigrations = args.migrations.filter((migration) =>
+    appliedIds.has(migration.meta.id),
+  );
+  const expectedCurrent = materializeSchema({
+    baseSchema: args.baseSchema,
+    migrations: appliedLocalMigrations,
+  }).schema;
+  const expectedHash = schemaHash(expectedCurrent);
+  const currentState = await getSchemaState(client);
+
+  if (currentState) {
+    if (currentState.schemaHash !== expectedHash) {
+      throw new Error(
+        `Schema drift detected. Database hash ${currentState.schemaHash} does not match expected local hash ${expectedHash}`,
+      );
+    }
+  } else if (appliedRows.length > 0) {
+    throw new Error(
+      `Database has applied migrations recorded in ${MIGRATIONS_TABLE} but is missing ${STATE_TABLE}`,
+    );
+  }
+
+  const pendingMigrations = args.migrations.filter(
+    (migration) => !appliedIds.has(migration.meta.id),
+  );
+  const appliedPlans: PlannedMigration[] = [];
+  let currentSchema = expectedCurrent;
+
+  for (const migration of pendingMigrations) {
+    const plan = planMigration({
+      currentSchema,
+      migration,
+    });
+
+    if (plan.sql.warnings.length > 0) {
+      throw new Error(
+        `Migration ${plan.migrationId} cannot be applied safely:\n${plan.sql.warnings
+          .map((warning) => `- ${warning}`)
+          .join("\n")}`,
+      );
+    }
+
+    await executePlan(client, plan);
+    currentSchema = plan.nextSchema;
+    appliedPlans.push(plan);
+  }
+
+  return {
+    appliedPlans,
+    skippedMigrationIds: appliedLocalMigrations.map((migration) => migration.meta.id),
+    currentSchema,
+    currentSchemaHash: schemaHash(currentSchema),
+  } satisfies ApplyMigrationsResult;
+}
+
+export async function listAppliedMigrations(client: Client) {
+  const result = await client.execute(
+    `SELECT migration_id, migration_name, schema_hash, applied_at
+     FROM ${MIGRATIONS_TABLE}
+     ORDER BY applied_at ASC, migration_id ASC`,
+  );
+
+  return (result.rows as Array<Record<string, unknown>>).map((row) => ({
+    migrationId: getString(row.migration_id) ?? "",
+    migrationName: getString(row.migration_name) ?? "",
+    schemaHash: getString(row.schema_hash) ?? "",
+    appliedAt: getNumber(row.applied_at) ?? 0,
+  }));
+}
+
+export async function getSchemaState(client: Client): Promise<SchemaStateRow | null> {
+  const result = await client.execute(
+    `SELECT schema_hash, schema_json
+     FROM ${STATE_TABLE}
+     WHERE singleton_id = 1`,
+  );
+
+  const row = (result.rows as Array<Record<string, unknown>>)[0];
+  if (!row) return null;
+
+  const schemaHashValue = getString(row.schema_hash);
+  const schemaJsonValue = getString(row.schema_json);
+  if (!schemaHashValue || !schemaJsonValue) return null;
+
+  return {
+    schemaHash: schemaHashValue,
+    schemaJson: schemaJsonValue,
+  };
+}
+
+async function ensureMetadataTables(client: Client) {
+  await client.batch(
+    [
+      "PRAGMA foreign_keys = ON",
+      `
+        CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
+          migration_id TEXT PRIMARY KEY,
+          migration_name TEXT NOT NULL,
+          schema_hash TEXT NOT NULL,
+          applied_at INTEGER NOT NULL,
+          sql_statements_json TEXT NOT NULL
+        )
+      `,
+      `
+        CREATE TABLE IF NOT EXISTS ${STATE_TABLE} (
+          singleton_id INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+          schema_hash TEXT NOT NULL,
+          schema_json TEXT NOT NULL,
+          updated_at INTEGER NOT NULL
+        )
+      `,
+    ],
+    "write",
+  );
+}
+
+async function executePlan(client: Client, plan: PlannedMigration) {
+  const appliedAt = Date.now();
+  const statements: Array<string | { sql: string; args: SqlValue[] }> = [
+    ...plan.sql.statements,
+    {
+      sql: `INSERT INTO ${MIGRATIONS_TABLE} (
+              migration_id,
+              migration_name,
+              schema_hash,
+              applied_at,
+              sql_statements_json
+            ) VALUES (?, ?, ?, ?, ?)`,
+      args: [
+        plan.migrationId,
+        plan.migrationName,
+        plan.toSchemaHash,
+        appliedAt,
+        JSON.stringify(plan.sql.statements),
+      ],
+    },
+    {
+      sql: `INSERT INTO ${STATE_TABLE} (
+              singleton_id,
+              schema_hash,
+              schema_json,
+              updated_at
+            ) VALUES (1, ?, ?, ?)
+            ON CONFLICT(singleton_id) DO UPDATE SET
+              schema_hash = excluded.schema_hash,
+              schema_json = excluded.schema_json,
+              updated_at = excluded.updated_at`,
+      args: [plan.toSchemaHash, JSON.stringify(plan.nextSchema), appliedAt],
+    },
+  ];
+
+  await client.batch(statements, "write");
+}
+
+function assertConnection(
+  connection: LibsqlConnectionOptions | undefined,
+): LibsqlConnectionOptions {
+  if (!connection?.url) {
+    throw new Error("Missing database connection. Provide --url or pass a connection object.");
+  }
+  return connection;
+}
+
+function getString(value: unknown) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function getNumber(value: unknown) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}

package/src/cli.ts

@@ -0,0 +1,209 @@
+#!/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 {
+  materializeProjectMigrations,
+  resolveDbProjectLayout,
+  writeDrizzleSchema,
+  writeSchemaSnapshot,
+} from "./project";
+
+type ParsedArgs = {
+  positionals: string[];
+  options: Map<string, string | boolean>;
+};
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const [group, command] = args.positionals;
+
+  if (!group || group === "help" || hasFlag(args, "help")) {
+    printHelp();
+    return;
+  }
+
+  switch (`${group} ${command ?? ""}`.trim()) {
+    case "migrate plan":
+      await handleMigratePlan(args);
+      return;
+    case "migrate apply":
+      await handleMigrateApply(args);
+      return;
+    case "schema print":
+      await handleSchemaPrint(args);
+      return;
+    case "schema drizzle":
+      await handleSchemaDrizzle(args);
+      return;
+    default:
+      throw new Error(`Unknown command: ${[group, command].filter(Boolean).join(" ")}`);
+  }
+}
+
+async function handleMigratePlan(args: ParsedArgs) {
+  const layout = resolveLayoutFromArgs(args);
+  const { schema, plans } = await materializeProjectMigrations(layout);
+
+  await writeSchemaSnapshot(schema, getStringOption(args, "snapshot") ?? layout.snapshotPath);
+  await writeDrizzleSchema(schema, getStringOption(args, "drizzle-out") ?? layout.drizzlePath);
+
+  const warnings = plans.flatMap((plan) =>
+    plan.sql.warnings.map((warning) => `${plan.migrationId}: ${warning}`),
+  );
+  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(`SQL statements: ${statementCount}`);
+  console.log(`Schema hash: ${plans.at(-1)?.toSchemaHash ?? "schema_00000000"}`);
+
+  if (warnings.length > 0) {
+    console.log("");
+    console.log("Warnings:");
+    for (const warning of warnings) console.log(`- ${warning}`);
+  }
+
+  if (hasFlag(args, "sql")) {
+    console.log("");
+    for (const plan of plans) {
+      console.log(`# ${plan.migrationId} ${plan.migrationName}`);
+      for (const statement of plan.sql.statements) console.log(statement);
+      if (plan.sql.warnings.length > 0) {
+        for (const warning of plan.sql.warnings) console.log(`-- warning: ${warning}`);
+      }
+      console.log("");
+    }
+  }
+}
+
+async function handleMigrateApply(args: ParsedArgs) {
+  const layout = resolveLayoutFromArgs(args);
+  const { migrations } = await materializeProjectMigrations(layout);
+  const url = getStringOption(args, "url") ?? env.LIBSQL_URL;
+  const authToken = getStringOption(args, "auth-token") ?? env.LIBSQL_AUTH_TOKEN;
+
+  if (!url) {
+    throw new Error("Missing database URL. Use --url or set LIBSQL_URL.");
+  }
+
+  const result = await applyMigrations({
+    client: createLibsqlClient({ url, authToken }),
+    migrations,
+  });
+
+  await writeSchemaSnapshot(
+    result.currentSchema,
+    getStringOption(args, "snapshot") ?? layout.snapshotPath,
+  );
+  await writeDrizzleSchema(
+    result.currentSchema,
+    getStringOption(args, "drizzle-out") ?? layout.drizzlePath,
+  );
+
+  console.log(`Applied ${result.appliedPlans.length} migration(s)`);
+  console.log(`Skipped ${result.skippedMigrationIds.length} already-applied migration(s)`);
+  console.log(`Current schema hash: ${result.currentSchemaHash}`);
+
+  if (result.appliedPlans.length > 0) {
+    console.log("");
+    console.log("Applied:");
+    for (const plan of result.appliedPlans) {
+      console.log(`- ${plan.migrationId} (${plan.sql.statements.length} statement(s))`);
+    }
+  }
+}
+
+async function handleSchemaPrint(args: ParsedArgs) {
+  const layout = resolveLayoutFromArgs(args);
+  const { schema } = await materializeProjectMigrations(layout);
+  console.log(JSON.stringify(schema, null, 2));
+}
+
+async function handleSchemaDrizzle(args: ParsedArgs) {
+  const layout = resolveLayoutFromArgs(args);
+  const { schema } = await materializeProjectMigrations(layout);
+  const source = compileSchemaToDrizzle(schema);
+  const outputPath = getStringOption(args, "out");
+
+  if (outputPath) {
+    await writeDrizzleSchema(schema, path.resolve(outputPath));
+    console.log(`Wrote Drizzle schema to ${path.resolve(outputPath)}`);
+    return;
+  }
+
+  process.stdout.write(source);
+}
+
+function resolveLayoutFromArgs(args: ParsedArgs) {
+  return resolveDbProjectLayout(getStringOption(args, "dir") ?? "db");
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const positionals: string[] = [];
+  const options = new Map<string, string | boolean>();
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index]!;
+    if (!value.startsWith("--")) {
+      positionals.push(value);
+      continue;
+    }
+
+    const withoutPrefix = value.slice(2);
+    const [rawKey, inlineValue] = withoutPrefix.split("=", 2);
+    const key = rawKey ?? "";
+    if (inlineValue !== undefined) {
+      options.set(key, inlineValue);
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      options.set(key, next);
+      index += 1;
+      continue;
+    }
+
+    options.set(key, true);
+  }
+
+  return {
+    positionals,
+    options,
+  };
+}
+
+function hasFlag(args: ParsedArgs, name: string) {
+  return args.options.get(name) === true;
+}
+
+function getStringOption(args: ParsedArgs, name: string) {
+  const value = args.options.get(name);
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function printHelp() {
+  console.log(`sedrino-db
+
+Usage:
+  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 schema print [--dir db]
+  sedrino-db schema drizzle [--dir db] [--out path]
+
+Defaults:
+  --dir defaults to ./db
+  schema snapshot defaults to ./db/schema/schema.snapshot.json
+  drizzle output defaults to ./db/schema/schema.generated.ts
+`);
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  exit(1);
+});

package/src/drizzle.ts

@@ -0,0 +1,178 @@
+import type {
+  DatabaseSchemaDocument,
+  DefaultSpec,
+  FieldSpec,
+  IndexSpec,
+  TableSpec,
+  UniqueSpec,
+} from "./types";
+import { tableVariableName, toPascalCase } from "./utils";
+
+export function compileSchemaToDrizzle(schema: DatabaseSchemaDocument) {
+  const sqliteImports = new Set(["sqliteTable"]);
+  const toolkitImports = new Set<string>();
+  let needsUlid = false;
+
+  for (const table of schema.tables) {
+    for (const field of table.fields) {
+      switch (field.logical.kind) {
+        case "id":
+        case "string":
+        case "text":
+        case "enum":
+        case "json":
+          sqliteImports.add("text");
+          break;
+        case "boolean":
+        case "integer":
+          sqliteImports.add("integer");
+          break;
+        case "number":
+          sqliteImports.add("real");
+          break;
+        case "temporal.instant":
+          toolkitImports.add("temporalInstantEpochMs");
+          break;
+        case "temporal.plainDate":
+          toolkitImports.add("temporalPlainDateText");
+          break;
+      }
+
+      if (field.default?.kind === "generatedId") needsUlid = true;
+      if (field.default?.kind === "now") toolkitImports.add("epochMsNow");
+    }
+
+    if (table.indexes.length > 0) sqliteImports.add("index");
+    if (table.uniques.length > 0) sqliteImports.add("uniqueIndex");
+  }
+
+  const lines: string[] = [];
+  lines.push(
+    `import { ${Array.from(sqliteImports).sort().join(", ")} } from "drizzle-orm/sqlite-core";`,
+  );
+  if (toolkitImports.size > 0) {
+    lines.push(
+      `import { ${Array.from(toolkitImports).sort().join(", ")} } from "@sedrino/toolkit/drizzle/sqlite";`,
+    );
+  }
+  if (needsUlid) {
+    lines.push(`import { ulid } from "ulid";`);
+  }
+  lines.push("");
+
+  for (const table of schema.tables) {
+    lines.push(renderTable(table));
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+function renderTable(table: TableSpec) {
+  const variableName = tableVariableName(table.name);
+  const fieldLines = table.fields.map((field) => `  ${field.name}: ${renderField(field)},`);
+  const tableConfig = renderTableConfig(table);
+
+  if (!tableConfig) {
+    return `export const ${variableName} = sqliteTable("${table.name}", {\n${fieldLines.join("\n")}\n});`;
+  }
+
+  return `export const ${variableName} = sqliteTable("${table.name}", {\n${fieldLines.join(
+    "\n",
+  )}\n}, (table) => [\n${tableConfig}\n]);`;
+}
+
+function renderTableConfig(table: TableSpec) {
+  const lines: string[] = [];
+
+  for (const index of table.indexes) {
+    lines.push(`  ${renderIndex(table.name, index)},`);
+  }
+
+  for (const unique of table.uniques) {
+    lines.push(`  ${renderUnique(table.name, unique)},`);
+  }
+
+  return lines.length > 0 ? lines.join("\n") : null;
+}
+
+function renderIndex(tableName: string, index: IndexSpec) {
+  const name = index.name ?? `${tableName}_${index.fields.join("_")}_idx`;
+  return `index("${name}").on(${index.fields.map((field) => `table.${field}`).join(", ")})`;
+}
+
+function renderUnique(tableName: string, unique: UniqueSpec) {
+  const name = unique.name ?? `${tableName}_${unique.fields.join("_")}_unique`;
+  return `uniqueIndex("${name}").on(${unique.fields.map((field) => `table.${field}`).join(", ")})`;
+}
+
+function renderField(field: FieldSpec) {
+  let expression = renderBaseColumn(field);
+
+  if (field.logical.kind === "json") {
+    expression += `.$type<${field.logical.tsType}>()`;
+  }
+
+  if (field.primaryKey) expression += ".primaryKey()";
+  if (!field.nullable) expression += ".notNull()";
+  if (field.unique && !field.primaryKey) expression += ".unique()";
+
+  const defaultExpression = renderDrizzleDefault(field.default);
+  if (defaultExpression) expression += `.default(${defaultExpression})`;
+
+  if (field.default?.kind === "generatedId") {
+    expression += `.$default(() => \`${field.default.prefix}-\${ulid()}\`)`;
+  }
+
+  if (field.references) {
+    const targetTable = tableVariableName(field.references.table);
+    const referenceParts = [`() => ${targetTable}.${field.references.field}`];
+    const options: string[] = [];
+    if (field.references.onDelete) options.push(`onDelete: "${field.references.onDelete}"`);
+    if (field.references.onUpdate) options.push(`onUpdate: "${field.references.onUpdate}"`);
+    if (options.length > 0) {
+      referenceParts.push(`{ ${options.join(", ")} }`);
+    }
+    expression += `.references(${referenceParts.join(", ")})`;
+  }
+
+  return expression;
+}
+
+function renderBaseColumn(field: FieldSpec) {
+  switch (field.logical.kind) {
+    case "id":
+    case "string":
+    case "text":
+      return `text("${field.storage.column}")`;
+    case "enum":
+      return `text("${field.storage.column}", { enum: [${field.logical.values
+        .map((value) => JSON.stringify(value))
+        .join(", ")}] })`;
+    case "json":
+      return `text("${field.storage.column}", { mode: "json" })`;
+    case "boolean":
+      return `integer("${field.storage.column}", { mode: "boolean" })`;
+    case "integer":
+      return `integer("${field.storage.column}", { mode: "number" })`;
+    case "number":
+      return `real("${field.storage.column}")`;
+    case "temporal.instant":
+      return `temporalInstantEpochMs("${field.storage.column}")`;
+    case "temporal.plainDate":
+      return `temporalPlainDateText("${field.storage.column}")`;
+  }
+}
+
+function renderDrizzleDefault(defaultValue: DefaultSpec | undefined) {
+  if (!defaultValue) return null;
+
+  switch (defaultValue.kind) {
+    case "generatedId":
+      return null;
+    case "now":
+      return "epochMsNow()";
+    case "literal":
+      return JSON.stringify(defaultValue.value);
+  }
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+export {
+  type DatabaseSchemaDocument,
+  type DefaultSpec,
+  type FieldReferenceSpec,
+  type FieldSpec,
+  type ForeignKeyAction,
+  type IndexSpec,
+  type LogicalTypeSpec,
+  type SchemaValidationIssue,
+  type StorageSpec,
+  type TableSpec,
+  type UniqueSpec,
+  defaultSpecSchema,
+  fieldReferenceSpecSchema,
+  fieldSpecSchema,
+  foreignKeyActionSchema,
+  indexSpecSchema,
+  logicalTypeSpecSchema,
+  schemaDocumentSchema,
+  storageSpecSchema,
+  tableSpecSchema,
+  uniqueSpecSchema,
+} from "./types";
+export {
+  type MigrationDefinition,
+  type MigrationMeta,
+  type MigrationOperation,
+  createMigration,
+} from "./migration";
+export {
+  type PlannedMigration,
+  applyOperationsToSchema,
+  materializeSchema,
+  planMigration,
+} from "./planner";
+export { compileSchemaToDrizzle } from "./drizzle";
+export { compileSchemaToSqlite, renderSqliteMigration } from "./sqlite";
+export {
+  type ApplyMigrationsResult,
+  type LibsqlConnectionOptions,
+  applyMigrations,
+  createLibsqlClient,
+  getSchemaState,
+  listAppliedMigrations,
+} from "./apply";
+export {
+  type DbProjectLayout,
+  loadMigrationDefinitionsFromDirectory,
+  materializeProjectMigrations,
+  resolveDbProjectLayout,
+  writeDrizzleSchema,
+  writeSchemaSnapshot,
+} from "./project";
+export {
+  assertValidSchemaDocument,
+  createEmptySchema,
+  findField,
+  findTable,
+  parseSchemaDocument,
+  schemaHash,
+  validateSchemaDocument,
+} from "./schema";