> ## Documentation Index
> Fetch the complete documentation index at: https://supaschema.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Library API

> Every CLI capability as an exported, typed function — the supaschema Node.js library surface.

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.

```ts theme={null}
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](/docs/configuration/environments), 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.