postgresql-table-design

Designs and reviews PostgreSQL schemas covering data types, indexes, constraints, and partitioning.

Updated Apr 13, 2026
One-click install
npx skills add https://github.com/scoots31/engineering-playbook --skill postgresql-table-design-scoots31
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: postgresql-table-design
Source: https://github.com/scoots31/engineering-playbook/tree/main/references/postgresql
Command: npx skills add https://github.com/scoots31/engineering-playbook --skill postgresql-table-design-scoots31

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Designing a PostgreSQL schema without deep platform knowledge leads to common mistakes: missing foreign key indexes, wrong data types like timestamp without time zone, silent performance traps, and painful schema migrations later. This Skill encodes PostgreSQL-specific best practices so schemas are correct and performant from the start. ## Core Features & Use Cases - Data Type Guidance: Recommends correct types for every column, including TIMESTAMPTZ for time, NUMERIC for money, TEXT for strings, identity columns over serial, and JSONB with GIN indexing for semi-structured data. - Indexing & Constraints: Covers B-tree, composite, partial, expression, covering, GIN, GiST, and BRIN indexes, plus primary keys, foreign keys with manual indexing, UNIQUE NULLS NOT DISTINCT, CHECK, and EXCLUDE constraints. - Advanced Patterns: Addresses partitioning strategies, row-level security, generated columns, upsert-friendly design, update-heavy and insert-heavy workload tuning, safe schema evolution, and extensions like TimescaleDB, PostGIS, and pgvector. - Use Case: When designing a new orders table, apply this Skill to get an identity primary key, a foreign key with its own index, a CHECK constraint on status values, NUMERIC for totals, and TIMESTAMPTZ defaults, avoiding the gotchas that typically surface only in production. ## Quick Start Ask the AI to design or review a PostgreSQL table schema for your use case, such as "design a PostgreSQL schema for an orders and users system following best practices."

Frequently Asked Questions about postgresql-table-design

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

FAQPage Schema
How do I design a PostgreSQL table with best practices?

Start with a BIGINT GENERATED ALWAYS AS IDENTITY primary key, normalize to 3NF, add NOT NULL and DEFAULT where semantically required, and index the columns you actually query. Use TIMESTAMPTZ for time, NUMERIC for money, and TEXT for strings.

What data types should I use in PostgreSQL?

Use BIGINT for integers, DOUBLE PRECISION or NUMERIC for decimals, TEXT instead of VARCHAR(n), TIMESTAMPTZ instead of timestamp, and BOOLEAN with NOT NULL. Avoid serial, money, char(n), and timetz types entirely.

Does PostgreSQL automatically index foreign key columns?

No, PostgreSQL does not auto-index foreign key columns. You must create indexes on referencing columns manually to speed up joins and prevent locking issues during parent table deletes or updates.

When should I use JSONB versus regular columns in PostgreSQL?

Keep core relations in typed columns and use JSONB only for optional or semi-structured attributes. Index JSONB with GIN for containment and key-existence queries, and extract frequently filtered scalar fields into generated columns with B-tree indexes.

When should I partition a PostgreSQL table?

Partition tables exceeding roughly 100 million rows when queries consistently filter on the partition key, typically time. Use declarative RANGE partitioning for time-series, LIST for discrete values, or HASH for even distribution, and consider TimescaleDB for automation.

Why does adding a column with a default rewrite my entire PostgreSQL table?

Adding a NOT NULL column with a volatile default like now() or gen_random_uuid() forces a full table rewrite. Use non-volatile defaults for fast metadata-only changes, and rely on transactional DDL to test migrations safely.