Add support for Postgres COMMENT ON to generate JS docstring

Docs: https://www.postgresql.org/docs/current/sql-comment.html

Given this table:

create table foo (
  bar text
)
comment on table foo is 'Table Foo has everything.
Even bars.'
comment on column foo.bar is 'The bar is closed.'

I would like this generated:

/**
 * Table Foo has everything.
 * Even bars.
 */
export interface FooEntity {
  /** The bar is closed. */
  bar: string
}

I believe that https://github.com/kristiandupont/kanel supports this.

Actually, looking at their examples, It would also be awesome to print comments with more information about the field (like index, default value, etc). This way when you are in your application code in your IDE, you can easily see whether a column has an index, for example.

[rmp135]

I’ve implemented importing comments from tables, views and columns based on the following. I’ve tested across all providers and they work as intended far as I can tell. It’s quite nice as it adds the comment to the TypeScript popover.

Provider	Source
MySQL	“Comments” field
SQL Server	Extended property with name “MS_Description”
Postgres	“Comment” field
SQLite	Not supported

I haven’t implemented the more verbose commenting. Most of the info can already be added using the template and hopefully this comment extraction can help with anything more expressive.

[DarkRoku12]

Hi, i did some research on this.

In order to support full commentaries and other information, we should get oid values to query other system tables.

The current Postgres adapter: https://github.com/rmp135/sql-ts/blob/71c9a4ad459921e4b21a807fb7d1e90d20be1467/src/Adapters/postgres.ts#L42-L65 does not expose the oid, thus, it cannot provide additional information.

In order to fix that, we should use the system tables instead of the system views, I’ve crafted some queries that will help us to achieve that, while maybe also adding extra functionality in case we need it.

For tables:

WITH schemas AS (
SELECT nspname AS name, oid AS oid
FROM pg_namespace
WHERE nspname <> 'information_schema' AND nspname NOT LIKE 'pg_%'
-- Here we may add more filters to filter out schemas, by convention 'pg_' are Posgtres internal schemas.
)
SELECT schemas.name                                          AS schema,
     pg_class.relname                                        AS name,
     pg_catalog.OBJ_DESCRIPTION( pg_class.oid , 'pg_class' ) AS commentary --> Get the table commentary of <null> if doesn't exists.
FROM pg_class
     JOIN schemas ON schemas.oid = pg_class.relnamespace
WHERE pg_class.relkind IN ( 'r' , 'p' , 'v' , 'm' );
/*
r = base relation (table).
p = partitioned table.
v = view
m = materialized view
--> https://www.postgresql.org/docs/current/catalog-pg-class.html  (search for relkind)
Maybe we could add a json option to support what kind of relations do we want?
*/

For columns:

It will be as simple as adding this line: pg_catalog.col_description( pg_class.oid , pg_attribute.attnum ) as commentary, to the SQL part of https://github.com/rmp135/sql-ts/blob/71c9a4ad459921e4b21a807fb7d1e90d20be1467/src/Adapters/postgres.ts#L67-L106 plus adding the corresponding JS/TS code.

I’d do this myself, but I don’t have enough time yet, but I’ll be sure to use this library on an important commercial project in my country.

Bonus:

If we would like to get commentaries and indexes information, to likely use the handlebars file to format it like

/***
@index  
   - traits: PRIMARY KEY | UNIQUE
   - name : table_pk
   - columns: id
@index 
   - traits: -
   - name : my_index_name
   - columns: col_a , col_b 
*/

I’ve craft this queries that should include proper index & foreign keys + checks metadata along with the table information.

WITH schemas     AS ( -- Query all schemas
  SELECT nspname AS name, oid AS oid
  FROM pg_namespace
  WHERE nspname <> 'information_schema' AND nspname NOT LIKE 'pg_%'
)
   , tables      AS ( -- Query all tables [using schemas]
  SELECT schemas.name                                            AS schema,
         pg_class.relname                                        AS name,
         pg_catalog.OBJ_DESCRIPTION( pg_class.oid , 'pg_class' ) AS commentary,
         pg_class.oid                                            AS oid
  FROM pg_class
         JOIN schemas ON schemas.oid = pg_class.relnamespace
  WHERE pg_class.relkind IN ( 'r' , 'p' , 'v' , 'm' )
)
   , indexes     AS ( -- Query all indexes [using tables]
  SELECT tables.oid                                             AS table_oid,
         idx_class.oid                                          AS index_oid,
         idx_class.relname                                      AS name,
         pg_catalog.PG_GET_INDEXDEF( idx_class.oid , 0 , TRUE ) AS definition,
         indisprimary                                           AS is_primary_key,
         indisunique                                            AS is_unique,
         indisexclusion                                         AS is_exclude,
         indisclustered                                         AS is_clustered,
         idx_cols.columns                                       AS columns
  FROM pg_index
         JOIN      tables ON tables.oid = pg_index.indrelid
         LEFT JOIN pg_class AS idx_class ON idx_class.oid = pg_index.indexrelid
         LEFT JOIN LATERAL (
                     SELECT ARRAY_AGG( attname ) AS columns
                     FROM pg_attribute
                     WHERE pg_attribute.attrelid = tables.oid AND pg_attribute.attnum = ANY ( pg_index.indkey )
                     )         idx_cols ON TRUE
)
   , constraints AS ( -- Query check & foreign keys.

  SELECT tables.oid                                                  AS table_oid,
         pg_constraint.oid                                           AS constraint_oid,
         pg_constraint.conname                                       AS name,
         pg_catalog.PG_GET_CONSTRAINTDEF( pg_constraint.oid , TRUE ) AS defintion
  FROM pg_constraint
         JOIN tables ON tables.oid = pg_constraint.conrelid
  WHERE pg_constraint.contype IN ( 'f' , 'c' )
)
-- Get everything important from previous queries.
SELECT tables.*, COALESCE( idxs_joined.data , '[]' ) AS indexes, COALESCE( con_joined.data , '[]' ) AS constraints
FROM tables
       LEFT JOIN LATERAL (
                   SELECT JSON_AGG( indexes.* ) AS data FROM indexes WHERE indexes.table_oid = tables.oid
                   ) idxs_joined ON TRUE
       LEFT JOIN LATERAL (
                   SELECT JSON_AGG( constraints.* ) AS data FROM constraints WHERE constraints.table_oid = tables.oid
                   ) con_joined ON TRUE;

---

BTW, This is such an excellent library, very well documented, crafted, non-opinionated, clean, and do perfectly what it should do.