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.

See this tutorial.

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.

See this tutorial.

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.

See this tutorial.

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.

See this tutorial.

Databricks considerations

Flyway can't sign in to Databricks Lakehouse with your Databricks username and password as this method of authentication has been retired by Databricks on July 2024. Instead, you must use a personal access token or OAuth. Flyway passes your URL and `jdbcProperties` to the Databricks JDBC driver, which handles authentication. See the Databricks driver reference for the URL format.

OAuth machine-to-machine is the best fit for pipelines. Flyway authenticates as a Databricks service principal, so there's no personal token tied to a named user. Set `AuthMech=11;Auth_Flow=1` in the URL, and set the `OAuth2ClientId` and `OAuth2Secret` JDBC properties to the service principal's application ID and a Databricks OAuth secret:

[environments.production]
url = "jdbc:databricks://adb-1234567890123456.7.azuredatabricks.net:443/default;transportMode=http;ssl=1;httpPath=/sql/1.0/warehouses/abc123;EnableArrow=0;AuthMech=11;Auth_Flow=1;ConnCatalog=main"

[environments.production.jdbcProperties]
OAuth2ClientId = "${env.DATABRICKS_CLIENT_ID}"
OAuth2Secret = "${env.DATABRICKS_CLIENT_SECRET}"

Personal access tokens (`AuthMech=3`) are the simplest option and work in pipelines and locally. Set `password` to the token, and keep it in a secret store or environment variable rather than in the URL. If you use one in a pipeline, generate it for a service principal rather than a named user, and rotate it regularly.

[environments.production]
url = "jdbc:databricks://adb-1234567890123456.7.azuredatabricks.net:443/default;transportMode=http;ssl=1;httpPath=/sql/1.0/warehouses/abc123;EnableArrow=0;AuthMech=3;ConnCatalog=main"
password = "${env.DATABRICKS_TOKEN}"

OAuth user-to-machine (`AuthMech=11;Auth_Flow=2`) is for interactive use. It opens a browser so you sign in with your own Databricks identity. The driver caches the OAuth tokens, encrypted with the passphrase in the `TokenCachePassPhrase` JDBC property. Use the Databricks Resolver to supply a per-user passphrase:

[environments.development]
url = "jdbc:databricks://adb-1234567890123456.7.azuredatabricks.net:443/default;transportMode=http;ssl=1;httpPath=/sql/1.0/warehouses/abc123;EnableArrow=0;AuthMech=11;Auth_Flow=2;ConnCatalog=main"

[environments.development.jdbcProperties]
TokenCachePassPhrase = "${databricks.tokenCachePassPhrase}"

In Flyway Desktop, choose "OAuth Interactive Sign-In" in the connection dialog's "Authentication" list and this is set up for you.

Catalog: `ConnCatalog` is required. Set it in the URL or `jdbcProperties` (Flyway Desktop's "Catalog" field). Flyway works within the specified Unity Catalog catalog. Workspaces that only use the Hive metastore aren't supported for schema model, migration script generation or drift checks.

See this tutorial.

Snowflake considerations

Flyway passes your URL and jdbcProperties to the Snowflake JDBC driver, which handles authentication. See the Snowflake driver reference for the URL format.

Programmatic access tokens (PATs) are the simplest option and work in pipelines and locally. Set password to the token, and keep it in a secret store or environment variable rather than in the URL. If you use one in a pipeline, generate it for a service user rather than a named person, and rotate it regularly.

By default, Snowflake requires the user to have a network policy before a PAT can be created or used. See Snowflake's programmatic access token documentation for the prerequisites.

[environments.production]
url = "jdbc:snowflake://myorganization-myaccount.snowflakecomputing.com/?db=MY_DB&warehouse=MY_WH"
user = "FLYWAY_SERVICE_USER"
password = "${env.SNOWFLAKE_PAT}"

In Flyway Desktop, choose "Username and password or PAT" in the connection dialog's "Authentication" list, and enter the token in the "Password or PAT" field.

Key-pair authentication also suits pipelines, and doesn't use a password at all. Assign a public key to the Snowflake user, then set authenticator=snowflake_jwt and private_key_file in the URL:

[environments.production]
url = "jdbc:snowflake://myorganization-myaccount.snowflakecomputing.com/?db=MY_DB&warehouse=MY_WH&authenticator=snowflake_jwt&private_key_file=/path/to/rsa_key.p8"
user = "FLYWAY_SERVICE_USER"

See the Snowflake driver reference for setting up the key pair. In Flyway Desktop, choose "Other (configure in JDBC URL)" in the "Authentication" list.

Password with MFA (authenticator=username_password_mfa) is for interactive use only, because signing in may need you to approve a push notification in your authenticator app. Only push notification authenticator apps are supported, not TOTP codes or passkeys. To reduce the number of prompts, enable MFA caching by setting the ALLOW_CLIENT_MFA_CACHING parameter on your Snowflake account. In Flyway Desktop, choose "MFA" in the "Authentication" list.

Database and warehouse: the URL must name both a database (db) and a warehouse (warehouse), which are Flyway Desktop's "Database" and "Warehouse" fields. Flyway takes its database and compute context from them, so a URL without them won't work.

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.

Databricks (Unity Catalog)

The principal Flyway connects as needs the following:

• Can use permission on the SQL warehouse
• USE CATALOG on the catalog and USE SCHEMA on each managed schema
• CREATE SCHEMA on the catalog, if Flyway creates the schemas for you
• CREATE TABLE on the schema that holds the schema history table
• SELECT and MODIFY on the schema history table, if a different principal created it. Flyway writes to this table on every run, including to lock it.
• any privileges your migration scripts need

Dropping objects, for example with clean , needs ownership of the object or the MANAGE  privilege on it.

For drift checks and generating migrations, the principal needs to see every object in the catalog. Databricks hides objects you don't have privileges on from information_schema, so missing privileges make objects silently disappear from comparisons rather than causing an error. Grant BROWSE on the catalog, or the same privileges your deployments use.

Snowflake

The role Flyway connects as needs the following:

• USAGE  on the warehouse
• USAGE  on the database and on each managed schema
• CREATE SCHEMA  on the database, if Flyway creates the schemas for you
• CREATE TABLE  on the schema that holds the schema history table (PUBLIC by default)
• SELECT , INSERT , UPDATE  and DELETE  on the schema history table, if a different role created it. Flyway writes to this table on every run, including to lock it.
• On each managed schema, the CREATE  privilege for each object type you deploy: CREATE TABLE , CREATE VIEW , CREATE FUNCTION , CREATE PROCEDURE , CREATE DYNAMIC TABLE  and CREATE TASK 
• USAGE  on any warehouse named by a dynamic table or task, and EXECUTE MANAGED TASK  on the account to create serverless tasks
• any privileges your migration scripts need

Altering or dropping an object, for example with clean, needs OWNERSHIP  of it. The simplest setup is a single deployment role that owns every object in the managed schemas.

For drift checks and generating migrations, the role needs to see every object in the database. Snowflake hides objects your role has no privileges on from INFORMATION_SCHEMA  and SHOW  results, so missing privileges make objects silently disappear from comparisons rather than causing an error. Use the same role your deployments use, or grant a read-only role privileges on every object, including future grants so new objects stay visible.

Dynamic tables need MONITOR  (or OPERATE  or OWNERSHIP , which include it). With only SELECT , Snowflake hides a dynamic table's query definition, and Flyway can't read it:

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)

Databricks: use a separate Unity Catalog catalog for your shadow or build environment, in the same workspace and with the same SQL warehouse if you like. Flyway compares a whole catalog and doesn't map schemas, so a shadow schema inside the development catalog won't work. Docker provisioning isn't available for Databricks, so create the catalog ahead of time. If you reset it with the `clean` provisioner, note that clean doesn't remove procedures or volumes.

Snowflake: use a separate Snowflake database for your shadow or build environment, in the same account and with the same warehouse if you like. Flyway compares a whole database and doesn't map schemas, so a shadow schema inside the development database won't work. Docker provisioning isn't available for Snowflake, so create the database ahead of time. Building the shadow creates any dynamic tables in it, and each one runs an initial refresh on its warehouse, which uses credits. Tasks are created suspended, so they won't run in the shadow database.

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 a database using Oracle Cloud Infrastructure (OCI)
• Tutorial - Connect using Kerberos authentication
• Tutorial - Connect to a Databricks instance 
• Tutorial - Connect to a Snowflake instance