postgres-style-guide

name

postgres-style-guide

description

Apply this PostgreSQL style guide when designing schemas, writing queries, authoring migrations, or configuring database roles for this project. Covers PostgreSQL 18 conventions, naming and formatting, keys and identity, data types, jsonb and normalization, constraints, indexes, join and CTE style, DML and upserts, functions, triggers, views, roles and grants, and safe schema migrations. Also use when investigating slow queries or reviewing schemas, migrations, and SQL changes.

PostgreSQL Style Guide

Apply the loaded policy pages directly.

Routing

Workflows

Task	Load
Change a live database schema	safe migration workflow
Stand up a new database	database setup workflow
Investigate a slow query	performance workflow
Review schema, migration, or query changes	review workflow

Policy Fast Paths

Task	Load
Design a new table	object naming, primary keys, foreign keys, scalar types, constraints, standard columns
Choose a primary key or ID type	primary keys and row identity
Model a status or category	enums/domains/lookups, constraints
Choose columns, JSONB, or arrays	JSONB and normalization, advanced indexes
Write a multi-step or reporting query	CTEs, join style, aggregation and pagination
Write an upsert or bulk write	DML and upserts
Add an index	index basics, plus advanced indexes for partial, expression, multicolumn, covering, GIN, JSONB, array, or range indexes
Add a database function	functions and procedures
Add a trigger	triggers
Add a view or materialized view	views and materialized views
Configure roles, grants, or RLS	roles, privileges, and RLS
Other PostgreSQL policy work	guideline index

Core Behavior

• Workflows own multi-step procedures and route to their policy pages.
• Fast paths load only the directly linked owner pages.
• Use the guideline index only when no workflow or fast path matches.
• Select conditional pages using task descriptions in this router, the guideline index, or workflow routing.
• After loading a conditional page, apply it only when its Activation section matches.
• Treat live-database migrations as stricter than greenfield DDL.
• Prefer concrete PostgreSQL guidance over SQL tutorials.
• Ask one focused question only when required project context is missing.