relspecgo/pkg/writers/pgsql/NAMING_CONVENTIONS.md

# PostgreSQL Naming Conventions

Standardized naming rules for all database objects in RelSpec PostgreSQL output.

## Quick Reference

| Object Type       | Prefix      | Format                             | Example                  |
| ----------------- | ----------- | ---------------------------------- | ------------------------ |
| Primary Key       | `pk_`       | `pk_<schema>_<table>`              | `pk_public_users`        |
| Foreign Key       | `fk_`       | `fk_<table>_<referenced_table>`    | `fk_posts_users`         |
| Unique Constraint | `ukey_`     | `ukey_<table>_<column>`            | `ukey_users_email`       |
| Unique Index      | `ukey_`     | `ukey_<table>_<column>`            | `ukey_users_email`       |
| Regular Index     | `idx_`      | `idx_<table>_<column>`             | `idx_posts_user_id`      |
| Check Constraint  | `chk_`      | `chk_<table>_<constraint_purpose>` | `chk_users_age_positive` |
| Sequence          | `identity_` | `identity_<table>_<column>`        | `identity_users_id`      |
| Trigger           | `t_`        | `t_<purpose>_<table>`              | `t_audit_users`          |
| Trigger Function  | `tf_`       | `tf_<purpose>_<table>`             | `tf_audit_users`         |

## Naming Rules by Object Type

### Primary Keys

**Pattern:** `pk_<schema>_<table>`

- Include schema name to avoid collisions across schemas
- Use lowercase, snake_case format
- Examples:
  - `pk_public_users`
  - `pk_audit_audit_log`
  - `pk_staging_temp_data`

### Foreign Keys

**Pattern:** `fk_<table>_<referenced_table>`

- Reference the table containing the FK followed by the referenced table
- Use lowercase, snake_case format
- Do NOT include column names in standard FK constraints
- Examples:
  - `fk_posts_users` (posts.user_id → users.id)
  - `fk_comments_posts` (comments.post_id → posts.id)
  - `fk_order_items_orders` (order_items.order_id → orders.id)

### Unique Constraints

**Pattern:** `ukey_<table>_<column>`

- Generated by the DBML reader for column `[unique]`
- Include column name for clarity
- Examples:
  - `ukey_users_email`
  - `ukey_users_username`
  - `ukey_products_sku`

### Unique Indexes

**Pattern:** `ukey_<table>_<column>`

- Unnamed unique indexes use the same name as a unique constraint on the same columns
- Writers then build the constraint on the index (`ADD CONSTRAINT ... UNIQUE USING INDEX`), so no duplicate index is created
- Examples:
  - `ukey_users_email`
  - `ukey_sessions_token`
  - `ukey_api_keys_key`

### Regular Indexes

**Pattern:** `idx_<table>_<column>`

- Standard indexes for query optimization
- Single column: `idx_<table>_<column>`
- Examples:
  - `idx_posts_user_id`
  - `idx_orders_created_at`
  - `idx_users_status`

### Check Constraints

**Pattern:** `chk_<table>_<constraint_purpose>`

- Describe the constraint validation purpose
- Use lowercase, snake_case for the purpose
- Examples:
  - `chk_users_age_positive` (CHECK (age > 0))
  - `chk_orders_quantity_positive` (CHECK (quantity > 0))
  - `chk_products_price_valid` (CHECK (price >= 0))
  - `chk_users_status_enum` (CHECK (status IN ('active', 'inactive')))

### Sequences

**Pattern:** `identity_<table>_<column>`

- Used for SERIAL/IDENTITY columns
- Explicitly named for clarity and management
- Examples:
  - `identity_users_id`
  - `identity_posts_id`
  - `identity_transactions_id`

### Triggers

**Pattern:** `t_<purpose>_<table>`

- Include purpose before table name
- Lowercase, snake_case format
- Examples:
  - `t_audit_users` (audit trigger on users table)
  - `t_update_timestamp_posts` (timestamp update trigger on posts)
  - `t_validate_orders` (validation trigger on orders)

### Trigger Functions

**Pattern:** `tf_<purpose>_<table>`

- Pair with trigger naming convention
- Use `tf_` prefix to distinguish from triggers themselves
- Examples:
  - `tf_audit_users` (function for t_audit_users)
  - `tf_update_timestamp_posts` (function for t_update_timestamp_posts)
  - `tf_validate_orders` (function for t_validate_orders)

## Multi-Column Objects

### Composite Primary Keys

**Pattern:** `pk_<schema>_<table>`

- Same as single-column PKs
- Example: `pk_public_order_items` (composite key on order_id + item_id)

### Composite Unique Constraints

**Pattern:** `uk_<table>_<column1>_<column2>_[...]`

- Append all column names in order
- Examples:
  - `uk_users_email_domain` (UNIQUE(email, domain))
  - `uk_inventory_warehouse_sku` (UNIQUE(warehouse_id, sku))

### Composite Unique Indexes

**Pattern:** `uidx_<table>_<column1>_<column2>_[...]`

- Append all column names in order
- Examples:
  - `uidx_users_first_name_last_name` (UNIQUE INDEX on first_name, last_name)
  - `uidx_sessions_user_id_device_id` (UNIQUE INDEX on user_id, device_id)

### Composite Regular Indexes

**Pattern:** `idx_<table>_<column1>_<column2>_[...]`

- Append all column names in order
- List columns in typical query filter order
- Examples:
  - `idx_orders_user_id_created_at` (filter by user, then sort by created_at)
  - `idx_logs_level_timestamp` (filter by level, then by timestamp)

## Special Cases & Conventions

### Audit Trail Tables

- Audit table naming: `<original_table>_audit` or `audit_<original_table>`
- Audit indexes follow standard pattern: `idx_<audit_table>_<column>`
- Examples:
  - Users table audit: `users_audit` with `idx_users_audit_tablename`, `idx_users_audit_changedate`
  - Posts table audit: `posts_audit` with `idx_posts_audit_tablename`, `idx_posts_audit_changedate`

### Temporal/Versioning Tables

- Use suffix `_history` or `_versions` if needed
- Apply standard naming rules with the full table name
- Examples:
  - `idx_users_history_user_id`
  - `uk_posts_versions_version_number`

### Schema-Specific Objects

- Always qualify with schema when needed: `pk_<schema>_<table>`
- Multiple schemas allowed: `pk_public_users`, `pk_staging_users`

### Reserved Words & Special Names

- Avoid PostgreSQL reserved keywords in object names
- If column/table names conflict, use quoted identifiers in DDL
- Naming convention rules still apply to the logical name

### Generated/Anonymous Indexes

- If an index lacks explicit naming, default to: `idx_<schema>_<table>`
- Should be replaced with explicit names following standards
- Examples (to be renamed):
  - `idx_public_users` → should be `idx_users_<column>`

## Implementation Notes

### Code Generation

- Names are always lowercase in generated SQL
- Underscore separators are required

### Migration Safety

- Do NOT rename objects after creation without explicit migration
- Names should be consistent across all schema versions
- Test generated DDL against PostgreSQL before deployment

### Testing

- Ensure consistency across all table and constraint generation
- Test with reserved words to verify escaping

## Related Documentation

- PostgreSQL Identifier Rules: https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-IDENTIFIERS
- Constraint Documentation: https://www.postgresql.org/docs/current/ddl-constraints.html
- Index Documentation: https://www.postgresql.org/docs/current/indexes.html