smartcomments

Overview ¶

Package smartcomments is a built-in plugin that turns PostGraphile-style "smart comments" — database COMMENTs whose leading lines start with '@' — into schema customization, so the generated API can be tuned with plain DDL and no pdbq configuration:

COMMENT ON TABLE app.people_raw IS E'@name people\n@omit update,delete';
COMMENT ON COLUMN app.users.hashed_password IS '@omit';
COMMENT ON CONSTRAINT posts_author_id_fkey ON app.posts IS '@fieldName writer';
COMMENT ON VIEW app.metrics IS E'@primaryKey name\n@unique label';
COMMENT ON FUNCTION app.users_score(app.users) IS '@filterable';

Supported tags (see docs/plugins.md for the full reference):

• @omit [actions] — on tables (bare, read, all, many, create, update, delete, filter, order), columns (bare, read, create, update, filter, order), foreign keys (bare, many, filter), unique constraints (bare), and functions (bare, plus filter/order for computed columns, honored by advanced-filters).
• @name <new_name> — rename a table, column, enum, or function; the value replaces the pg name at the start of the inflection pipeline, so every derived name (type, queries, mutations, filters) follows.
• @fieldName / @foreignFieldName <name> — on a foreign key: exact GraphQL name for the forward (child -> parent) / backward (parent -> children) relation field; also picked up by advanced-filters and nested-mutations.
• @deprecated [reason] — on columns and functions: marks the generated output fields with @deprecated(reason:).
• @notNull / @nullable — on columns: override introspected nullability (views lose NOT NULL information).
• @filterable / @sortable — on columns: opt in to filtering and ordering despite filters.indexed_only; on foreign keys / computed functions: opt in when advanced-filters runs in opt-in mode.
• @primaryKey col[, col] — on a view (or PK-less table): declare a logical primary key, enabling nodeId, single-row lookups, and keyset pagination. Mutations stay gated by real privileges.
• @unique col[, col] — on tables/views: declare a logical unique constraint, generating a single-row lookup field (repeatable).
• @foreignKey (col, ...) references [schema.]table (col, ...) — on tables/views: declare a logical foreign key, generating relation fields both ways (repeatable; append |@fieldName x|@foreignFieldName y to name them).

Tag lines are stripped from the GraphQL descriptions; the rest of the comment remains the description. Everything happens at schema-build time — the compiler is untouched, and disabling the plugin (plugins.disabled: [smart-comments]) restores the raw schema.