feat: Add initial PostgreSQL best practices rules

[Rodriguespn]

PostgreSQL Best Practices Rules

Note: This PR was authored by Claude. Team members are encouraged to review, edit, or remove any content that may be inaccurate or could be improved. This is meant to be a collaborative starting point, not a final implementation.

Summary

This repository contains 30 PostgreSQL best practices rules organized into 8 categories by priority and impact.

Rules Included

Query Performance (5 rules) - CRITICAL/HIGH

Rule	Impact	Description
query-missing-indexes.md	CRITICAL	Add indexes on WHERE and JOIN columns
query-partial-indexes.md	HIGH	Use partial indexes for filtered queries
query-composite-indexes.md	HIGH	Create composite indexes for multi-column queries
query-covering-indexes.md	MEDIUM-HIGH	Use covering indexes to avoid table lookups
query-index-types.md	HIGH	Choose the right index type (B-tree, GIN, BRIN, Hash)

Connection Management (4 rules) - CRITICAL/HIGH

Rule	Impact	Description
conn-pooling.md	CRITICAL	Use connection pooling for all applications
conn-limits.md	CRITICAL	Set appropriate connection limits
conn-idle-timeout.md	HIGH	Configure idle connection timeouts
conn-prepared-statements.md	HIGH	Use prepared statements correctly with pooling

Schema Design (5 rules) - HIGH/MEDIUM-HIGH/MEDIUM

Rule	Impact	Description
schema-data-types.md	HIGH	Choose appropriate data types
schema-primary-keys.md	HIGH	Select optimal primary key strategy
schema-foreign-key-indexes.md	HIGH	Index foreign key columns
schema-partitioning.md	MEDIUM-HIGH	Partition large tables for better performance
schema-lowercase-identifiers.md	MEDIUM	Lowercase schema identifiers for better consistency

Concurrency & Locking (4 rules) - MEDIUM-HIGH

Rule	Impact	Description
lock-short-transactions.md	MEDIUM-HIGH	Keep transactions short to reduce lock contention
lock-skip-locked.md	MEDIUM-HIGH	Use SKIP LOCKED for non-blocking queue processing
lock-advisory.md	MEDIUM	Use advisory locks for application-level locking
lock-deadlock-prevention.md	MEDIUM-HIGH	Prevent deadlocks with consistent lock ordering

Security & RLS (3 rules) - MEDIUM-HIGH/HIGH

Rule	Impact	Description
security-rls-basics.md	MEDIUM-HIGH	Enable RLS for multi-tenant data
security-rls-performance.md	HIGH	Optimize RLS policies for performance
security-privileges.md	MEDIUM	Apply principle of least privilege

Data Access Patterns (4 rules) - MEDIUM/MEDIUM-HIGH

Rule	Impact	Description
data-n-plus-one.md	MEDIUM-HIGH	Eliminate N+1 queries with batch loading
data-pagination.md	MEDIUM-HIGH	Use cursor-based pagination instead of OFFSET
data-upsert.md	MEDIUM	Use UPSERT for insert-or-update operations
data-batch-inserts.md	MEDIUM	Batch INSERT statements for bulk data

Monitoring & Diagnostics (3 rules) - MEDIUM/LOW-MEDIUM

Rule	Impact	Description
monitor-explain-analyze.md	LOW-MEDIUM	Use EXPLAIN ANALYZE to diagnose slow queries
monitor-pg-stat-statements.md	LOW-MEDIUM	Enable pg_stat_statements for query analysis
monitor-vacuum-analyze.md	MEDIUM	Maintain table statistics with VACUUM and ANALYZE

Advanced Features (2 rules) - MEDIUM

Rule	Impact	Description
advanced-jsonb-indexing.md	MEDIUM	Index JSONB columns for efficient querying
advanced-full-text-search.md	MEDIUM	Use tsvector for full-text search

Design Decisions

1. Concise Format: Each rule is 25-60 lines, following the established
   pattern:

   • YAML frontmatter with impact level
   • 1-sentence explanation
   • Incorrect/Correct SQL examples
   • Reference link

2. Quantified Impact: Every rule includes specific metrics (e.g., "10-100x
   faster", "3x throughput").

3. Error-First Structure: Shows the anti-pattern first, then the correct
   approach.

Validation

cd packages/postgresql-best-practices-build
npm run validate
npm run build

[gregnr]

Nice work. Just one small comment. Also doesn't have to be in this PR, but I think we should also do this before launch.

[Rodriguespn]

Also doesn't have to be in this PR, but I think we should also do #2 before launch.

Agree and thanks for the suggestion. It's now on main

[gregnr]

Let's fix this before merging

[Rodriguespn]

Merging this as we reached a consensus about the initial postgres rules. Thanks everyone for the collaboration!