pg_readme

pg_readme

pg_readme : Generate a README.md document for a database extension or schema

Overview

IDExtensionPackageVersionCategoryLicenseLanguage
4300
pg_readme
pg_readme
0.7.0
UTIL
PostgreSQL
C
AttributeHas BinaryHas LibraryNeed LoadHas DDLRelocatableTrusted
----d-r
No
No
No
Yes
yes
no
Relationships
Requires
hstore
See Also
ddl_historization
schedoc
pg_render
gzip
bzip
zstd
http
pg_net
Siblings
pg_readme_test_extension

Packages

TypeRepoVersionPG Major CompatibilityPackage PatternDependencies
EXT
MIXED
0.7.0
18
17
16
15
14
pg_readmehstore
RPM
PGDG
0.7.0
18
17
16
15
14
pg_readme_$v-
DEB
PIGSTY
0.7.0
18
17
16
15
14
postgresql-$v-pg-readme-
Linux / PGPG18PG17PG16PG15PG14
el8.x86_64
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
el8.aarch64
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
el9.x86_64
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
el9.aarch64
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
el10.x86_64
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
el10.aarch64
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
PGDG 0.7.0
d12.x86_64
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
d12.aarch64
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
d13.x86_64
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
d13.aarch64
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
u22.x86_64
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
u22.aarch64
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
u24.x86_64
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
u24.aarch64
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0
PIGSTY 0.7.0

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

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

SettingDefault
pg_readme.include_view_definitionstrue
pg_readme.include_routine_definitions_like'{test__%}'
pg_readme.include_this_routine_definitionnull
Last updated on