# Documenting your PostgreSQL database

DevFeed: [Documenting your PostgreSQL database](<https://devfeed.tech/articles/documenting-your-postgresql-database-41146.md>)

Original publisher: [Read original article](<https://www.craigkerstiens.com/2013/07/29/Documenting-your-PostgreSQL-database/>)

Author: Map

Published: 2013-07-29T20:55:56Z

Content type: tutorial

Language: en

Sources: [Craig Kerstiens](<https://devfeed.tech/sources/craig-kerstiens.md>)

Topics: [PostgreSQL](<https://devfeed.tech/topics/postgresql.md>), [Databases](<https://devfeed.tech/topics/databases.md>), [SQL](<https://devfeed.tech/topics/sql.md>), [Code](<https://devfeed.tech/topics/code.md>)

Tags: [code](<https://devfeed.tech/tags/code.md>), [database](<https://devfeed.tech/tags/database.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [postgres](<https://devfeed.tech/tags/postgres.md>), [postgresql](<https://devfeed.tech/tags/postgresql.md>), [sql](<https://devfeed.tech/tags/sql.md>)

## AI overview

The article explains how PostgreSQL COMMENT statements can document tables, columns, functions, schemas, views, and indexes directly within a database. It argues that in-database documentation can support clearer reporting and remain more accessible than separate documentation.

## Source excerpt

Just a few days ago I was surprised by what someone was doing with their database, and not in the typical horrifying travesty against mankind. Rather, it was a feature that while familiar with I'd never seen anyone fully take proper advantage of - COMMENT or describing tables. Postgres has a nice facility for you to provide a description for just about anything: Table Column Function Schema View Index Etc. The specific use case was a database acting as a datamart pulling in data from multiple sources to be able to report against disparate data. Over the years I've seen this occur really one three ways, the first is that a limited set of people, typically one person, have knowledge over all the datasources and thus far the sole individual responsible for creating reports and answering questions of the data. The second, is wide open access to anyone that wishes for it. In this case you often have people asking questions of the data, and because they don't understand the relationships coming up to entirely wrong conclusions. The final approach is to create some external documentation, entity relationship diagrams, data dictionaries, etc. This last one often works okay enough, but often suffers from lack of updates and being too heavyweight. A better solution, and all around good process is simply documenting clearly within the database itself. Simply comment each table and column, just as you would outside of your DB then it can be quite clear when inside the database working interactivly: COMMENT ON TABLE products IS 'Products catalog'; COMMENT ON COLUMN products.price is 'Current price of a single item purchased'; While an obvious example above naming even the most mundance columns can help create more accurate reports. Then of course when you want to inspect your DB its quite clear: \d+ users # \d+ users Table "public.users" Column | Type | ... | Description ------------+-----------------------------+-...-+----------------------------------------- id | integer | ...