Skip to main content
supaschema parses your declarative schema files, extracts a typed model of every named DDL object, diffs it against a baseline, and renders idempotent migration SQL. This page tells you exactly which PostgreSQL object types supaschema supports, how it renders each one, and what you need to know before relying on it in production.
Run npx supaschema audit dir:supabase/schemas to check coverage for your specific schema directory. The audit command reports which objects supaschema extracted cleanly, which triggered warnings, and which could not be tracked.

​
Object support table

The Extract column indicates whether supaschema can parse and track this object type from a declarative source file. The Render Strategy column shows the SQL pattern supaschema uses when writing migration output for this object.
Object TypeExtractRender StrategyNotes
Schemas✅CREATE SCHEMA IF NOT EXISTS
Extensions✅CREATE EXTENSION IF NOT EXISTS
Types (enum)✅CREATE TYPE + catalog guardAdding enum values is supported. Reordering or removing enum values cannot be expressed safely in SQL and must be hand-authored in a separate migration.
Domains✅CREATE DOMAIN + catalog guard
Tables✅CREATE TABLE IF NOT EXISTS + ALTER TABLEFull column-level tracking. supaschema tracks additions, alterations, and removals at the column granularity.
Columns✅ADD COLUMN / ALTER COLUMN / DROP COLUMNDestructive operations (drop, type change) require an explicit entry in hints.destructive to proceed.
Constraints✅ADD CONSTRAINT + catalog guardIncludes PRIMARY KEY, UNIQUE, CHECK, and FOREIGN KEY. The catalog guard prevents duplicate-constraint errors on replay.
Indexes✅CREATE INDEX IF NOT EXISTSCREATE INDEX CONCURRENTLY is not supported inside a transactional migration block. supaschema splits concurrent indexes into a separate file automatically.
Sequences✅CREATE SEQUENCE IF NOT EXISTS
Functions✅CREATE OR REPLACE FUNCTIONReturn type changes require hints.destructive because OR REPLACE cannot change a return type.
Procedures✅CREATE OR REPLACE PROCEDURE
Views✅CREATE OR REPLACE VIEWColumn list changes (adding, removing, or reordering columns) are incompatible with OR REPLACE and require a hints.destructive entry for a DROP + CREATE cycle.
Materialized Views✅CREATE MATERIALIZED VIEW IF NOT EXISTS
Triggers✅CREATE OR REPLACE TRIGGER / DROP IF EXISTS + CREATEsupaschema uses OR REPLACE on PostgreSQL 14+. On earlier versions it falls back to DROP TRIGGER IF EXISTS followed by CREATE TRIGGER.
Row Level Security✅ALTER TABLE ... ENABLE ROW LEVEL SECURITYsupaschema tracks the enabled/disabled state of RLS per table.
Policies✅DROP POLICY IF EXISTS + CREATE POLICYPostgreSQL has no OR REPLACE for policies. supaschema always emits a DROP IF EXISTS before the CREATE to ensure idempotency.
Grants & Default Privileges✅GRANT / REVOKE / ALTER DEFAULT PRIVILEGESThe excludedGrantRoles config option filters out system roles and noisy grant entries that you do not want supaschema to manage.
Comments✅COMMENT ON ...Applies to tables, columns, functions, views, and other commentable objects.
Foreign Data Wrappers✅CREATE FOREIGN DATA WRAPPER
Foreign Servers✅CREATE SERVER
Foreign Tables✅CREATE FOREIGN TABLE
Side-effect statements⚠️Not trackedINSERT, UPDATE, DELETE, SET, and similar DML or session statements are not schema objects and are not tracked in the schema model. Keep them in hand-authored migration files and review them separately.

​
Supabase managed schema block list

When you use supaschema with a Supabase project, the following schemas are considered Supabase-managed and cannot be used as declarative source owners. Attempting to do so raises SUPA_SUPABASE_MANAGED_SCHEMA. 
auth
storage
realtime
vault
extensions
cron
net
supabase_functions
graphql
graphql_public
Do not add any of these schemas to your schemaPaths configuration. supaschema will block the operation to prevent you from accidentally overwriting Supabase’s internal schema migrations.
You can still read objects from these schemas (for example, to reference auth.users as a foreign key target), but you cannot declare or manage objects inside them.

​
Coverage audit

To verify that supaschema can successfully extract every object in your schema directory, run: 
npx supaschema audit dir:supabase/schemas
The audit output groups objects into three categories:
  • Extracted — supaschema parsed and fully tracked the object.
  • Warnings — supaschema extracted the object but emitted one or more SUPA_EXTRACT_* warnings. Review each warning before relying on the object in a generated migration.
  • Skipped — The statement was not recognized as a trackable schema object (e.g., side-effect statements). These will not appear in any generated migration.
The audit command does not connect to a database and does not modify any files. It is safe to run at any time.

​
Unsupported and partially supported DDL

The following categories of DDL are not currently tracked as first-class schema objects. They may appear in your schema files, but supaschema will emit an SUPA_EXTRACT_UNSUPPORTED or SUPA_EXTRACT_SIDE_EFFECT_UNSUPPORTED warning and will not include them in generated migrations.
  • DML statements (INSERT, UPDATE, DELETE) — not schema definitions.
  • Session-level statements (SET, RESET, BEGIN, COMMIT) — not persistent schema state.
  • ALTER SYSTEM — server-level configuration; out of scope.
  • Composite types and range types — partially supported; check the audit output for your specific usage.
  • Publications and subscriptions — logical replication objects are not yet tracked.
  • Event triggers — not yet supported as a first-class object type.
For any unsupported statement, keep it in a hand-authored migration file and manage it outside supaschema’s tracking.