Configuration Reference

Subject to change

During this active development phase, the configuration structure is subject to change.

The format of the configuration data varies between versions. When a connector subgraph is added to a project, a schema.json file is created in the configuration directory which describes the format of the configuration.json file.

Introduction

The configuration is a metadata object that lists all the database entities — such as tables — that the data connector has to know about in order to serve queries. It never changes during the lifetime of the data connector service instance. When your database schema changes you will have to update the configuration accordingly, see updating with introspection.

Below you will find information about how to work effectively with the configuration authoring tools provided by Hasura, along with the data connector and descriptions of the meanings of each configuration field.

Versioning policy

The PostgreSQL data connector and its configuration format are versioned independently.

The data connector will always support at least the latest two configuration versions, and tooling is provided to ease the upgrade of configurations. A Hasura DDN project will always use the head version of the PostgreSQL data connector. We recommend doing the same for data connector instances used for local development as well.

During its lifetime, the head version of the configuration format may receive backwards-compatible extensions. The reference documentation of the configuration version will always list the version of the connector which introduced the configuration extension. The configuration version number is only bumped when it changes in a way that is not backwards compatible.

Certain fields have default values. The defaults are allowed to evolve over time without requiring a version bump. Whenever you initialize a new project or update an existing one, all unspecified fields will have their defaults output, ensuring that only intentional updates to default fields will ever affect the observable behavior of a project, save for enhancements to performance and security.

The currently supported versions are:

• "version": "5" (current).
• "version": "4" (deprecated).
• "version": "3" (deprecated).

Configuration workflows

The data connector provides a plugin to the hasura CLI to assist you in authoring configuration.

We provide the ndc-postgres-cli, which is a small executable, whose builds can be accessed here.

Current status

The intended way to commonly use this plugin is through the main ddn CLI.

Some of the commands, such as initialize and update, do not need to be invoked directly as part of the ddn CLI workflow.

The commands can be invoked by changing the directory into the connector directory (e.g. cd my_subgraph/connector/my_pg/) and invoking the command using the following syntax:

ddn connector plugin --connector connector.yaml -- --help

The initial configuration

Running initialize in an empty directory will produce a single file, configuration.json, containing a minimal configuration which expects to be given a connection string via the environment variable CONNECTION_URI.

This is the same configuration you would get if you were to add a new PostgreSQL data connector to a project with the ddn cli.

SSL configuration can be provided via the following variables, which can either be suppied via Hasura Cloud, or as environment variable arguments to the binary or Docker container:

• CLIENT_CERT: the contents of the SSL client certificate.
• CLIENT_KEY: the contents of the SSL client key.
• ROOT_CERT: the contents of the SSL root certificate.

If your certificates are stored in files, these files can be read into environment variables. As an example, we could read the client certificate into the environment variable like so:

CLIENT_CERT="$(cat client-certficate.pem)"

Updating with introspection

Whenever the schema of your database changes you will need to update your data connector configuration accordingly to reflect those changes.

Running update in a configuration directory will do the following:

• Connect to the database with the specified connectionUri, and then overwrite all data in the metadata field (except for the native operations) based on the contents of the database and the values given in the introspectionOptions field.

• Fill in default values for any fields absent from the configuration, as described in the Versioning Policy section.

Various fields in the introspectionOptions object influence the outcome of the introspection process, See Configure options.

Upgrading the configuration format version

The ndc-postgres-cli plugin can assist in upgrading any supported version of a connector configuration to the latest one.

upgrade --from-dir <existing configuration dir> --to-dir <new directory> will produce an upgraded version of the configuration in <existing configuration dir> and place it in <new directory>.

For example:

cd <connector-path> # E.g. my_subgraph/connector/my_pg/
ddn connector plugin --connector connector.yaml -- upgrade --dir-from . --dir-to .

Sometimes a configuration format upgrade will need some manual editing of the result, if the new version requires information that cannot be derived from the previous version. This can vary from case to case, but the upgrade command will output instructions if there are known manual changes required.

Manually editing

There are occasions when the automatic introspection falls short of your needs. For instance, it may not detect a particular entity type, or it may pick names according to conventions with which you disagree.

If you find yourself in this situation you may still be able to bring your configuration into an acceptable state by editing it manually. In this case you'd be well advised to keep your configuration files under version control, as re-running the update command will overwrite your manually-crafted changes.

If there is a pattern to the changes you find yourself applying manually it's possible that your use case could warrant a new introspectionOptions field that could integrate the pattern with the normal introspection process. Feel free to raise a feature request issue on the Issue Tracker.

One section of the configuration that will always need manual authorship is the user-defined nativeQueries.