design-postgres-tables

Designs PostgreSQL tables with data types, constraints, indexes, and partitioning guidance.

Updated Aug 15, 2025
One-click install
npx skills add https://github.com/yehezkieldio/topaz --skill design-postgres-tables-yehezkieldio
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: design-postgres-tables
Source: https://github.com/yehezkieldio/topaz/tree/main/.agents/skills/design-postgres-tables
Command: npx skills add https://github.com/yehezkieldio/topaz --skill design-postgres-tables-yehezkieldio

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Designing PostgreSQL schemas involves many subtle decisions—choosing data types, indexing strategies, constraints, and partitioning—where mistakes lead to slow queries, data anomalies, and painful migrations. This Skill provides a comprehensive reference of PostgreSQL best practices so you can design correct, performant tables the first time. ## Core Features & Use Cases - Data Type Selection: Guidance on choosing BIGINT identity columns, TIMESTAMPTZ, NUMERIC, TEXT, JSONB, arrays, ranges, and which types to avoid (serial, varchar(n), money, timestamp without time zone). - Indexing & Constraints: Covers B-tree, GIN, GiST, BRIN, partial, covering, and expression indexes, plus PK/FK/UNIQUE/CHECK/EXCLUDE constraint patterns including the manual FK indexing requirement. - Workload-Specific Design: Patterns for update-heavy, insert-heavy, and upsert-heavy tables, plus partitioning strategies, JSONB guidance, row-level security, and safe schema evolution. - Use Case: When building a new orders table, use this Skill to get a schema with an identity primary key, proper foreign key indexes, CHECK constraints on status values, NUMERIC for money, and TIMESTAMPTZ defaults. ## Quick Start Ask the AI to design a PostgreSQL schema for your use case, such as a users and orders table with proper indexes and constraints.

Frequently Asked Questions about design-postgres-tables

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

FAQPage Schema
How do I design a PostgreSQL table with proper indexes?

Define a primary key (prefer BIGINT GENERATED ALWAYS AS IDENTITY), add NOT NULL and CHECK constraints, then create indexes for columns you actually query. PostgreSQL does not auto-index foreign key columns, so add those indexes manually.

What data type should I use for primary keys in PostgreSQL?

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

Should I use JSONB or separate 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 queries, or extract frequently filtered 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.

Why does my PostgreSQL upsert require a unique index?

ON CONFLICT requires an exact matching unique index on the conflict target columns, and partial indexes do not qualify. Use EXCLUDED.column to reference would-be-inserted values and DO NOTHING when no update is needed.

What PostgreSQL data types should I avoid?

Avoid timestamp without time zone, char(n), varchar(n), money, timetz, and serial. Use timestamptz, text, numeric, and generated identity columns instead, and prefer PostGIS geometry over built-in geometric types.