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 :program:`dbaugment` utility (see :doc:`dbaugment`). 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 :program:`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`` and ``triggers`` sections (see below). See :doc:`predefaug` for audit columns defined in the system ``config.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 a ``default`` specification. See :doc:`predefaug` for columns defined in the system ``config.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 the ``modified_timestamp`` columns be named ``last_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 :doc:`predefaug` 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 the ``full`` 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 include ``table table-name`` items, and under each the ``audit_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`` or ``delete`` (the latter is not used for audit columns but may be used in future augmentations). - level: This can take the values ``row`` or ``statement`` (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`` or ``after`` (usually the former). 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 :doc:`cmdargs`): - 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 :program:`dbtoyaml` and :program:`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 :program:`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 :program:`dbtoyaml` and :program:`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 system ``config.yaml``) is **metadata**. - metadata: Path, relative to the root of the repository, where :program:`dbtoyaml` and :program:`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 :option:`--config` option. If not specified, this defaults to the current working directory from which the utility is run.