Configuration Items¶
The following lists the various sections allowed in a configuration file and the items that are recognized by the Pyrseas utilities.
Augmenter¶
This section is used by the dbaugment utility (see dbaugment - Augment a database). Most of these are specified in the system configuration file delivered with Pyrseas, but can also be included or overridden in user or repository configuration files.
audit_columns: This section defines combinations of columns and triggers to be added to tables. Both columns and triggers are specified as YAML lists (to be consistent with dbtoyaml YAML output), although normally a single trigger will be necessary per column combination. The columns and triggers should reference previously defined items in the
columns
andtriggers
sections (see below). See Predefined Database Augmentations for audit columns defined in the systemconfig.yaml
.columns: This section defines prototype columns to be added to a table by Augmenter. For each column, a valid Postgres data type should be included.
You can also add a
not_null
constraint and adefault
specification. See Predefined Database Augmentations for columns defined in the systemconfig.yaml
. In a repository or user configuration file, you can also specify an alternate name for a previously defined column. For example, if you prefer that themodified_timestamp
columns be namedlast_update
, you can add the following to a configuration file:augmenter: columns: modified_timestamp: name: last_update
function_templates: This section defines the source text for the trigger functions (see below) using a template language. Any text enclosed in double braces, e.g.,
{{modified_by_user}}
, will be replaced, typically by a previously defined column or its alternate name (see above).functions: This section defines prototype trigger functions to be invoked by audit columns or other augmentations. The following items can be specified for each function:
- description: Text for a COMMENT statement on the function.
- language: Procedural language, e.g.,
plpgsql
, in which the function is written. - returns: Value should be
trigger
. - security_definer: Indicates whether the function is to be executed with the privileges of the user that created it. This is usually needed for audit column trigger functions.
- source: This is usually a reference to a function template (see
above) enclosed in double braces, e.g.,
{{functempl_audit_default}}
. However, in user or repository configurations, this can also be the actual text of the function.
See Predefined Database Augmentations for functions defined in the system configuration file.
schema pyrseas: This section currently defines three functions that may be installed in the
pyrseas
schema if thefull
audit columns specifications is added for Augmenter processing.schemas and tables: Multiple
schema schema-name
sections can be present, typically in a repository configuration file. Each such section can includetable table-name
items, and under each theaudit_columns
specifications to be added to the given table. For example:augmenter: schema public: table t1: audit_columns: default
triggers: This section defines the prototype triggers to be used with audit columns and other augmentations. The following items can be specified for each trigger:
- events: This is a list that can include one or more of
insert
,update
ordelete
(the latter is not used for audit columns but may be used in future augmentations). - level: This can take the values
row
orstatement
(usually the former). - name: This specifies the name to be given to a trigger. It can be
a template using
{{table_name}}
which will then be replaced with the actual table name on which the trigger will act. - procedure: This is the invocation name, e.g.,
audit_default()
of the function to be called when the trigger fires. - timing: This can take the values
before
orafter
(usually the former).
- events: This is a list that can include one or more of
Database¶
This section is primarily for a user configuration file. If you frequently connect to a particular host, port or as a given user, that are not the Postgres defaults, adding corresponding entries to your user configuration file allows you to automatically override the defaults. If for a given invocation you need to connect to or as a different host, port or user, you can still override the configuration using the command line options (see Common Command Line Options):
- host: Name of the host to connect. Please refer to the Postgres connection host documentation for details and defaults.
- port: Port number to connect to. See the Postgres connection port documentation for more.
- username: Name of the user to connect as. View the Postgres connection user documentation for more.
Datacopy¶
This section is normally in a user or repository configuration file. It is used by dbtoyaml and yamltodb to determine which tables should be exported from or imported to the database. It consists of schema names, using the format schema schema_name, followed by lists of table names. For example:
datacopy:
schema public:
- t1
- t2
schema s1:
- t3
Repository¶
This section is used by all utilities (but dbaugment does not fully support it). The “repository” is intended to be a version control, e.g., Git, Mercurial, or Subversion, repository.
- data: Path, relative to the root of the repository, where
dbtoyaml and yamltodb place or expect the
files containing data exported from or imported to the database. The
tables to be exported or imported are specified in the
Datacopy
section. The default value (defined in the systemconfig.yaml
) is metadata. - metadata: Path, relative to the root of the repository, where
dbtoyaml and yamltodb place or expect the YAML
specification files for the database objects when the
–multiple-files option is used. The default value (defined
in the system
config.yaml
) is metadata. - path: Absolute path to the root of the repository. This should
normally be specified in a user configuration file, or in a file
given with the
--config
option. If not specified, this defaults to the current working directory from which the utility is run.