postgres-project-structure

PostgreSQL Project Structure

Standard Layout

database/
├── migrations/
│   ├── V001__create_extensions.sql
│   ├── V002__create_orders_table.sql
│   ├── V003__create_auth_schema.sql
│   └── V004__add_rls_policies.sql
├── schemas/
│   ├── public/
│   │   ├── tables/
│   │   │   ├── orders.sql
│   │   │   ├── order_items.sql
│   │   │   └── customers.sql
│   │   ├── views/
│   │   │   └── active_customers.sql
│   │   ├── functions/
│   │   │   ├── get_order_by_id.sql
│   │   │   └── calculate_total.sql
│   │   ├── triggers/
│   │   │   └── trg_set_modified_at.sql
│   │   └── types/
│   │       └── order_status.sql
│   ├── auth/
│   │   ├── tables/
│   │   │   ├── users.sql
│   │   │   └── roles.sql
│   │   └── functions/
│   │       └── authenticate_user.sql
│   └── audit/
│       └── tables/
│           └── audit_log.sql
├── extensions/
│   └── required_extensions.sql
├── security/
│   ├── roles/
│   │   ├── app_read_role.sql
│   │   └── app_write_role.sql
│   └── rls/
│       └── tenant_policies.sql
├── seed/
│   ├── lookup/
│   │   ├── order_statuses.sql
│   │   └── countries.sql
│   └── dev/
│       └── sample_orders.sql
├── tests/
│   └── pgTAP/
│       ├── test_orders.sql
│       └── test_auth.sql
├── alembic/                          # If using Alembic
│   ├── alembic.ini
│   ├── env.py
│   └── versions/
└── flyway.conf                       # If using Flyway

Rules

• One file per database object
• Organize by schema, then by object type
• migrations/ for versioned change scripts (V001, V002, ...)
• extensions/ for PostgreSQL extension declarations
• security/ for roles and RLS policies
• seed/lookup/ for reference data (always applied)
• seed/dev/ for development-only sample data
• tests/pgTAP/ for in-database unit tests
• Schema separation: public for core domain, auth for authentication, audit for logging
• Use types/ subdirectory for custom ENUMs and composite types