Smokes your problems, coughs fresh air.

pg_readme: generating a README.md from the COMMENTs in a PostgreSQL extension or schema

I released pg_readme a couple of days ago. From the (auto-generated, inception-style, by pg_readme) README.md:

The pg_readme PostgreSQL extension provides functions to generate a README.md document for a database extension or schema, based on COMMENT objects found in the pg_description system catalog.

This is a split-off from the PostgreSQL database structure that I’ve developed for the backend of our managed MQTT hosting platform. There will be many more of split-off PostgreSQL extensions to follow. Although I like my home-grown migration framework (soon to also be released), pushing reusable parts of schemas into separate extensions has a couple of advantages:

  1. easier sharing between projects;
  2. more decoupling between schemas, making migrations easier;
  3. more documentation and testing discipline due to releasing code as open source (peeing in public); and
  4. simpler, cleaner, more well-boundaried code.

3 Comments

  1. Rowan Rodrik

    Version 0.2.0 of pg_readme has now been released, with support for generating a reference of all the objects in a schema instead of all the objects belonging to an extension.

    It’s still a long (though not complicated) road to pg_readme 1.0. I do expect to be pretty damn close by the time that our FlashMQ MQTT hosting platform is live by the beginning of next quarter.

  2. Rowan Rodrik

    On the heels of version 0.2.0, today saw the release of pg_readme version 0.3.0, with even more goodness. I am seriously aiming to make pg_readme the go-to solution for Postgres extension makers, and for people wishing to document their own in-house schemas. If you’re missing anything, do let me know; it may motivate me to release those features quicker.

  3. Rowan Rodrik

    pg_readme is now also available via the PostgreSQL Extension Network (PGXN): https://pgxn.org/dist/pg_readme/

© 2024 BigSmoke

Theme by Anders NorenUp ↑