database-patterns

Document PostgreSQL schema design, indexing, and migration patterns.

5|Updated Mar 30, 2026
One-click install
npx skills add https://github.com/jeanpaulsio/nunchuck-skills --skill database-patterns-jeanpaulsio
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: database-patterns
Source: https://github.com/jeanpaulsio/nunchuck-skills/tree/main/skills/database-patterns
Command: npx skills add https://github.com/jeanpaulsio/nunchuck-skills --skill database-patterns-jeanpaulsio

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Deep reference for PostgreSQL schema design, query optimization, indexing, migration safety, and data modeling. Focused on patterns that prevent costly refactors.

Core Features & Use Cases

  • Schema Design Principles: One Concern Per Table; Domain Names; Status Enums; Timestamps on Everything; Nullable Foreign Keys for Optional Relationships.
  • Data Modeling Decisions: UUID vs Integer PKs; Join Table Design; Partial Unique Indexes; JSONB for Semi-Structured Data; When to Denormalize; Atomic Updates.
  • Indexing Strategy: Index Your WHERE Clauses; Composite Indexes; PostgreSQL FK Indexing; Don't Index Everything; EXPLAIN ANALYZE.
  • Query Optimization: Explicit Column Selection; Avoid ORDER BY random(); N+1 Query Detection; Aggregate Subqueries.
  • Migration Safety: Never Use create_all(); Always Test Against Postgres; Review Autogenerated Migrations; Never Edit an Applied Migration; Lock-Aware Operations.
  • Enum Patterns; Soft Delete; Audit Logging; Connection Management.
  • Quick Reference: Summary of common fixes and guidelines.

Quick Start

Review a current schema change and apply these PostgreSQL patterns to ensure safer migrations and robust data models.

Frequently Asked Questions about database-patterns

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What are the best PostgreSQL schema design patterns to prevent costly refactors?

To design scalable PostgreSQL schemas, apply one concern per table, use status enums, add timestamps to everything, and use nullable foreign keys for optional relationships. These patterns ensure maintainable data models and prevent costly refactoring.

How do I ensure migration safety when modifying PostgreSQL database schemas?

To ensure PostgreSQL migration safety, never use create_all(), always test against Postgres, review autogenerated migrations, never edit an applied migration, and execute lock-aware operations to prevent downtime and data corruption.

When should I use UUID vs Integer primary keys in PostgreSQL data modeling?

UUID vs Integer primary keys is a key PostgreSQL data modeling decision. UUIDs provide distributed generation benefits and avoid integer overflow, while Integers offer smaller storage and faster indexing. Choose based on your application's scale and distributed requirements.

What is the correct indexing strategy for optimizing PostgreSQL query performance?

PostgreSQL indexing strategy involves indexing your WHERE clauses, using composite indexes for multi-column queries, indexing foreign keys, and avoiding over-indexing. Use EXPLAIN ANALYZE to verify query optimization and ensure indexes improve performance without unnecessary overhead.

How do I detect and avoid N+1 queries in PostgreSQL applications?

N+1 query detection in PostgreSQL involves identifying inefficient loops that execute individual queries for related records. Avoid them by using explicit column selection, aggregate subqueries, and proper join table design to optimize data retrieval and reduce database connection overhead.

Can I use JSONB for semi-structured data in PostgreSQL without affecting schema maintainability?

JSONB for semi-structured data in PostgreSQL allows flexible schema evolution without migrations. It supports partial unique indexes and atomic updates, making it suitable for variable data structures while maintaining query optimization and schema design integrity.