Skip to content

Schema Reference

Every object in a pglifecycle project is validated against one of these schemas. They are the project format's contract; this reference is generated from them, so it cannot drift from what the tool enforces.

For where each file lives on disk, see Project Format.

Validating in an editor

Each schema is published as resolvable JSON Schema. Point yaml-language-server (VS Code, Neovim, Helix) at the one for the file you are editing to get completion and validation as you type:

# yaml-language-server: $schema=https://gmr.github.io/pglifecycle/schemata/table.json
---
name: users
schema: test

Objects

  • Project — project.yaml at the root of a project: the database-wide settings, and the objects that belong to the database rather than to a schema.
  • Aggregate — An Aggregate function computes a single result from a set of input values.
  • Cast — Defines an cast
  • Collation — A collation is a schema object that provides the locale rules used when sorting and comparing text.
  • Conversion — Defines a conversion between character set encodings
  • Domain — Creates a user-defined data type with optional constraints.
  • Event Trigger — Defines an Event Trigger
  • Foreign Data Wrapper — Foreign Data Wrappers provide a standardized way of handling access to remote data stores.
  • Function — Defines a function
  • Index — Defines an index on a table
  • Materialized View — Defines a materialized view
  • Operator — User defined comparison operator
  • Publication — A publication is essentially a group of tables whose data changes are intended to be replicated through logical replication.
  • Schema — A schema is essentially a namespace: it contains named objects (tables, data types, functions, and operators) whose names can duplicate those of other objects existing in other schemas. Named objects are accessed either by “qualifying” their names with the schema name as a prefix, or by setting a search path that includes the desired schema(s).
  • Sequence — Defines a sequence object
  • Statistics — Extended statistics on a table or materialized view (CREATE STATISTICS), which let the planner estimate columns that depend on each other
  • Server — A foreign server typically encapsulates connection information that a foreign-data wrapper uses to access an external data resource.
  • Subscription — The subscription represents a replication connection to the publisher.
  • Table — Defines a table
  • Tablespace — A tablespace allows superusers to define an alternative location on the file system where the data files containing database objects (such as tables and indexes) can reside.
  • Text Search — Defines all properties for text-search in a schema
  • Type — User defined data type. here are five forms of types. They respectively create a composite type, an enum type, a range type, a base type, or a shell type. A shell type is simply a placeholder for a type to be defined later. Shell types are needed as forward references when creating range types and base types, as discussed in those sections.
  • View — Defines a view

Roles and privileges

  • ACLs — Privileges on database objects, grouped by the kind of object they are on. Written under grants: or revocations: on the role, user, or group they apply to, so a role file is the whole story of what that role can do. ALL stands for every privilege the object type has. Append WITH GRANT OPTION to a privilege to let the grantee grant it onward.
  • Default Privileges — The privileges objects a role creates start with (ALTER DEFAULT PRIVILEGES FOR ROLE). Global and per-schema declarations compose, so they are kept as written.
  • Group — A group is a type of role that defines permissions for one or more users.
  • Role — A role is an entity that can own database objects and have database privileges.
  • User — A user is a role that is permitted to login to the database.
  • User Mapping — A user mapping typically encapsulates connection information that a foreign-data wrapper uses together with the information encapsulated by a foreign server to access an external data resource.

Shared definitions

  • Argument
  • Column — Defines a column in a table
  • Constraint — Defines a constraint
  • Dependencies — Objects this object depends on, for the cases the dependency graph cannot infer: an ordering the topological sort would otherwise get wrong, such as a foreign key between tables or an inheritance parent. Each entry names an object as schema.name, or unqualified for a schemaless type. A function or aggregate carries its argument signature (test.f(integer)) and a cast its types ((int4 AS timestamp)), since the name alone is ambiguous.
  • Foreign Key — Defines a foreign key on a table
  • Policy — Defines a row-level security policy on a table
  • Rule — Defines a rewrite rule on a table or view (CREATE RULE)
  • Trigger — Defines a trigger on a table

Per-schema container files

  • Casts — Specifies all user-defined casts in a schema
  • Conversions — Specifies all conversions in a schema
  • Operators — Specifies all user-defined operators in a schema
  • Types — Specifies all user-defined types in a schema