This page covers the options available for providing database credentials to Flyway without storing them in plaintext in your configuration files.

Secret storage integrations

Flyway's resolvers let you reference secrets directly in your TOML configuration using placeholder syntax (e.g. `${vault.path/to/secret}`). The secret is fetched at runtime and never written to disk.

Local secrets

For reading secrets on a local development machine, Flyway supports reading from that machine's secret store, via a resolver.

This is the default secret storage mechanism used by Flyway Desktop.

The store flyway will use depends on the operating system of the machine:

• Windows - Windows Credential Manager
• Mac - Keychain
• Linux - libsecret (if available)

As these secrets are only available on a local machine it is recommended not to add the associated connection information to a version controlled settings file. Flyway Desktop will always put local secret storage configuration in the user settings file, for configurations entered via a database connection dialog.

HashiCorp Vault

EDITION: ENTERPRISE

Flyway integrates with Vault's key-value engine in order to allow users to store Flyway configuration parameters securely. This can be used to securely read license tokens without storing them in application configuration, and other configuration parameters can also be stored and read such as your database password or Flyway placeholders.

It is possible to connect to use a resolver for accessing secrets as part of an environment connection. Otherwise Vault url, token, and secrets settings can be used to access the secrets for more generic use.

The Vault token should not be committed to source control. In a pipeline, inject it via a CI platform secret as an environment variable. In Flyway Desktop, define it in `flyway.user.toml` (which should be gitignored) or reference an environment variable.

See this tutorial.

Dapr

EDITION: ENTERPRISE

Flyway integrates with Dapr's Secret Store in order to allow users to store Flyway configuration parameters securely. This can be used to securely read license tokens without storing them in application configuration, and other configuration parameters can also be stored and read such as your database password or Flyway placeholders.

It is possible to connect to use a resolver for accessing secrets as part of an environment connection. Otherwise Dapr url  and secrets settings can be used to access the secrets for more generic use.

The Dapr sidecar must be running before Flyway can resolve secrets. In a pipeline, start the sidecar as a background process or configure it as a sidecar container. Dapr provides a uniform API across multiple secret store backends (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, and more).

See this tutorial.

Google Cloud Secret Manager

EDITION: ENTERPRISE

Flyway integrates with Google Cloud Secret Manager (GCSM) in order to allow users to store Flyway configuration parameters securely. This can be used to securely read license tokens without storing them in application configuration, and other configuration parameters can also be stored and read such as your database password or Flyway placeholders.

It is possible to connect to use a resolver for accessing secrets as part of an environment connection. Otherwise Google Cloud Secret Manager project and secrets settings can be used to access the secrets for more generic use.

Flyway uses the standard Google Cloud authentication chain. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to a service account key file, or use workload identity on GCP infrastructure. The service account or identity needs the `secretmanager.versions.access` IAM permission.

See this tutorial.

AWS Secrets Manager

EDITION: ENTERPRISE

AWS Secrets Manager offers a solution to the problem of handling database credentials. Secrets such as usernames and passwords can be stored in the Secrets Manager, and then accessed via an id known to authorized users. This keeps sensitive credentials out of application configuration.

Flyway can integrate with version 1.0.5 or later of com.amazonaws.secretsmanager:aws-secretsmanager-jdbc. This library does not ship with FLyway and needs to be manually added to the classpath.

See this tutorial.

Supported databases

Secrets Manager support is currently provided by the AWS Secrets Manager JDBC Library for the following databases:

CI/CD platform secrets

If you are not using a dedicated secret manager, most CI/CD platforms can inject secrets as environment variables. Flyway can consume these directly in your TOML configuration:

[environments.production]
url = "jdbc:postgresql://prod-host:5432/mydb"
user = "flyway_deployer"
password = "${FLYWAY_PASSWORD}"

See Connecting to production environments for more information.

Database-specific credential retrieval

Some databases support retrieving credentials from platform-specific stores, so that usernames and passwords do not need to be provided in Flyway configuration.

MySQL Option Files

EDITION: TEAMS

MySQL can retrieve credentials from option files. The following files are searched in order:

When credentials are found in an option file, they do not need to be supplied separately in Flyway configuration.

Limitations: Flyway does not support option file inclusions, and only reads user  and password  properties from option files.

PostgreSQL pgpass

EDITION: TEAMS

PostgreSQL can retrieve passwords from a pgpass file. If the PGPASSFILE  environment variable is set, the file is read from that path. Otherwise, the default location is:

- Windows: %APPDATA%\postgresql\pgpass.conf 
- Linux / macOS: ~/.pgpass 

When a matching entry is found, the password does not need to be supplied in Flyway configuration.

Limitations: Flyway does not support the passfile  or hostaddr  parameters as there is no JDBC equivalent.

Oracle Proxy Authentication

EDITION: TEAMS

Oracle allows you to connect as one user and proxy as another for migrations. This is useful when a shared service account connects to the database but migrations should execute under a different schema owner.

Configure proxy authentication using Flyway's jdbcProperties :

[environments.production]
url = "jdbc:oracle:thin:@prod-host:1521/ORCL"
user = "connection_user"
password = "${vault.oracle/connection-password}"

[environments.production.jdbcProperties]
PROXY_USER_NAME = "schema_owner"

See the Oracle proxy authentication documentation for how to grant proxy privileges.

Relevant tutorials

• Tutorial - Manage Secrets with AWS Secrets Manager
• Tutorial - Manage Secrets with Dapr
• Tutorial - Manage Secrets with Google Cloud Secret Manager
• Tutorial - Manage Secrets with HashiCorp Vault