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 Add stream configuration for ClassPath SQL Migrations Update AWS S3 dependency to fix CVE-2024-29025 make upgrade message less alarming Update ErrorCode and ErrorOutput to allow extending in plugins Closes #3860 Remove unused methods in ClassUtils and remove need for `java.desktop` set property to hide warning from polyglot engine Create `flyway.communityDBSupportEnabled` to turn off community db support database types if desired
- Loading branch information
1 parent
5511c69
commit 00db8d5
Showing
116 changed files
with
1,013 additions
and
614 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
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
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
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
73 changes: 73 additions & 0 deletions
73
documentation/Flyway CLI and API/Concepts/Check Changes concept.md
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,73 @@ | ||
--- | ||
subtitle: Check Changes | ||
--- | ||
# Check Changes Concept | ||
{% include enterprise.html %} | ||
|
||
## Overview | ||
The `-changes` flag produces a report indicating differences between applied migration scripts on your target database and pending migrations scripts (ie. the set of instructions you want to use to change your target database). | ||
You can use this capability pre- and post-deployment: | ||
- In pre-deployment scenarios to check the effect of your pending changes | ||
- In post-deployment scenarios to have captured a history of changes for retrospective auditing or reporting | ||
|
||
In either scenario, using the `-changes` flag will help you infer which database objects will be/have been affected - and how - when you execute/have executed your migration scripts. | ||
|
||
## Configuring the environment | ||
Please see the [check -changes](<Configuration/Parameters/Flyway/Check/Check Changes>) parameter reference page | ||
|
||
## Examples | ||
There are a variety of ways to configure Flyway to produce this report so we'll step through a couple and show you what it is doing along the way. | ||
|
||
### Example: `environment` and `buildEnvironment` | ||
|
||
The `check -changes` command and flag works by building a temporary database. This 'build' database is first made to reflect the state of your target schema, and then made to reflect your target schema with the pending changes applied. | ||
|
||
The difference between the two states of this build database (target now, and target with changes applied) represents the effect your pending migrations will have when the scripts are executed. This difference is captured as an artefact called a "Change Report". The change report is available as both HTML (human readable) and JSON (machine readable) formats. | ||
|
||
The process works like this: | ||
![Check_changes.png](assets/Check_changes.png) | ||
1. Specify your target database location | ||
1. This is the database you want to apply your changes to, where Flyway is already being used to manage migrations (ie. A Flyway migrations table exists) | ||
1. Specify a build environment | ||
1. This is an existing build environment that contains a build database (note: Flyway will [`clean`](Commands/clean) this database, so if you specify a full database, you must ensure it is ok to for Flyway to erase its schema) | ||
1. Run `flyway check -changes -check.buildEnvironment="build" -environment="production"` | ||
|
||
Flyway's `check -changes` will then: | ||
1. Clean your build database | ||
1. Query the target database for the list of applied migrations (for simplicity, let's say it's at V2) | ||
1. Apply these migrations to the build database | ||
1. Take a [`snapshot`](Commands/snapshot) of the build database (now also at V2) | ||
1. Applying pending migrations to the build database (let's say it's now at V5) | ||
1. Take a [`snapshot`](Commands/snapshot) of the build database | ||
1. Compare the V2 build database snapshot to the V5 build database snapshot | ||
1. Generate a HTML (human readable) and JSON (machine readable) Change Report, indicating the additions, deletions, and modifications of database objects between V2 and V5 | ||
|
||
### Example: `appliedMigrations` and `buildEnvironment` | ||
|
||
The `check -changes` command and flag works by building a temporary database. This 'build' database is first made to reflect the state specified by `appliedMigrations`, and then made to reflect your `appliedMigrations` with the pending changes applied. | ||
|
||
The difference between the two states of this build database (`appliedMigrations`, and `appliedMigrations` with changes applied) represents the effect your pending migrations will have (or have had) when the scripts are (or were) executed. This difference is captured as an artefact called a "Change Report". The change report is available as both HTML (human readable) and JSON (machine readable) formats. | ||
|
||
The process works like this: | ||
![Check_appliedMigrations.png](assets/Check_appliedMigrations.png) | ||
1. Run `flyway info -infoOfState="success,pending,out_of_order" -migrationIds > appliedMigrations.txt` | ||
1. This will produce a comma-separated list which represents the applied migrations of your target database | ||
1. Specify a build environment | ||
1. This is an existing build environment that contains a build database (note: Flyway will [`clean`](Commands/clean) this database, so if you specify a full database, you must ensure it is ok to for Flyway to erase its schema) | ||
1. Run `flyway check -changes -check.buildEnvironment="build" -check.appliedMigrations="$(cat appliedMigrations.txt)"` | ||
|
||
Flyway's `check -changes` will then: | ||
1. Clean your build database | ||
1. Apply the migrations specified in `appliedMigrations` to the build database (for simplicity, let's say it's at V2) | ||
1. Take a [`snapshot`](Commands/snapshot) of the build database (now also at V2) | ||
1. Applying pending migrations to the build database (let's say it's now at V5) | ||
1. Take a [`snapshot`](Commands/snapshot) of the build database | ||
1. Compare the V2 build database snapshot to the V5 build database snapshot | ||
1. Generate a HTML (human readable) and JSON (machine readable) Change Report, indicating the additions, deletions, and modifications of database objects between V2 and V5 | ||
|
||
## Good things to know | ||
- There is no requirement for the build environment to be in your production system | ||
- Please note that the build environment **may be cleaned** before the operation starts | ||
- Your Flyway instance assumes that it is the only party changing the build environment so it shouldn't be used concurrently by different developers | ||
- If you get an ERROR: Invalid argument: -check, this is because some systems (for example, Powershell) do not like the period in the argument. You can wrap the arguments in a single or double quotes to work around this. | ||
- for example, `flyway check -changes "-check.buildURL"` |
56 changes: 56 additions & 0 deletions
56
documentation/Flyway CLI and API/Concepts/Check Code concept.md
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,56 @@ | ||
--- | ||
subtitle: Check Code Concept | ||
--- | ||
# Check Code Concept | ||
{% include redgate.html %} | ||
|
||
## Overview | ||
|
||
The `-code` flag produces a report showing the results of running static code analysis over your SQL migrations. | ||
|
||
Rules that Flyway comes supplied with can be found in: [Code Analysis Rules](<Usage/Code Analysis Rules>) | ||
|
||
For details on how to use code analysis, see the [check -code](<Configuration/Parameters/Flyway/Check/Check Code>) parameter reference | ||
|
||
## Analysis engines | ||
At least one needs to be present or else this command will fail with an error. | ||
Enterprise users have the Regular Expression engine available by default but otherwise you will have to install SQLFluff to use this command. | ||
|
||
## Analysis engine: SQLFluff | ||
|
||
### Requirements | ||
|
||
[SQLFluff](https://www.sqlfluff.com/) needs to be installed on the machine producing the report. | ||
|
||
We currently only integrate with version 1.2.1 and You can install it by running: | ||
|
||
```powershell | ||
pip3 install sqlfluff==1.2.1 | ||
``` | ||
|
||
Alternatively, the redgate/flyway docker image comes with this already pre-installed. | ||
|
||
### Configuring SQLFluff | ||
|
||
If you provide a URL/environment to `check -code` Flyway will use it to automatically determine which SQL dialect to use when analysing your SQL. | ||
|
||
If no URL is provided, then you need to configure the dialect in a `.sqlfluff` configuration file. | ||
This file needs to be located in the same location as the migrations being analysed. | ||
|
||
You can find more information on configuration in the [SQLFLuff documentation](https://docs.sqlfluff.com/en/stable/configuration.html). | ||
|
||
## Analysis engine: Regular Expressions | ||
{% include enterprise.html %} | ||
|
||
### Configuring Regular Expression rules | ||
|
||
Customers can easily craft their own custom rules or take advantage of the set of rules Flyway provides: | ||
- [Creating Regular Expression Rules](<Learn More/Creating Regular Expression Rules>) | ||
- [Code Analysis Rules](<Usage/Code Analysis Rules>) | ||
|
||
|
||
|
||
|
||
|
||
|
||
|
38 changes: 38 additions & 0 deletions
38
documentation/Flyway CLI and API/Concepts/Check Drift concept.md
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,38 @@ | ||
--- | ||
subtitle: Check Drift | ||
--- | ||
# Check Drift Concept | ||
|
||
{% include enterprise.html %} | ||
|
||
## Overview | ||
The `-drift` flag produces a report indicating differences between structure of your target database and structure created by the migrations applied by Flyway. | ||
|
||
## Configuring the environment | ||
Please see the [check -drift](<Configuration/Parameters/Flyway/Check/Check Drift>) parameter reference page | ||
|
||
## Examples | ||
There are a variety of ways to configure Flyway to produce this report so we'll step through a couple and show you what it is doing along the way. | ||
|
||
### Example: `environment` and `buildEnvironment` | ||
|
||
The `check -drift` command and flag works by building a temporary database. This 'build' environment that contains a 'build' database is made to reflect the state of your target schema based on the migrations applied by Flyway. | ||
|
||
The difference between the two states of this build database and your target database represents the drift between the expected structure according to Flyway and the actual structure. This difference is captured as an artefact called a "Drift Report". The drift report is available as both HTML (human readable) and JSON (machine readable) formats. | ||
|
||
The process works like this: | ||
![Check_drift.png](assets/Check_drift.png) | ||
1. Specify your target database location | ||
1. This is the database you want to apply your changes to, where Flyway is already being used to manage migrations (ie. A Flyway migrations table exists) | ||
1. Specify a build database | ||
1. This is an existing build database (note: Flyway will "clean" this database, so if you specify a full database, you must ensure it is ok to for Flyway to erase its schema) | ||
1. Run `flyway check -drift -check.buildEnvironment="build" -environment="production"` | ||
|
||
Flyway's `check -drift` will then: | ||
1. Take a [`snapshot`](Commands/snapshot) of the target database | ||
2. Clean your build database | ||
3. Query the target database for the list of applied migrations (for simplicity, let's say it's at V2) | ||
4. Apply these migrations to the build database | ||
5. Take a [`snapshot`](Commands/snapshot) of the build database (now also at V2) | ||
6. Compare the V2 target database snapshot to the V2 build database snapshot | ||
7. Generate a HTML (human readable) and JSON (machine readable) Drift Report, indicating the additions, deletions, and modifications of database objects between target and build |
Oops, something went wrong.