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.

Tools

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 selectable 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 selectable differences.

generate_migrations

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

Returns the migration folder path, the list of generated files, and any warnings raised during generation.

review_code

Runs code review against a single migration script and reports the rule violations found.

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).

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 a git pull brought in versus your own local changes.

Returns a diffId and a list of selectable 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.

Returns changesDeployed (a boolean indicating whether a deployment action was performed against development—this may be false if no changes were selected) and the list of objects updated in the development database.

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 text for the requested change.