pg_readme

Overview

Catalog release is 0.7.1; PGDG remains the RPM maintainer at 0.7.0, so the PIGSTY 0.7.1 RPM must not be published; PIGSTY maintains the 0.7.1 DEB package.

Version

Build

You can build the DEB packages for pg_readme using pig build:

pig build pkg pg_readme         # build DEB packages

Install

You can install pg_readme directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

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

Install the extension using pig or apt/yum/dnf:

pig install pg_readme;          # Install for current active PG version

pig ext install -y pg_readme -v 18  # PG 18
pig ext install -y pg_readme -v 17  # PG 17
pig ext install -y pg_readme -v 16  # PG 16
pig ext install -y pg_readme -v 15  # PG 15
pig ext install -y pg_readme -v 14  # PG 14

dnf install -y pg_readme_18       # PG 18
dnf install -y pg_readme_17       # PG 17
dnf install -y pg_readme_16       # PG 16
dnf install -y pg_readme_15       # PG 15
dnf install -y pg_readme_14       # PG 14

apt install -y postgresql-18-pg-readme   # PG 18
apt install -y postgresql-17-pg-readme   # PG 17
apt install -y postgresql-16-pg-readme   # PG 16
apt install -y postgresql-15-pg-readme   # PG 15
apt install -y postgresql-14-pg-readme   # PG 14

Create Extension:

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.