Postgrest: Expose comments on views and columns

[sveniu]

This is a feature request to expose PG's object comments for views and their columns.

Several meta attributes are already exposed via the OPTIONS method, for both views and columns. For views, the comment can be fetched with obj_description(object_oid, catalog_name). For columns within a view, the view OID must be accompanied by the column's position; this is already fetched – presumably via the information_schema.columns.ordinal_position column – and then fed to col_description(table_oid, column_number).

PG itself mixes the terms "comment" and "description", so I'm not sure which one would make most sense to use in the API.

[begriffs]

Very cool idea for documenting the API. :+1:

How would you say the resulting JSON response from OPTIONS should look when extended with the new information?

[sveniu]

For GET or OPTIONS requests to /, I imagine simply adding a "description" attribute to each view's json object. This description would then be extracted verbatim from the comment added to the view in postgres.

For OPTIONS requests to a /view, I imagine that the view description is available as a top-level "description" attribute, and a column "description" attribute is available in each column's json object.

Since the comment is a plain text string, it probably makes sense to make it available verbatim, without any processing.

[diogob]

+1

[dweinstein]

👍

would be awesome to see the comments for table and columns in the OPTIONS response and calling it description in each object.

would this be a good first contribution for someone?

[diogob]

That would be a good issue to get acquainted with the code indeed. @dweinstein if you need any help feel free to ping me ;)

[FGRibreau]

:+1: this could be used in the OpenAPI/Swagger spec (Postgraphql does that as well for GraphQL).

[begriffs]

Sure, sounds feasible. When we build our cache of the db structure we can obtain that info as well. Now that we use OpenAPI for documentation rather than the old system it should be more straightforward to expose.

@dweinstein are you interested in giving this contribution a try? You can open a pull request with preliminary work if you like and we can discuss it there and help you out.

[ruslantalpa]

Implemented in #885 plus you can have your custom view describing the api in the format you want by using a query/view like this one https://gist.github.com/ruslantalpa/b2f10eb1b5f6dd0fc1c154e071a1c91b