import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Thumbnail from '@site/src/components/Thumbnail'; import ProductBadge from '@site/src/components/ProductBadge';

Dynamic Secrets

Introduction

Dynamic secrets allow rotating database credentials without requiring you to restart the Hasura GraphQL Engine. Upon enabling this feature, database connection strings will be read from a configured file for each new connection or upon encountering a connection error.

Configuration

:::tip Enabling this feature

To enable this feature, the environment variable HASURA_GRAPHQL_DYNAMIC_SECRETS_ALLOWED_PATH_PREFIX must be set and non-empty. File paths used with this feature must start with the prefix set in this environment variable. See Dynamic Secrets Allowed Path Prefix for reference.

:::

To add a new Postgres database with this feature, navigate to Data tab and click on Data Manager. Choose Postgres and click Connect Existing Database. Choose Dynamic URL in the options and provide the path of the file where the database connection string can be read from.

<Thumbnail src="/img/databases/postgres/dynamic-secrets/dynamic-secrets.png" alt="Dynamic secrets configuration for Postgres" />

Head to the /metadata/databases/databases.yaml file and add the database configuration as below:

- name: pgDatabase
  kind: postgres
  configuration:
    connection_info:
      # highlight-start
      database_url:
        dynamic_from_file: /secrets/dbCredentials
      isolation_level: read-committed
      # highlight-end
      use_prepared_statements: false

Apply the Metadata by running:

hasura metadata apply

You can add data source with dynamic secrets using the pg_add_source Metadata API.

Configuration for metadata database

To enable rotating secrets for your metadata database, the environment variable HASURA_GRAPHQL_METADATA_DATABASE_URL must be set as dynamic-from-file:///path/to/file. The connection string to the metadata database will be read from this file. See Metadata Database URL for reference.

Template variables

Dynamic secrets can be used in template variables for data connectors. See Template variables for reference.

Forcing secret refresh

If the environment variable HASURA_SECRETS_BLOCKING_FORCE_REFRESH_URL=<url> is set, on each connection failure the server will POST to the specified URL the payload:

{"filename": <path>}

It is expected that the responding server will return only after refreshing the secret at the given filepath. hasura-secret-refresh follows this spec.