Skip to main content

PostgreSQL table and column comments that create living docs

2025-08-30

Introduction

Good documentation does not live in a separate file that drifts. The fastest way to keep knowledge current is to place it where engineers look every day. PostgreSQL gives you first class support for table and column comments. With a small habit you can create living docs that help onboarding, reduce mistakes, and speed up reviews.

This guide shows how to use comments well, how to audit coverage with simple queries, and how to keep everything under version control.

Why native comments

  • Comments travel with the schema through dumps and migrations
  • Comments show up in tools and in psql describe output
  • Comments reduce context switching during reviews
  • Comments are easy to export to Markdown or PDF later

External suites can be powerful in large programs, yet they often add cost and setup time. Native comments give immediate value to small and mid sized teams and they pair nicely with a focused documentation tool.

Quick start

PostgreSQL supports comments at many levels. The most useful are table and column.

-- Table level comment
COMMENT ON TABLE public.orders IS
'Stores customer orders. One row per order. Created by checkout flow.';

-- Column level comments
COMMENT ON COLUMN public.orders.order_id IS
'Primary key generated by sequence orders_order_id_seq.';

COMMENT ON COLUMN public.orders.customer_id IS
'Reference to customers.customer_id. Required.';

COMMENT ON COLUMN public.orders.total_amount IS
'Amount in cents. Includes tax. Non negative.';

COMMENT ON COLUMN public.orders.created_at IS
'UTC timestamp of order creation. Immutable after insert.';