postgresql-table-design

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

Updated Jul 28, 2026
One-click install
npx skills add https://github.com/truongnat/Restly --skill postgresql-table-design-truongnat
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: postgresql-table-design
Source: https://github.com/truongnat/Restly/tree/main/.agents/skills/postgresql-table-design
Command: npx skills add https://github.com/truongnat/Restly --skill postgresql-table-design-truongnat

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Designing a PostgreSQL schema involves many version-specific decisions—choosing between identity columns and UUIDs, picking the right index type, avoiding types like timestamp or serial—and mistakes lead to slow queries, bloated tables, and painful migrations. This Skill encodes PostgreSQL best practices so schemas are correct and performant from the start. ## Core Features & Use Cases - Schema Design Guidance: Covers primary keys, normalization to 3NF, NOT NULL/DEFAULT usage, and correct data type selection (TIMESTAMPTZ, NUMERIC, TEXT, BIGINT, JSONB). - Indexing & Performance Patterns: Explains B-tree, GIN, GiST, BRIN, partial, covering, and expression indexes, plus partitioning strategies and update/insert-heavy workload tuning. - PostgreSQL Gotcha Detection: Flags common pitfalls such as unindexed foreign keys, UNIQUE with multiple NULLs, volatile defaults causing table rewrites, and discouraged types like money and varchar(n). - Use Case: When creating a new orders table, apply this Skill to get an identity primary key, an indexed foreign key to users, a CHECK-constrained status column, and a TIMESTAMPTZ created_at with proper defaults. ## Quick Start Ask the AI to design a PostgreSQL schema for your entities, or paste an existing CREATE TABLE statement and request a review against PostgreSQL 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?▼

Use BIGINT GENERATED ALWAYS AS IDENTITY for primary keys, TIMESTAMPTZ for timestamps, NUMERIC for money, and TEXT for strings. Add NOT NULL where semantically required, index foreign key columns manually, and normalize to 3NF before considering denormalization.

Should I use UUID or BIGINT for PostgreSQL primary keys?▼

Prefer BIGINT GENERATED ALWAYS AS IDENTITY for most tables since it is compact and efficient. Use UUID only when you need global uniqueness across distributed systems or opaque identifiers, generated with uuidv7() on PG18+ or gen_random_uuid() on older versions.

Does PostgreSQL automatically index foreign key columns?▼

No, PostgreSQL does not automatically create indexes on foreign key columns. You must add them manually to speed up joins and prevent locking issues when parent rows are deleted or updated.

When should I use JSONB vs regular columns in PostgreSQL?▼

Keep core relational data 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.

Why is my PostgreSQL table rewrite happening after adding a column?▼

Adding a NOT NULL column with a volatile default like now() or gen_random_uuid() rewrites the entire table. Use non-volatile defaults for fast metadata-only changes, or add the column nullable and backfill values separately.

When should I partition a PostgreSQL table?▼

Partition tables exceeding roughly 100M rows when queries consistently filter on the partition key, typically a time or date column. Use declarative RANGE, LIST, or HASH partitioning, and remember that unique constraints must include the partition key.