Change Naming Conventions

Previously: In Adding Your First Database Change, we learned the basic workflow for adding changes. Now let's organize changes as your schema grows.

As your schema grows to 50+ changes, flat structures become unmaintainable. pgpm supports nested paths for hierarchical organization.

Old: Flat Structure (50+ changes)

create_users_table
create_posts_table
create_comments_table
add_users_email_index
add_posts_published_index
create_user_profiles_table
add_users_avatar_column
create_sessions_table
add_users_password_hash
create_organizations_table
...

Finding anything becomes tedious. No clear organization.

New: Nested Structure

Use hierarchical paths that mirror Postgres schema organization:

pgpm add schemas/<schema_name>/schema
pgpm add schemas/<schema_name>/tables/<table_name>
pgpm add schemas/<schema_name>/tables/<table_name>/indexes/<index_name>
pgpm add schemas/<schema_name>/tables/<table_name>/triggers/<trigger_name>
pgpm add schemas/<schema_name>/functions/<function_name>

Example:

pgpm add schemas/app/schema
pgpm add schemas/app/tables/users
pgpm add schemas/app/tables/users/indexes/email
pgpm add schemas/app/tables/users/triggers/updated_at
pgpm add schemas/app/functions/create_user

This creates an organized directory structure:

deploy/
└── schemas/
    └── app/
        ├── schema.sql
        ├── tables/
        │   └── users/
        │       ├── table.sql
        │       ├── indexes/
        │       │   └── email.sql
        │       └── triggers/
        │           └── updated_at.sql
        └── functions/
            └── create_user.sql

Key Takeaways

• Use schemas/<schema_name>/ as the foundation
• Nest by object type: tables/, functions/, triggers/, indexes/, etc.
• Keep paths descriptive and consistent
• Deployment order follows plan file, not directory structure

What's Next

In the next lesson, we'll explore plan files and deployment plans.