supaschema Node.js Library API — Full Function Reference

npm install supaschema

import {
  // Extraction
  extractSourceModel,
  extractCatalogModel,
  // Planning & rendering
  planSchemaDiff,
  renderMigration,
  renderMigrationSplit,
  // Static analysis & verification
  checkMigrationSql,
  verifyMigration,
  // Migrations management
  migrationsStatus,
  renderMigrationsStatus,
  syncMigrations,
  // Type & schema generation
  generateDatabaseTypes,
  generateZodSchemas,
  // Configuration
  loadConfig,
  defaultConfig,
  resolveConfig,
  supaschemaConfigSchema,
  // Auditing & corpus
  auditModel,
  renderAuditReport,
  runCorpus,
  renderCorpusReport,
  // Utilities
  resolveDatabaseUrl,
  resolveSupabaseLocalDatabaseUrl,
  parseLineage,
  latestLineage,
  lineageLine,
  runConfiguredValidators,
  // Database admin (advanced)
  applyMigrationSql,
  applySql,
  catalogFingerprint,
} from 'supaschema'

function extractSourceModel(
  source: string,
  options?: ExtractSourceOptions
): Promise<SchemaModel>

import { extractSourceModel } from 'supaschema'

const model = await extractSourceModel('dir:supabase/schemas', {
  cwd: process.cwd(),
})

console.log(model.fingerprint) // deterministic hash of all tracked objects
console.log(Object.keys(model.objects).length) // total tracked object count

function extractCatalogModel(
  databaseUrl: string,
  options?: ExtractCatalogOptions
): Promise<SchemaModel>

import { extractCatalogModel, loadConfig } from 'supaschema'

const config = await loadConfig(process.cwd())
const liveModel = await extractCatalogModel(
  'postgresql://postgres:postgres@localhost:54322/postgres',
  { config }
)

console.log(liveModel.fingerprint)

function planSchemaDiff(
  fromModel: SchemaModel,
  toModel: SchemaModel,
  config?: SupaschemaConfig
): MigrationPlan

import { extractSourceModel, extractCatalogModel, planSchemaDiff } from 'supaschema'

const fromModel = await extractCatalogModel('postgresql://...')
const toModel = await extractSourceModel('dir:supabase/schemas')

const plan = planSchemaDiff(fromModel, toModel)

console.log(plan.operations.length)          // total number of changes
console.log(plan.operations[0].kind)         // 'create' | 'alter' | 'replace' | 'drop' | 'rename'
console.log(plan.operations[0].ref)          // e.g. 'public.users' (table)
console.log(plan.operations[0].destructive)  // true if this operation destroys data
console.log(plan.operations[0].blocked)      // true if a hint is required to proceed

function renderMigration(
  plan: MigrationPlan,
  options?: RenderOptions
): string

import { planSchemaDiff, renderMigration } from 'supaschema'

const plan = planSchemaDiff(fromModel, toModel, config)
const sql = renderMigration(plan, { config })

console.log(sql)

function renderMigrationSplit(
  plan: MigrationPlan,
  options?: RenderOptions
): RenderResult

interface RenderResult {
  sql: string           // main migration SQL (transactional)
  concurrentSql?: string // separate file for CONCURRENTLY statements, if any
}

import { renderMigrationSplit } from 'supaschema'
import { writeFileSync } from 'fs'

const { sql, concurrentSql } = renderMigrationSplit(plan, { config })

writeFileSync('supabase/migrations/20240101000000_changes.sql', sql)

if (concurrentSql) {
  // Apply this file outside a transaction block after the main migration
  writeFileSync('supabase/migrations/20240101000001_concurrent.sql', concurrentSql)
}

function checkMigrationSql(
  sql: string,
  options?: CheckOptions
): Promise<Diagnostic[]>

import { checkMigrationSql } from 'supaschema'
import { readFileSync } from 'fs'

const sql = readFileSync('supabase/migrations/20240101000000_changes.sql', 'utf8')
const diagnostics = await checkMigrationSql(sql, { config })

const errors = diagnostics.filter(d => d.severity === 'error')
const warnings = diagnostics.filter(d => d.severity === 'warning')

if (errors.length > 0) {
  console.error('Migration has errors:', errors)
  process.exit(1)
}

function verifyMigration(options: VerifyMigrationOptions): Promise<Diagnostic[]>

import { verifyMigration } from 'supaschema'

const diagnostics = await verifyMigration({
  databaseUrl: 'postgresql://postgres:postgres@localhost:54322/postgres',
  from: 'git:HEAD',
  to: 'dir:supabase/schemas',
  migrationPath: './supabase/migrations/20240101000000_changes.sql',
  ensureRoles: true,
})

if (diagnostics.some(d => d.severity === 'error')) {
  console.error('Verification failed:', diagnostics)
  process.exit(1)
}

console.log('Migration verified successfully.')

function migrationsStatus(options: MigrationsStatusOptions): Promise<MigrationsReport>

import { migrationsStatus } from 'supaschema'

const report = await migrationsStatus({
  migrationsDir: 'supabase/migrations',
  databaseUrl: 'postgresql://postgres:postgres@localhost:54322/postgres',
})

console.log(report.pending)     // migrations on disk not yet applied
console.log(report.applied)     // migrations recorded in the history table
console.log(report.ghost)       // history entries with no file on disk
console.log(report.outOfOrder)  // pending files older than the newest applied
console.log(report.diagnostics) // any SUPA_MIGRATIONS_* diagnostics

function renderMigrationsStatus(report: MigrationsStatusReport): string

import { migrationsStatus, renderMigrationsStatus } from 'supaschema'

const report = await migrationsStatus({ migrationsDir: 'supabase/migrations' })
console.log(renderMigrationsStatus(report))

function loadConfig(
  cwd?: string,
  explicitPath?: string
): Promise<SupaschemaConfig>

import { loadConfig } from 'supaschema'

const config = await loadConfig(process.cwd())

console.log(config.schemaPaths)        // e.g. ['supabase/schemas']
console.log(config.hints?.destructive) // e.g. ['public.old_table']
console.log(config.excludedGrantRoles) // roles filtered from grant tracking

import { defaultConfig } from 'supaschema'

console.log(defaultConfig.migrationsDir) // default migrations directory

function resolveConfig(partial: Partial<SupaschemaConfig>): SupaschemaConfig

import { supaschemaConfigSchema } from 'supaschema'

const result = supaschemaConfigSchema.safeParse(myConfig)
if (!result.success) {
  console.error(result.error.format())
}

function auditModel(
  model: SchemaModel,
  options?: AuditOptions
): AuditReport

import { extractSourceModel, auditModel } from 'supaschema'

const model = await extractSourceModel('dir:supabase/schemas')
const report = auditModel(model)

console.log(report.extracted.length) // cleanly tracked objects
console.log(report.warnings.length)  // objects with extraction warnings
console.log(report.skipped.length)   // untracked statements

function renderAuditReport(report: AuditReport): string

import { extractSourceModel, auditModel, renderAuditReport } from 'supaschema'

const model = await extractSourceModel('dir:supabase/schemas')
const report = auditModel(model)
console.log(renderAuditReport(report))

function syncMigrations(options: SyncOptions): Promise<Diagnostic[]>

function generateDatabaseTypes(
  source: string | SchemaModel,
  options?: GenerateTypesOptions
): Promise<string>

function generateZodSchemas(
  source: string | SchemaModel,
  options?: GenerateZodOptions
): Promise<string>

function runCorpus(options: CorpusOptions): Promise<CorpusReport>

function renderCorpusReport(report: CorpusReport): string

function resolveDatabaseUrl(
  explicit?: string,
  options?: { cwd?: string }
): Promise<string | undefined>

function resolveSupabaseLocalDatabaseUrl(cwd?: string): Promise<string | undefined>

function parseLineage(sql: string): MigrationLineage | undefined

function latestLineage(migrationsDir: string): Promise<MigrationLineage | undefined>

function lineageLine(from: string, to: string): string

function runConfiguredValidators(
  sql: string,
  config: SupaschemaConfig,
  options?: { filename?: string }
): Promise<Diagnostic[]>

function applyMigrationSql(
  databaseUrl: string,
  sql: string
): Promise<void>

function applySql(
  databaseUrl: string,
  sql: string
): Promise<void>

function catalogFingerprint(
  databaseUrl: string,
  options?: { config?: SupaschemaConfig }
): Promise<string>

interface SchemaModel {
  /** The source specifier used to produce this model. */
  source: string

  /** All tracked objects, in dependency order. */
  objects: SchemaObject[]

  /** Raw diagnostics emitted during extraction. */
  diagnostics: Diagnostic[]

  /** Deterministic hash of all tracked object definitions. */
  fingerprint: string

  /** Internal format version; used to detect stale snapshots. */
  formatVersion?: number
}

interface MigrationPlan {
  /** Fingerprint of the baseline (from) model. */
  fromFingerprint: string

  /** Fingerprint of the target (to) model. */
  toFingerprint: string

  /** Ordered list of operations to apply. */
  operations: MigrationOperation[]

  /** Diagnostics emitted during planning. */
  diagnostics: Diagnostic[]
}

interface MigrationOperation {
  /** The type of change. */
  kind: MigrationOperationKind // 'alter' | 'create' | 'replace' | 'drop' | 'rename'

  /** Structured reference to the affected object (kind, name, schema). */
  ref: ObjectRef

  /** Fully-qualified identity key (e.g. 'public.users'). */
  key: string

  /** The object's state before the operation (undefined for creates). */
  before?: SchemaObject

  /** The object's state after the operation (undefined for drops). */
  after?: SchemaObject

  /** True if this operation permanently destroys data or objects. */
  destructive: boolean

  /**
   * True if supaschema requires a hint before it will render this operation.
   * Blocked operations cause `renderMigration` / `renderMigrationSplit` to throw.
   */
  blocked: boolean

  /** Diagnostics emitted for this specific operation during planning. */
  diagnostics: Diagnostic[]

  /** Additional planner metadata (internal use). */
  metadata: Record<string, unknown>
}

interface Diagnostic {
  /** Stable diagnostic code (e.g. 'SUPA_PLAN_DESTRUCTIVE_HINT_REQUIRED'). */
  code: string

  /** Severity level. */
  severity: DiagnosticSeverity // 'error' | 'warning' | 'info'

  /** Human-readable explanation of the issue. */
  message: string

  /** Structured reference to the affected object. */
  ref?: ObjectRef

  /** Path to the source file where the issue was detected. */
  file?: string

  /** The SQL statement that triggered the diagnostic, if applicable. */
  statement?: string

  /** Actionable suggestion for resolving the issue. */
  hint?: string

  /** Schemas referenced by the failing statement (used for schema-filter scoping). */
  schemas?: string[]
}

interface SupaschemaConfig {
  /** Schema source paths (e.g. ['supabase/schemas']). */
  schemaPaths: string[]

  /** Migrations output directory. */
  migrationsDir?: string

  /** Roles to exclude from grant tracking. */
  excludedGrantRoles?: string[]

  /** Hints that influence planning behavior. */
  hints?: {
    /** Object keys that are allowed to be dropped or destructively altered. */
    destructive?: string[]

    /** Rename hints, each specifying the old and new fully-qualified object key. */
    renames?: RenameHint[]
  }

  /** External SQL validators to run after check. */
  validators?: string[]

  /** History table for migrations tracking. */
  historyTable?: string
}

interface RenameHint {
  from: string // e.g. 'public.old_table_name'
  to: string   // e.g. 'public.new_table_name'
}

interface ObjectRef {
  kind: ObjectKind
  name: string
  schema?: string
  /** Function/procedure parameter-type signature, if applicable. */
  signature?: string
  /** Parent table name, for constraints, indexes, triggers, and policies. */
  table?: string
}

type DiagnosticSeverity = 'info' | 'warning' | 'error'

type ObjectKind =
  | 'schema' | 'extension' | 'type' | 'domain' | 'enum' | 'sequence'
  | 'table' | 'foreign-data-wrapper' | 'foreign-server' | 'foreign-table'
  | 'constraint' | 'index' | 'function' | 'procedure'
  | 'view' | 'materialized-view' | 'trigger'
  | 'rls' | 'policy' | 'grant' | 'default-privilege' | 'comment'

type MigrationOperationKind = 'alter' | 'create' | 'replace' | 'drop' | 'rename'