Skip to main content
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:
  1. Gradual Migration - Incrementally adopt pgschema without managing all existing objects
  2. Temporary Objects - Exclude temp tables, debug views, and development-only objects
  3. Legacy Objects - Ignore deprecated objects while maintaining new schema management
  4. Environment-Specific Objects - Skip objects that exist only in certain environments
  5. 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: 
[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:
  1. 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.
  2. Cross-schema foreign keys - When modules live in separate schemas with foreign keys between them, ignore the cross-schema foreign keys so each schema can be bootstrapped independently, then drop the ignore to let pgschema manage them once all tables exist.
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.

​
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.