Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Please see the GH release for the release notes Fix #3570: Support latest versions of Cockroach Use jackson-dataformat-toml instead of night-config Ship the SingleStore JDBC driver in the CLI code analysis engine name is now logged in the summary Closes #3417: Add SingleStore support at the Teams level fix #3562: Bump jackson dataformat version Create a Dialect configuration to allow configuration of rules engine dialect via Flyway Move undo resolver to proprietary
- Loading branch information
1 parent
ead6a7a
commit c015f2d
Showing
465 changed files
with
126,708 additions
and
720 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,62 @@ | ||
--- | ||
layout: documentation | ||
pill: addingtotheclasspath | ||
subtitle: Adding to the classpath | ||
--- | ||
|
||
# Adding to the classpath | ||
|
||
Flyway ships with support for a large number of databases and functionality, but due to limitations (such as licensing) it cannot ship containing everything it supports. In these situations, Flyway will load the extra support/functionality if it is present on the classpath. | ||
|
||
## How to add to the classpath | ||
|
||
How you add to the classpath depends on how you are invoking Flyway. | ||
|
||
### Command Line | ||
|
||
When using the CLI, you can add to the classpath by dropping the `.jar` files for the libraries you want to include into either the `drivers` or the `jars` folder in the downloaded folder structure. The two folders are provided to make it easier to separate jars used for adding database driver support, and jars used to contain other functionality (such as [Java migrations](/documentation/concepts/migrations#java-based-migrations) or [Java callbacks](/documentation/concepts/callbacks#java-callbacks)). | ||
|
||
<pre class="filetree"><i class="fa fa-folder-open"></i> flyway | ||
<i class="fa fa-folder-open"></i> conf | ||
<i class="fa fa-folder-open"></i> drivers <i class="fa fa-long-arrow-left"></i> <code>here</code> | ||
<i class="fa fa-folder-open"></i> jars <i class="fa fa-long-arrow-left"></i> <code>or here</code> | ||
<i class="fa fa-folder-open"></i> jre | ||
<i class="fa fa-folder-open"></i> lib | ||
<i class="fa fa-folder-open"></i> licenses | ||
<i class="fa fa-folder-open"></i> sql | ||
<i class="fa fa-file"></i> flyway | ||
<i class="fa fa-file"></i> flyway.cmd | ||
<i class="fa fa-file-text"></i> README.txt | ||
</pre> | ||
|
||
You can also specify more folders to load jars from using the [jarDirs](/documentation/configuration/parameters/jarDirs) configuration parameter. | ||
|
||
### API | ||
|
||
When using the API, the jars you wish to include should be added as dependencies of the overall project, just as you would with any other java dependencies. | ||
|
||
### Gradle | ||
|
||
See [extending the gradle classpath](/documentation/usage/gradle/#extending-the-default-classpath). | ||
|
||
### Maven | ||
|
||
Simply add the library as a regular dependency of your maven project. e.g: | ||
|
||
|
||
``` | ||
<dependencies> | ||
<dependency> | ||
<groupId>org.hsqldb</groupId> | ||
<artifactId>hsqldb</artifactId> | ||
<version>1.8.0.10</version> | ||
</dependency> | ||
</dependencies> | ||
``` | ||
|
||
## What can be added | ||
|
||
The most common library to be added to Flyway is those that add JDBC driver support. For example the [Informix](/documentation/database/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 each database page for the JDBC driver they use and whether they are shipped with Flyway or not. | ||
|
||
|
||
Other uses for adding libraries are [adding logging support](/documentation/usage/commandline/#output), adding [Java migrations](/documentation/concepts/migrations#java-based-migrations), and more. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
--- | ||
layout: documentation | ||
menu: baseline | ||
subtitle: Baseline | ||
--- | ||
# Baseline | ||
|
||
Baselines an existing database, excluding all migrations up to and including baselineVersion. | ||
|
||
![Baseline](/assets/balsamiq/command-baseline.png) | ||
|
||
Baseline is for introducing Flyway to [existing databases](/documentation/learnmore/existing) by baselining them | ||
at a specific version. This will cause [Migrate](/documentation/command/migrate) to ignore all migrations | ||
up to and including the baseline version. Newer migrations will then be applied as usual. | ||
|
||
## Resetting the baseline | ||
|
||
When you have many migrations, it might be desirable to reset your baseline migration. This will allow you to reduce the overhead of dealing with lots of scripts, many of which might be old and irrelevant. | ||
|
||
<a class="btn btn-primary" href="https://flywaydb.org/reset-the-baseline-migration">Learn more about resetting the baseline migration</a> | ||
|
||
## Usage | ||
See [configuration](/documentation/configuration/parameters/#baseline) for baseline specific configuration parameters. | ||
{% include commandUsage.html command="baseline" %} | ||
|
||
<p class="next-steps"> | ||
<a class="btn btn-primary" href="/documentation/command/repair">Repair <i class="fa fa-arrow-right"></i></a> | ||
</p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,90 @@ | ||
--- | ||
layout: documentation | ||
menu: check | ||
subtitle: Check | ||
--- | ||
|
||
# Check | ||
|
||
`check` produces reports to increase confidence in your migrations. | ||
|
||
For `-changes` and `-drift`, Flyway migrates against a build database and compares this against the target database in order to generate a report. | ||
**This build database will be cleaned before it is used, so you must ensure it does not contain anything of importance.** | ||
|
||
You can read more about the `check` concept [here](/documentation/concepts/check). | ||
|
||
#### Requirements | ||
- .NET 6 is required in order to generate reports. You can download it from [here](https://dotnet.microsoft.com/en-us/download/dotnet/6.0). | ||
- `sqlfluff` is required for Code Analysis (`-code`). You can install it by running `pip3 install sqlfluff==1.2.1` or use the `redgate/flyway` Docker image that has `sqlfluff` pre-installed. | ||
|
||
#### Flags: | ||
- _One or more flags must be present_ | ||
|
||
| Parameter | Description | ||
| ----------------------------- | -------------------------------------------------------------- | ||
| -changes | {% include enterprise.html %} Include pending changes that will be applied to the database | ||
| -drift | {% include enterprise.html %} Include changes applied out of process to the database | ||
| -code | **In Preview** Performs code analysis on your migrations | ||
| -dryrun | {% include teams.html %} Performs a [dry run](/documentation/concepts/dryruns), showing what changes would be applied in a real deployment | ||
|
||
#### Configuration parameters: | ||
_Format: -key=value_ | ||
|
||
| Parameter | Description | ||
| ----------------------------- | ----------------------------------------------------------- | ||
| check.buildUrl | URL for a build database. | ||
| check.buildUser | Username for the build database. Defaults to 'flyway.user' | ||
| check.buildPassword | Password for the build database. Defaults to 'flyway.password' | ||
| check.reportFilename | **[REQUIRED]** Destination filename for reports | ||
| check.nextSnapshot | A snapshot containing all migrations including those that are pending (generated via [`snapshot`](/documentation/command/snapshot)) | ||
| check.deployedSnapshot | A snapshot containing all applied migrations and thus matching what should be in the target (generated via [`snapshot`](/documentation/command/snapshot)) | ||
| check.appliedMigrations | A comma-separated list of migration ids (migration versions or repeatable descriptions) to apply to create snapshots (generated via [`info`](/documentation/command/info)) | ||
| check.majorRules | A comma-separated list of SQL Fluff rule codes that are considered to be 'major' issues | ||
| check.minorRules | A comma-separated list of SQL Fluff rule codes that are considered to be 'minor' issues | ||
| check.majorTolerance | The number of 'major' issues to be tolerated before throwing an error | ||
| check.minorTolerance | The number of 'minor' issues to be tolerated before throwing an error | ||
|
||
#### `check.reportFilename` | ||
|
||
If this filename does not have the `.html` suffix, Flyway will add it for you. Flyway also produces a `json` result for programmatic consumption. | ||
|
||
#### Usage Example: | ||
``` | ||
flyway check -changes -url=jdbc:example:database -user=username -password=password -check.buildUrl=jdbc:example:build_database | ||
``` | ||
|
||
##### Example configuration file | ||
|
||
```properties | ||
flyway.url=jdbc:example:database | ||
flyway.user=username | ||
flyway.password=password | ||
flyway.check.buildUrl=jdbc:example:build_database | ||
flyway.check.reportFilename=change_report | ||
``` | ||
|
||
#### Database Support | ||
|
||
##### `-changes` and `-drift` | ||
|
||
Change and drift reports work on the following databases: | ||
|
||
- SQL Server | ||
- PostgreSQL | ||
- Oracle | ||
- SQLite | ||
|
||
##### `-code` and `-dryrun` | ||
|
||
Code analysis and Dry run reports work on any database supported by Flyway. | ||
|
||
##### Check for Oracle | ||
|
||
When using Check with an Oracle database there are additional requirements. | ||
|
||
If no schemas are specified in the configuration `flyway.schemas`, then the database connection username will be used as the default schema, otherwise `flyway.schemas` will be used. | ||
These schema names are case-sensitive. | ||
|
||
##### Check for SQL Server | ||
|
||
If you see errors about being unable to connect to your database and you are specifying `localhost` as the host, then this may be due to not having pipes configured. Using `127.0.0.1` instead should work. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
--- | ||
layout: documentation | ||
menu: clean | ||
subtitle: Clean | ||
--- | ||
|
||
# Clean | ||
|
||
Drops all objects (tables, views, procedures, triggers, ...) in the configured schemas. | ||
|
||
The schemas are cleaned in the order specified by the [`schemas`](/documentation/configuration/parameters/schemas) and [`defaultSchema`](/documentation/configuration/parameters/defaultSchema) property. | ||
|
||
![Clean](/assets/balsamiq/command-clean.png) | ||
|
||
Clean is a great help in development and test. It will effectively give you a fresh start, by wiping your configured schemas completely clean. All objects (tables, views, procedures, ...) will be dropped. | ||
|
||
Needless to say: **do not use against your production DB!** | ||
|
||
## Limitations | ||
|
||
- [SQL Server - no users will be dropped](/documentation/database/sqlserver#limitations) | ||
|
||
### Cleaning additional objects | ||
|
||
For complicated database structures an accurate dependency graph cannot always be constructed, so not every object is cleaned. | ||
We also have objects we do not drop as they aren't always safe to, for example `users` in SQL Server. | ||
To clean additional objects, you can add an [`afterClean`](/documentation/concepts/callbacks#afterClean) callback defining drop statements, for example `afterClean.sql`: | ||
|
||
```sql | ||
DROP USER test_user | ||
``` | ||
|
||
## Usage | ||
See [configuration](/documentation/configuration/parameters/#clean) for clean specific configuration parameters. | ||
{% include commandUsage.html command="clean" %} | ||
|
||
<p class="next-steps"> | ||
<a class="btn btn-primary" href="/documentation/command/info">Info <i class="fa fa-arrow-right"></i></a> | ||
</p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
--- | ||
layout: documentation | ||
menu: info | ||
subtitle: Info | ||
--- | ||
# Info | ||
|
||
Prints the details and status information about all the migrations. | ||
|
||
![Info](/assets/balsamiq/command-info.png) | ||
|
||
Info lets you know where you stand. At a glance you will see which migrations have already been applied, | ||
which other ones are still pending, when they were executed and whether they were successful or not. | ||
|
||
## Usage | ||
{% include commandUsage.html command="info" %} | ||
|
||
<p class="next-steps"> | ||
<a class="btn btn-primary" href="/documentation/command/validate">Validate <i class="fa fa-arrow-right"></i></a> | ||
</p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
--- | ||
layout: documentation | ||
menu: migrate | ||
subtitle: Migrate | ||
--- | ||
# Migrate | ||
|
||
Migrates the schema to the latest version. Flyway will create the schema history table automatically if it doesn't exist. | ||
|
||
![Migrate](/assets/balsamiq/command-migrate.png) | ||
|
||
Migrate is the centerpiece of the Flyway workflow. It will scan the filesystem or your classpath for available migrations. | ||
It will compare them to the migrations that have been applied to the database. If any difference is found, it will | ||
migrate the database to close the gap. | ||
|
||
Migrate should preferably be executed on application startup to avoid any incompatibilities between the database | ||
and the expectations of the code. | ||
|
||
## Behavior | ||
|
||
Executing migrate is idempotent and can be done safely regardless of the current version of the schema. | ||
|
||
#### Example 1: We have migrations available up to version 9, and the database is at version 5. | ||
|
||
Migrate will apply the migrations 6, 7, 8 and 9 in order. | ||
|
||
#### Example 2: We have migrations available up to version 9, and the database is at version 9. | ||
|
||
Migrate does nothing. | ||
|
||
## Usage | ||
{% include commandUsage.html command="migrate" %} | ||
|
||
<p class="next-steps"> | ||
<a class="btn btn-primary" href="/documentation/command/clean">Clean <i class="fa fa-arrow-right"></i></a> | ||
</p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
--- | ||
layout: documentation | ||
menu: repair | ||
subtitle: Repair | ||
--- | ||
# Repair | ||
|
||
Repairs the schema history table. | ||
|
||
![Repair](/assets/balsamiq/command-repair.png) | ||
|
||
Repair is your tool to fix issues with the schema history table. It has a few main uses: | ||
- Remove failed migration entries (only for databases that do NOT support DDL transactions) | ||
- Realign the checksums, descriptions, and types of the applied migrations with the ones of the available migrations | ||
- Mark all missing migrations as **deleted** | ||
- As a result, `repair` must be given the same [`locations`](/documentation/configuration/parameters/locations) as `migrate`! | ||
|
||
## Usage | ||
{% include commandUsage.html command="repair" %} | ||
|
||
<p class="next-steps"> | ||
<a class="btn btn-primary" href="/documentation/usage/commandline/">Command-line <i class="fa fa-arrow-right"></i></a> | ||
</p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,62 @@ | ||
--- | ||
layout: documentation | ||
menu: snapshot | ||
subtitle: snapshot | ||
--- | ||
|
||
# Snapshot | ||
|
||
**The `snapshot` command is currently in beta. This feature will be available in future products, but during the beta phase you can access it through your Flyway Teams or Redgate Deploy license.** | ||
|
||
{% include enterprise.html %} | ||
|
||
`snapshot` captures the schema of the database specified in `flyway.url` into a file. | ||
|
||
This can be used to generate a snapshot of your database in its current state for use with [`check.deployedSnapshot`](/documentation/command/check#configuration-parameters) | ||
or to take a snapshot of a build database for use with [`check.nextSnapshot`](/documentation/command/check#configuration-parameters) | ||
|
||
#### Requirements | ||
- .NET 6 is required in order to generate reports. You can download it from [here](https://dotnet.microsoft.com/en-us/download/dotnet/6.0). | ||
|
||
#### Configuration parameters: | ||
_Format: -key=value_ | ||
|
||
| Parameter | Description | ||
| ---------------------------- | ----------------------------------------------------------- | ||
| snapshot.filename | **[REQUIRED]** Destination filename for the snapshot | ||
|
||
#### Usage example: | ||
``` | ||
flyway snapshot -url=jdbc:example:database -user=username -password=password -snapshot.filename=C:\snapshots\my_snapshot | ||
``` | ||
|
||
### `deployedSnapshot` and `nextSnapshot` example: | ||
In order to generate these snapshots for use with [`check`](/documentation/command/check) we first need to get a list of the applied migrations | ||
so we can accurately create the build database: | ||
|
||
``` | ||
flyway info -url="jdbc://prod" -infoOfState="success,out_of_order,baseline" -migrationIds > applied_migrations.txt | ||
``` | ||
|
||
Then we can apply these to our build database and take a snapshot, the `deployedSnapshot`: | ||
|
||
``` | ||
flyway migrate -cherrypick=$(cat applied_migrations.txt) -url="jdbc://build" | ||
flyway snapshot -snapshot.filename="deployed.snapshot" -url="jdbc://build" | ||
``` | ||
|
||
Lastly, we can apply any pending migrations and then capture the `nextSnapshot`: | ||
|
||
``` | ||
flyway migrate -url="jdbc://build" | ||
flyway snapshot -snapshot.filename="next.snapshot" -url="jdbc://build" | ||
``` | ||
|
||
##### Example configuration file | ||
|
||
```properties | ||
flyway.url=jdbc:example:database | ||
flyway.user=username | ||
flyway.password=password | ||
flyway.snapshot.filename=C:\snapshots\my_snapshot | ||
``` |
Oops, something went wrong.