Ignore (.pgschemaignore)

pgschema supports ignoring specific database objects using a .pgschemaignore file, enabling gradual onboarding and selective schema management.

Overview

The .pgschemaignore file allows you to exclude database objects from pgschema operations. This is particularly useful when:

Gradual Migration - Incrementally adopt pgschema without managing all existing objects
Temporary Objects - Exclude temp tables, debug views, and development-only objects
Legacy Objects - Ignore deprecated objects while maintaining new schema management
Environment-Specific Objects - Skip objects that exist only in certain environments
Role-Specific Privileges - Ignore grants to roles that don’t exist in the plan database

File Format

The .pgschemaignore file is automatically loaded when present in the current directory:

Create a .pgschemaignore file in your project directory using TOML format:

[schemas]
patterns = ["auth", "storage"]

[tables]
patterns = ["temp_*", "test_*", "!test_core_*"]

[views]
patterns = ["debug_*", "*_view_tmp", "analytics_*"]

[functions]
patterns = ["fn_test_*", "fn_debug_*"]

[procedures]
patterns = ["sp_temp_*", "sp_legacy_*"]

[aggregates]
patterns = ["agg_test_*", "agg_debug_*"]

[types]
patterns = ["type_test_*"]

[sequences]
patterns = ["seq_temp_*", "seq_debug_*"]

[indexes]
patterns = ["idx_temp_*", "manual_*"]

[constraints]
patterns = ["fk_legacy_*"]

[triggers]
patterns = ["_vectorizer_src_trg_*"]

[privileges]
patterns = ["deploy_bot", "admin_*"]

[default_privileges]
patterns = ["deploy_bot"]

Pattern Syntax

Wildcard Patterns

Use * to match any sequence of characters:

[tables]
patterns = [
  "temp_*",        # Matches: temp_backup, temp_cache, temp_session
  "*_backup",      # Matches: users_backup, orders_backup
  "test_*_data"    # Matches: test_user_data, test_order_data
]

Exact Patterns

Specify exact object names without wildcards:

[tables]
patterns = ["legacy_table", "deprecated_users", "old_audit"]

Negation Patterns

Use ! prefix to exclude objects from broader patterns:

[tables]
patterns = [
  "test_*",           # Ignore all test_ tables
  "!test_core_*"      # But keep test_core_ tables
]

This will ignore test_data, test_results but keep test_core_config, test_core_settings.

Privileges

The [privileges] and [default_privileges] sections filter GRANT statements by grantee role name. This is useful when running pgschema plan with roles that don’t exist in the plan database, or managing migrations across environments with different role configurations.

[privileges]
patterns = [
  "deploy_bot",    # Ignore all grants to deploy_bot
  "admin_*",       # Ignore grants to any admin_* role
  "!admin_super"   # But keep grants to admin_super
]

[default_privileges]
patterns = ["deploy_bot"]  # Ignore ALTER DEFAULT PRIVILEGES for deploy_bot

The [privileges] section filters explicit grants (GRANT ... TO role), including column-level privileges. The [default_privileges] section filters ALTER DEFAULT PRIVILEGES statements.

Constraints

The [constraints] section matches table constraints by constraint name (primary keys, unique, foreign keys, check, and exclusion constraints). When a constraint is ignored, pgschema neither creates, drops, nor reports drift on it — it is left entirely to be managed out-of-band.

[constraints]
patterns = ["fk_*", "!fk_core_*"]

This is useful when:

Out-of-band constraints - A constraint is added and managed manually (e.g. disabled during an AWS DMS migration and re-added afterward), and you don’t want pgschema plan to flag it for drop.
Cross-schema foreign keys - Prefer ignoring the referenced schema or table (see below) so plan can stub it. Alternatively, omit the FK from the desired SQL and ignore the live constraint by name so each schema can be bootstrapped independently.

Patterns match the constraint name only, which is not necessarily unique across tables. Be careful with broad patterns like *, as ignoring a primary key or unique constraint can leave a table without the keys it needs.

Schemas and Cross-Schema Foreign Keys

The [schemas] section matches schema names. Combined with schema-qualified [tables] patterns (auth.users, auth.*), this is the way to keep a foreign key to an unmanaged schema (for example Supabase auth.users) in your desired SQL.

[schemas]
patterns = ["auth"]

# Or ignore only specific tables in another schema:
# [tables]
# patterns = ["auth.users"]

-- schema.sql (your app schema only — no auth stub required)
CREATE TABLE profiles (
    id UUID PRIMARY KEY,
    auth_user_id UUID NOT NULL UNIQUE REFERENCES auth.users (id) ON DELETE CASCADE
);

When plan applies this SQL to its temporary database, it clones a structural stub of each ignored FK target from the target database (columns plus PRIMARY KEY / UNIQUE constraints), so PostgreSQL can create the foreign key. You do not need a manual CREATE TABLE auth.users stub in your schema file or a separate external plan database for this case. The auto-stub is not part of the managed schema: dump does not emit auth.users, and plan will not create or drop it. The referenced table must already exist on the target database. If it does not, use a manual stub in your schema file or an external plan database.

Cross-schema table patterns must be schema-qualified (auth.users or auth.*). A bare pattern like users only matches tables in the schema you are managing, so it will not stub auth.users.

Triggers

The [triggers] section matches triggers by trigger name. When a trigger is ignored, pgschema neither creates, drops, nor reports drift on it — it is left entirely to be managed out-of-band.

[triggers]
patterns = ["_vectorizer_src_trg_*"]

This is useful when an extension automatically creates triggers on tables you manage. For example, the pgai vectorizer adds _vectorizer_src_trg_* triggers to source tables; ignoring them keeps pgschema plan from flagging them for drop while you continue to manage the rest of the table.

Patterns match the trigger name only, which is not necessarily unique across tables. Be careful with broad patterns like *.

Triggers on Ignored Tables

Triggers can be defined on ignored tables. The table structure is not managed, but the trigger itself is.

# .pgschemaignore
[tables]
patterns = ["external_*"]

-- schema.sql
CREATE TRIGGER on_data_change
  AFTER INSERT ON external_users
  FOR EACH ROW
  EXECUTE FUNCTION sync_data();

The trigger will be managed while external_users table structure remains unmanaged.

Getting started

CLI Reference

Workflow

Configuration

Overview

File Format

Pattern Syntax

Wildcard Patterns

Exact Patterns

Negation Patterns

Privileges

Constraints

Schemas and Cross-Schema Foreign Keys

Triggers

Triggers on Ignored Tables

​Overview

​File Format

​Pattern Syntax

​Wildcard Patterns

​Exact Patterns

​Negation Patterns

​Privileges

​Constraints

​Schemas and Cross-Schema Foreign Keys

​Triggers

​Triggers on Ignored Tables

Overview

File Format

Pattern Syntax

Wildcard Patterns

Exact Patterns

Negation Patterns

Privileges

Constraints

Schemas and Cross-Schema Foreign Keys

Triggers

Triggers on Ignored Tables