This feature is in preview. Tool names, parameters, and behavior may change significantly, or tools may be removed, in future releases without notice. This reference describes the tools in Flyway 13.11.1.

Concepts

• Workspace: Calling load_project loads a Flyway project into a workspace, identified by a workspaceId. Only one workspace is loaded at a time; loading a new project discards artifacts and results from the previous one. If you've only changed the project's TOML configuration, call reload_project instead, which preserves existing artifacts.
• Diffs and artifacts: Each create_diff_* tool computes the difference between two states of your project (for example, the development database and the schema model) and returns a diffId. Other tools then consume that diffId, together with a list of change IDs, to apply or generate something from the selected differences.
• Selecting changes: Tools that accept a changes list of IDs also accept a single * to select every change from a diff. You can't mix * with specific IDs. If a selected change depends on another change that wasn't selected, the dependency is included automatically.

• Three-sided diff: Instead of comparing two states, create_diff_development can compare three—the current schema model, the development database, and a schema model checkpoint captured earlier via create_schema_model_checkpoint. Each change is tagged with how the schema model has moved since the checkpoint (new, existing, missing, or conflict), which lets you separate changes you introduced locally from ones brought in from a shared source. See create_diff_development for details.

• Diff names: A create_diff_* tool is named for what its changes are applied to, not for the direction of the comparison. create_diff_schema_model produces changes to apply to the schema model (by comparing the development database against it), create_diff_migrations produces changes to generate migration scripts from, and create_diff_development produces changes to apply to the development database.
• Selectable differences: Each create_diff_* tool returns a diffId and a list of differences. Each difference has an id (used in changes lists and as changeId), the object's name and type, a change of Add, Edit, Rename or Delete, and, for a rename, its previousName. Calling a create_diff_* tool again replaces the previous diff of that type, so the earlier diffId is no longer valid.
• Parameter types: IDs (workspaceId, diffId, migrationsDiffId, checkpointId and changeId) are strings returned by earlier tool calls. Copy them exactly rather than constructing them. changes is an array of strings, such as ["chg-1", "chg-3"], or ["*"] to select everything. generateUndoScripts and rebuild take true or false; projectFolder, file and description are strings.
• Errors: A failed call returns an error result containing the error code and message, for example PROJECT_NOT_LOADED Project workspace 'ws-1234' is not loaded. The Troubleshooting page covers the common ones.

Tools

What each tool reads and writes

Only update_development changes your development database. create_diff_migrations and test_migrate use the shadow database, and the create_diff_* tools keep their results in the server's temporary workspace rather than in your project.

load_project

Loads a Flyway project into a workspace. Required before any other tool can be used.

Returns a workspaceId, used by all subsequent tool calls.

reload_project

Reloads a project from disk for an existing workspace, without discarding previously computed artifacts. Prefer this over load_project when you've only edited the project's TOML files.

create_schema_model_checkpoint

Captures a checkpoint of the current schema model. The checkpoint can be used as input to create_diff_development to categorize changes by origin (schema model vs. checkpoint) as a three-sided diff.

Returns a checkpointId, for use as an input to create_diff_development.

create_diff_schema_model

Diffs the development database against the project's schema model. Feeds into update_schema_model. Only one such diff is stored per workspace at a time.

Returns a diffId and a list of differences.

update_schema_model

Updates the schema model files using selected changes from a schema model diff.

Returns the list of schema model files that were updated, relative to the project's schema model folder.

create_diff_migrations

Diffs the schema model against the current state of the migration scripts, built via the shadow environment. Feeds into generate_migrations. Only one such diff is stored per workspace at a time.

Returns a diffId and a list of differences.

generate_migrations

Generates migration scripts from a migrations diff. Scripts are named automatically using the project's configured naming convention.

Whether an undo script is also generated for each versioned script is controlled by the project's flyway.generate.types TOML setting, e.g.:

[flyway.generate]
types = ["versioned", "undo"]

unless overridden for this call via generateUndoScripts. If flyway.generate.types isn't set at all, the flywayDesktop.generate.undoScripts toml setting is used as a fallback, e.g.:

[flywayDesktop.generate]
undoScripts = true

Returns the migrationFolder path, the list of generated files (relative to that folder), any warnings raised during generation (each with a file, message, type and severity), and whether undo scripts were generated (undoScriptsGenerated).

review_code

Runs code review against a single migration script and reports the rule violations found. It uses the project's code review configuration, as flyway check -code does.

Returns the absolute path of the reviewed file, the list of issues (rule violations) found, the definitions of the violated rules, and total_rules_checked (the number of rules evaluated).

test_migrate

Runs pending migration scripts against the shadow database to verify they execute without errors. The shadow database may be automatically reprovisioned first if the migration history has diverged. Each migration that ran during this call is reported as success; if one fails, execution stops and that migration is reported as failed, with any remaining scripts reported as pending.

Returns results (per-file migration results in execution order, each with a file name and a status of success, failed, or pending), error (the error message from the failed migration; omitted when all migrations succeeded), and reprovisioned (whether the shadow database was fully reprovisioned during this call; always false if a migration failed, even when a reprovision happened first).

create_diff_development

Diffs the schema model against the development database, describing the changes needed to bring the development database in line with the schema model. Feeds into update_development. Only one such diff is stored per workspace at a time.

If a checkpointId is supplied (from create_schema_model_checkpoint), a three-sided diff is performed instead: the schema model as it was at the checkpoint is compared against both the current schema model and the development database, classifying each change by how the schema model has moved since the checkpoint (new, existing, missing, or conflict). This distinguishes changes that predate the checkpoint from ones introduced since—for example, changes brought in from a shared source versus your own local edits.

Returns a diffId and a list of differences. When checkpointId is supplied, also returns threeSidedDifferences—the same differences, each tagged with how the schema model has moved since the checkpoint (new, existing, missing, or conflict).

update_development

Applies selected changes from a development diff to the development database. This modifies the database that your flywayDesktop.developmentEnvironment points at. For supported database types, a dependency of a selected change is included automatically and, where available, listed in objects.

Returns changesDeployed (a boolean indicating whether a deployment action was performed against development—this may be false if no changes were selected) and objects, the list of objects updated in the development database, each with a name, a type and where the update came from (origin). objects is only given for some database types, and is omitted when nothing was applied.

get_diff_details

Returns the unified diff text for a single changed object within a diff previously created by any create_diff_* tool, in the same workspace.

Returns the unified diff as text. Very large objects fail with The object detail exceeds the rendering limit of 500 lines.