Library API

Use the library API when you want supaschema behavior inside your own script, test, or tool. Everything the CLI does is available as typed ESM exports.

import {
  extractSourceModel, // any source prefix -> SchemaModel
  extractCatalogModel, // live pg_catalog -> SchemaModel
  planSchemaDiff, // two models -> MigrationPlan
  renderMigrationSplit, // plan -> { sql, concurrentSql? }
  checkMigrationSql, // SQL -> replay-safety diagnostics
  verifyMigration, // apply-twice + reconvergence proof
  migrationsStatus, // disk files vs applied history
  compareMigrationHistory, // expected vs applied version sets
  runDirectMigrationRunner, // provider-neutral PostgreSQL apply
  runSupabaseCliMigrationRunner, // Supabase CLI adapter
  runTypeSafetyGate, // deploy policy over type-contract diagnostics
  runRlsSafetyGate, // deploy policy over RLS/grant diagnostics
  syncMigrations, // gate + orchestrate the migration runner
  runCorpus, // the corpus oracle
  resolveDatabaseUrl,
  parseLineage,
  loadConfig,
} from "supaschema";

Core pipeline

Export	Maps to	Purpose
`extractSourceModel`	`inspect`	Parse any source (`dir:`, `git:`, `database:`, `dump:`, `catalog:`) into a `SchemaModel`.
`extractCatalogModel`	`inspect`	Read a live `pg_catalog` (read-only) into a `SchemaModel`.
`planSchemaDiff`	`plan`	Diff two models into a `MigrationPlan` of ordered, dependency-aware operations.
`renderMigration` / `renderMigrationSplit`	`diff`	Render a plan to guarded SQL; the split form separates a `concurrentSql` companion for `CREATE INDEX CONCURRENTLY` when `transactionMode` is `per-statement`.
`checkMigrationSql`	`check`	Static replay-safety and lock-hazard diagnostics for any migration SQL.
`verifyMigration`	`verify`	The apply-twice proof in throwaway databases, plus the reconvergence cross-check.

Operations and state

Export	Maps to	Purpose
`migrationsStatus` / `renderMigrationsStatus`	`migrations`	Reconcile disk files against a database target’s applied history, with optional target/runner labels and expected final versions.
`compareMigrationHistory` / `migrationFileVersions`	`migrations`	Compare expected migration versions with applied history for post-run target verification.
`runDirectMigrationRunner` / `runSupabaseCliMigrationRunner`	`sync`	Apply pending migration units through direct PostgreSQL or the Supabase CLI adapter.
`runTypeSafetyGate` / `runRlsSafetyGate`	`sync`	Run deploy-safety policy gates without depending on the standalone `type-contract` report command.
`syncMigrations`	`sync`	Gate pending migrations, then optionally drive the selected runner.
`auditModel` / `renderAuditReport`	`audit`	Support-matrix coverage report for adopting an existing schema.
`runCorpus` / `renderCorpusReport`	`corpus`	Replay a corpus tree and require reconvergence to zero.
`collectSchemaShapes` / `generateDatabaseTypes` / `generateZodSchemas`	`types`	Collect one schema shape graph, then generate upstream-compatible TypeScript database types plus separate runtime Zod validators from the PostgreSQL schema model.

Pass { postgrestVersion: "12" } as the second argument to generateDatabaseTypes to include Database.__InternalSupabase.PostgrestVersion; omit it when the generated contract should not own a PostgREST version.

Support utilities

Export	Purpose
`loadConfig` / `resolveConfig` / `defaultConfig` / `supaschemaConfigSchema` / `configJsonSchema` / `validateConfig`	Load, validate, and describe `supaschema.config.json` (the Zod and JSON Schema surfaces are exported).
`SupaschemaWorkflow` / `SchemaDiffPolicy` / `MigrationCheckPolicy` / `MigrationVerifyPolicy` / `MigrationSyncPolicy` / `GeneratedOutputPolicy` / `TypeUsagePolicy`	Typed names for the `workflow.*` config policy values.
`resolveDatabaseUrl` / `resolveSupabaseLocalDatabaseUrl` / `resolveVerificationDatabaseUrl`	The URL resolution lanes, including least-privilege target discovery and verification-specific local Supabase admin discovery.
`parseLineage` / `latestLineage` / `lineageLine`	Read and produce the `-- supaschema: lineage` markers that chain migrations.
`runConfiguredValidators`	Run the configured external validators (`squawk`, `sqlfluff`, …) against SQL.

All exports ship TypeScript types, including SchemaModel, MigrationPlan, SyncOptions, and CorpusReport.

Public vs internal surface

The exports above are the semver-stable public library API. Lower-level helpers that the CLI and tests share internally are not part of the public package surface and have no published entry point. These include disposable-database lifecycle, raw apply, and catalog fingerprinting (src/database/admin.ts), migration-unit grouping and Supabase-CLI command building (src/migrations/runners.ts), migration-file version parsing (src/migrations/status.ts), and deploy-safety/type-safety internals (src/pipeline/deploy-safety.ts, src/pipeline/type-safety.ts). They may change or be removed in any release. Use the documented pipeline exports (verifyMigration, syncMigrations, migrationsStatus) instead of reaching for them. For generated signatures, run npm run docs:api in the repository.

Start

Core workflow

Configure

Tasks

Agents and CI

Evidence

Reference

Core pipeline

Operations and state

Support utilities

Public vs internal surface

​Core pipeline

​Operations and state

​Support utilities

​Public vs internal surface

Core pipeline

Operations and state

Support utilities

Public vs internal surface