pg_readme

Overview

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:

• Install
• pig
• dnf
• apt

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

pg_readme: Auto-generate README documentation from PostgreSQL COMMENT objects

Generates README.md documents for extensions or schemas based on COMMENT objects in the pg_description system catalog.

Generate Extension README

SELECT pg_extension_readme('my_extension'::name);

Generate Schema README

SELECT pg_schema_readme('my_schema'::regnamespace);

Processing Instructions

Include these XML processing instructions in your COMMENT ON EXTENSION or COMMENT ON SCHEMA:

• <?pg-readme-reference?> – replaced with a full object reference
• <?pg-readme-colophon?> – adds a colophon with pg_readme info

Typical Workflow

Create a readme-generating function in your extension:

CREATE FUNCTION my_ext_readme() RETURNS text
    VOLATILE SET search_path FROM current
    SET pg_readme.include_view_definitions TO 'true'
    LANGUAGE plpgsql AS $$
DECLARE _readme text;
BEGIN
    CREATE EXTENSION IF NOT EXISTS pg_readme WITH VERSION '0.1.0';
    _readme := pg_extension_readme('my_extension'::name);
    RAISE transaction_rollback;
EXCEPTION WHEN transaction_rollback THEN RETURN _readme;
END; $$;

Then generate with: make README.md

Settings