pg_readme

pg_readme : Generate a Markdown README from PostgreSQL COMMENT objects

Overview

Packages

Source

pig build pkg pg_readme;		# build deb

Install

Make sure PGDG and PIGSTY repo available:

pig repo add pgsql -u   # add both repo and update cache

Install this extension with pig:

pig install pg_readme;		# install via package name, for the active PG version

pig install pg_readme -v 18;   # install for PG 18
pig install pg_readme -v 17;   # install for PG 17
pig install pg_readme -v 16;   # install for PG 16
pig install pg_readme -v 15;   # install for PG 15
pig install pg_readme -v 14;   # install for PG 14

Create this extension with:

CREATE EXTENSION pg_readme CASCADE; -- requires hstore

Usage

Sources:

• pg_readme 0.7.1 README
• pg_readme 0.7.1 control file
• pg_readme 0.7.1 upgrade SQL
• Pigsty package matrix

pg_readme generates Markdown documentation for a PostgreSQL extension or schema from COMMENT objects and live catalog metadata. Use it to keep an extension’s README close to its SQL definitions and verify the generated output in source control.

Install and Generate Markdown

CREATE EXTENSION pg_readme CASCADE;

SELECT pg_extension_readme('my_extension'::name);
SELECT pg_schema_readme('my_schema'::regnamespace);

The control file requires hstore, is relocatable, and permits non-superuser installation when the caller can install its dependencies and create the objects.

Add Processing Instructions

Put Markdown and processing instructions in the extension or schema comment:

COMMENT ON EXTENSION my_extension IS $markdown$
### `my_extension`

What the extension does.

### Reference

<?pg-readme-reference?>

### Colophon

<?pg-readme-colophon?>
$markdown$;

<?pg-readme-reference?> expands to a catalog-derived object reference. <?pg-readme-colophon?> adds generation metadata. Optional instruction attributes can adjust the heading depth when embedding generated sections.

Settings

• pg_readme.include_view_definitions: include view definitions; default true.
• pg_readme.include_routine_definitions_like: array of routine-name patterns whose definitions are included; default '{test__%}'.
• pg_readme.include_this_routine_definition: routine-local override for including the current definition.
• pg_readme.readme_url: upstream README link used by generated material.

Use SET options on a wrapper function or transaction when a project needs reproducible generation settings.

Version 0.7.1 and Caveats

• Version 0.7.1 fixes PostgreSQL 18 reference generation that could duplicate array/composite table types and NOT NULL markers.
• Upstream and the current Pigsty DEB package are 0.7.1, while the current Pigsty RPM package remains 0.7.0. Check pg_available_extension_versions before relying on the PostgreSQL 18 fix.
• Generated output reflects the current database catalog, installed extension versions, comments, and generation time. Review diffs instead of assuming two environments produce identical text.
• Catalog introspection does not replace hand-written operational guidance. Keep prerequisites, preload/restart behavior, upgrade notes, and unsafe operations in curated prose.
• The singular setting pg_readme.include_routine_definition_like appears in an old README wrapper example, but the documented current GUC is the plural pg_readme.include_routine_definitions_like.