Smart Comments

Ensure you've read the Smart Tags page before referring here.

You can customise your PostGraphile GraphQL schema without making breaking changes to your database schema by adding specially formatted comments to tables, columns, functions, relations, etc. within your PostgreSQL database. We call these "smart comments".

Smart comment spec

Comments can be added to various entities within PostgreSQL using the COMMENT statement; we add a special syntax to these comments that enables PostGraphile to treat them as smart comments.

A smart comment is made up of one or more "tags" and optionally followed by the remaining comment. Leading spaces and tabs are ignored. If the very first line is blank, that is also ignored. Tags may have a string payload (which follows the tag and a space, and must not contain newline characters) and are separated by newlines (\n or \r\n). Tags always start with an @ symbol and must always come before the remaining comment, hence all smart comments start with an @ symbol. If a tag has no payload then its value will be the boolean true, otherwise it will be a string. If the same tag is present more than once in a smart comment then its final value will become an array of the individual values for that tag.

The following text could be parsed as a smart comment (the smart comment values shown are examples only, and don't have any meaning):

@name meta
@isImportant
@jsonField date timestamp
@jsonField name text
@jsonField episode enum ONE=1 TWO=2
This field has a load of arbitrary tags.

and would result in the following JSON tags object:

{
  "name": "meta",
  "isImportant": true,
  "jsonField": ["date timestamp", "name text", "episode enum ONE=1 TWO=2"]
}

and the description on the last line (This field has a load of arbitrary tags.) would be made available as documentation as regular comments are.

Note that the parser is deliberately very strict currently, we might make it more flexible in future; you might want to check out the test suite.

Adding newlines

We recommend you define smart tags using dollar quoting, which makes adding newlines natural. We support both LF and CRLF line endings (and treat them the same).

Traditionally we recommended the use of the E "escape" string constants, wherein you can use \n for newlines, but that was before we made the parser less strict.

comment on column my_schema.my_table.my_column is $$
@name meta
@isImportant
@jsonField date timestamp
@jsonField name text
@jsonField episode enum ONE=1 TWO=2
This field has a load of arbitrary tags.
$$;

Note that adding two newlines in a row separates the smart tags section from the descriptive prose. Content after two newlines will not be parsed for smart tags even if it starts with an @ character.

For example:

comment on column my_schema.my_table.my_column is $$
@name meta
@isImportant
@jsonField date timestamp
@jsonField name text

This field has a load of arbitrary tags.
@jsonField episode enum ONE=1 TWO=2
$$;

results in the following JSON tags object:

{
  "name": "meta",
  "isImportant": true,
  "jsonField": ["date timestamp", "name text"]
}

and the description:

This field has a load of arbitrary tags.
@jsonField episode enum ONE=1 TWO=2

Applying smart tags to database entities

Tables

comment on table my_schema.my_table is
  E'@name my_new_table_name\n@omit update,delete\nThis is the documentation.';

Views

comment on view my_schema.mv_view is
  E'@name my_new_view_name\n@omit update,delete\nThis is the documentation.';

Materialized Views

comment on materialized view my_schema.mv_view is
  E'@name my_new_view_name\n@omit update,delete\nThis is the documentation.';

Types

comment on type my_schema.my_type is
  E'@name my_new_type_name\nThis is the documentation.';

Columns

comment on column my_schema.my_table.my_column is
  E'@name my_new_column\n@omit create,update\nThis is the documentation.';

Constraints

comment on constraint my_constraint on my_schema.my_table is
  E'@foreignFieldName foos\n@fieldName bar\nDocumentation here.';

Functions

comment on function my_function(arg_type_1, arg_type_2) is
  E'@name my_new_function_name\nDocumentation here.';

Adding smart tags to fake constraints

If you need to apply any smart comments to a fake constraint, you cannot use newlines (\n) because they will be interpretted as separate smart comments on the original entity. We've added a workaround for this: you can use the pipe (|) symbol to assign smart comments to the fake constraint, for example to rename the fake constraint:

comment on materialized view my_materialized_view is
  E'@foreignKey (post_id) references posts (id)|@fieldName yourNameHere';