Environments can be configured using Flyway Desktop or by editing the TOML confuguration file directly. The reference information for all possible environment-specific configurations can be found here.

For considerations specific to production databases, see Connecting to production environments.

Connecting to databases drivers which don't ship with flyway

Flyway ships with support for a large number of databases and functionality, but due to limitations (such as licensing) it can't ship containing everything it supports. In these situations, Flyway will load the extra support/functionality if it is present on the classpath. The most common libraries to be added to Flyway are those that add JDBC driver support. For example the Informix database is supported by Flyway, but the JDBC driver is not shipped with it. Therefore the com.ibm.informix:jdbc:4.10.10.0 dependency needs to be added to the classpath to allow Flyway to work with it. See the database driver reference for more information and see this tutorial for more guidance on how to add items to the classpath.

Connecting to SQL Server Local DB

LocalDB uses named pipes for connections, and the official Microsoft SQL Server JDBC driver doesn't support LocalDB named pipes - see this Github issue.

LocalDB connections can instead be made using the jTDS driver, but there are a couple of important caveats to note:

• The jTDS driver only supports named pipes when connecting to LocalDB - you can read more about this limitation in this GitHub issue. This means that the instance name for your LocalDB will change every time the service is restarted, which would mean you have to edit your connection string every time too. To avoid this, Flyway supports deferred resolution of the instance using a Local DB resolver.
• With jTds SQL Server authentication works out of the box, but for Windows Authentication to work an additional dll, ntlmauth.dll, needs to be downloaded, as well as setting the domain property in the JDBC URL.
• jTds does not support using localhost as a server name. Use .  instead.

For more guidance see this tutorial.

Authentication

Choose the most secure authentication mechanism available for your database platform. Avoid storing plaintext credentials.

SQL authentication (username and password)

The simplest approach, supported by most databases. Configure via your TOML configuration file:

[environments.production]
url = "jdbc:sqlserver://prod-server:1433;databaseName=mydb"
user = "flyway_deployer"
password = "${vault.flyway/prod-password}"

Flyway Desktop uses OS-specific local secret storage by default.. In a pipeline, prefer injecting credentials via [secret resolvers](#secrets-management-in-pipelines) or environment variables rather than hardcoding values.

Platform-specific authentication

The following tutorials walk through platform-native authentication mechanisms:

Windows Integrated Authentication considerations

Windows Integrated Authentication uses the identity of the account running Flyway.

In a pipeline, the agent service must run under a domain service account on a domain-joined machine. In Flyway Desktop, it uses the logged-in user's Windows identity and can be configured from the connection dialog.

Microsoft Entra ID considerations

Microsoft Entra ID offers several methods:

• Service Principal is recommended for pipelines (client ID + secret).
• Managed Identity (MSI) is the most secure option for agents running on Azure infrastructure, requiring no credentials at all.
• Interactive authentication is suited to Flyway Desktop and local development — the Entra Interactive resolver caches the token so you are not prompted on every connection.
  For Java API users, the MSAL4J and Azure Identity libraries must be added to your classpath (they are already bundled with the command-line tool). See the Microsoft JDBC driver documentation for full details.

Kerberos considerations

Kerberos authenticates using cryptographic tickets rather than passwords.

In a pipeline, the agent typically authenticates using a keytab file — the keytab, `krb5.conf`, and network access to the KDC must all be available.

Clock skew between the client, KDC, and database server is a common cause of authentication failures.

In Flyway Desktop, Kerberos settings must be defined in TOML (flyway.toml  or flyway.user.toml ) as they cannot be configured from the connection dialog, but they will be honoured.

For interactive use, configure the login module to use the ticket cache rather than a keytab.

Oracle Wallet

Oracle Wallet stores credentials in an encrypted wallet file on disk.

In a pipeline, the wallet files must be deployed as secure artifacts alongside `tnsnames.ora` and `sqlnet.ora`, with the `TNS_ADMIN` environment variable set.

In Flyway Desktop, the oracle.walletLocation  parameter must be defined in TOML as it cannot be configured from the connection dialog, but it will be honoured.

Storing credentials

See Storing and retrieving credentials.

Encrypting connections with TLS/SSL

Maintaining a secure connection to your database is highly desirable in a production environment, even if not already enforced by the database configuration. Flyway can be configured to use SSL to establish a secure connection as and when required, provided the relevant database and JDBC driver also support SSL.
Always encrypt connections to production databases. The configuration is database-specific and set via JDBC URL parameters or JDBC properties.

For properties that cannot be set in the URL, use the jdbcProperties  configuration:

[environments.production]
url = "jdbc:postgresql://prod-host:5432/mydb"

[environments.production.jdbcProperties]
ssl = "true"
sslmode = "verify-full"
sslrootcert = "/path/to/ca-cert.pem"

See this tutorial for more guidance.

SSL in Docker

Using SSL with the Flyway Docker image is a little more involved, as you will need to get the certificate into the container you ultimately run.

If you wish to do this, we can recommend an excellent guide by Joao Rosa who follows the process through step by step.

Database permissions

Apply the principle of least privilege. The permissions Flyway needs depend on which commands you run.

For deployments (migrate / deploy)

The deploying user needs:

• CREATE, ALTER, DROP on the schemas being managed
• INSERT, UPDATE, DELETE on the Flyway schema history table
• Any permissions required by the specific SQL in your migration scripts (e.g. granting roles, creating users)

For read-only operations (check -drift, info)

Drift detection and information queries need:

• Read access to schema metadata (e.g. `INFORMATION_SCHEMA` or equivalent)
• SELECT on the Flyway schema history table

Where possible, use a separate, read-only credential for drift checks and reserve write-capable credentials for deployments.

Shadow and build databases

Shadow and build databases are used to generate expected schema state for comparisons. These databases:
- Should never be your production database
- Need full DDL permissions (since Flyway recreates schema from scratch)
- Can run on lightweight infrastructure (they are rebuilt frequently)

Relevant tutorials

• Tutorial - Configure SSL for database connections
• Tutorial - Adding drivers to the classpath
• Tutorial - Connect using Windows integrated authentication
• Tutorial - Connect to SQL Server Local DB
• Tutorial - Connect using Microsoft Entra ID
• Tutorial - Connect to Oracle Cloud Infrastructure (OCI)
• Tutorial - Connect using Kerberos authentication