This page covers considerations and best practices for connecting Flyway to production databases, both from Flyway Desktop and from automated pipelines during deployment.

Environment separation

Using toml

You can manage all your environments — including production — in the flyway.toml  configuration file. Defining your production environment here means your CI/CD pipeline scripts can reference it by name (e.g. -environment=production ) rather than constructing JDBC URLs, credentials, and connection properties inline. This simplifies your build scripts and ensures consistency between what you test locally and what runs in your pipeline.

This is required for any operation where the database is involved within Flyway Desktop such as manual deployment, and this also allows you to generate more complete workflow files using the Flyway Desktop automated deployment page.

Use Flyway's environment configuration to clearly separate production from non-production settings.

[environments.development]
url = "jdbc:postgresql://localhost:5432/devdb"
user = "dev_user"
password = "dev_password"

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

Key practices:

• Use different credentials for different environments. Production credentials should only be available to your deployment pipeline, not to developers.
• Use environment overrides to enforce stricter settings on production (e.g. disabling out-of-order migrations).

Note that for any authentication involving credentials

Defining connections inline

For simple deployment workflows, defining connections inline will be more verbose than defining environments in TOML, but there may be scenarios where this is preferable.

For example, if multiple projects are deploying to the same database, it may be preferable not to duplicate the database credential configuration across multiple project toml files, and instead define it once using an appropriate mechanism for your CI platform.

For simple connections, you can user -url, -user, and -password. e.g.

flyway migrate "-url=${PRODUCTION_URL}" -user=${PRODUCTION_USER} -password=${PRODUCTION_PASSWORD}

For anything more involved, use the full environment syntax. e.g.

flyway migrate -environment=production "-environments.production.url=${PRODUCTION_URL}" "-environments.production.user=${PRODUCTION_USER}" "-environments.production.password=${PRODUCTION_PASSWORD}" "-environments.production.flyway.locations=filesystem:migrations"

Network access

Production databases are typically not directly accessible from developer machines or CI/CD agents. You will need to account for one or more of the following:

• Firewalls and security groups - Ensure that the machine running Flyway has network access to the database port. This may require allowlisting IP addresses or CIDR ranges for your CI/CD runners.
• VPNs and bastion hosts - If the database is on a private network, your pipeline agent may need to connect via a VPN or SSH tunnel. Configure these at the infrastructure level before Flyway runs.
• Cloud private endpoints - For databases hosted in AWS, Azure, or GCP, consider using private endpoints or private link connections so that traffic never traverses the public internet.
• DNS resolution - In isolated network environments, ensure the pipeline agent can resolve the database hostname. This is a common source of connectivity failures in containerised CI/CD environments.

CI/CD automated deployment pipelines

Pipeline agents are the primary consumer of production database connections. Ensure your agents are deployed in a network location that has access, or configure network tunnelling as part of your pipeline setup before invoking Flyway.

Common approaches include using self-hosted runners deployed inside your network, or using your CI platform's built-in private networking features to connect cloud-hosted runners to your database. See your provider's documentation:

• GitHub Actions - Private networking for hosted runners | Self-hosted runners
• Azure DevOps - Azure DevOps with Azure Virtual Networks | Self-hosted agents
• GitLab CI/CD - Private service connect | Self-managed runners
• Jenkins - Using agents
• CircleCI - Create a private connection | Self-hosted runners
• Bitbucket Pipelines - Self-hosted runners
• Octopus Deploy - Workers | Tentacle agents
• TeamCity - Build agents
• Harness - Self-managed runners | Secure connect

Flyway Desktop

Flyway Desktop needs network access to any environments defined in your TOML configuration that you interact with directly, including production if you are using Flyway Desktop for manual deployment or to help set up automated deployment pipelines using the automated deployment page.

If your production database is behind a VPN or firewall, your developer machine will need the same network access as a pipeline agent.

Authentication

Choose the most secure authentication mechanism available for your database platform. Avoid storing plaintext credentials. Where possible, use platform-native authentication instead of SQL usernames and passwords. For tutorials on different authentication mechanisms, see Connecting to Environments - Authentication.

Encrypting connections with TLS/SSL

Always encrypt connections to production databases. See Connecting to Environments - Encrypting connections with TLS/SSL.

Database permissions

Apply the principle of least privilege. Where possible, use a separate, read-only credential for drift checks and reserve write-capable credentials for deployments. See Connecting to Environments - Database permissions.

Secrets management in pipelines

Never store production credentials in source control. Flyway has built-in integrations with external secret managers, and can also consume secrets injected as environment variables by your CI/CD platform.

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}"

Set `FLYWAY_PASSWORD` as a secret variable in your pipeline configuration. See your CI/CD provider's documentation for how to configure secrets:

• GitHub Actions - Using secrets in a workflow
• Azure DevOps - Set secret variables
• GitLab CI/CD - CI/CD variables
• Jenkins - Using credentials
• CircleCI - Using environment variables
• Bitbucket Pipelines - Variables and secrets
• Octopus Deploy - Sensitive variables
• TeamCity - Typed parameters (password type)
• Harness - Secrets management