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

# 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:

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

<Note>
  The `.pgschemaignore` file is automatically loaded when present in the current directory:
</Note>

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

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[tables]
patterns = ["legacy_table", "deprecated_users", "old_audit"]
```

### Negation Patterns

Use `!` prefix to exclude objects from broader patterns:

```toml theme={null}
[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.

```toml theme={null}
[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.

```toml theme={null}
[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** - 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.

<Warning>
  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.
</Warning>

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

```toml theme={null}
[schemas]
patterns = ["auth"]

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

```sql theme={null}
-- 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](/cli/plan-db).

<Note>
  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`.
</Note>

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

```toml theme={null}
[triggers]
patterns = ["_vectorizer_src_trg_*"]
```

This is useful when an extension automatically creates triggers on tables you manage. For example, the [pgai](https://github.com/timescale/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.

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

## Triggers on Ignored Tables

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

```toml theme={null}
# .pgschemaignore
[tables]
patterns = ["external_*"]
```

```sql theme={null}
-- 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.