Documentation for "mixed" config setting is misleading

The documentation for the “mixed” config setting is misleading. It says:

Whether to allow mixing transactional and non-transactional statements within the same migration. Enabling this automatically causes the entire affected migration to be run without a transaction.

Note that this is only applicable for PostgreSQL, Aurora PostgreSQL, SQL Server and SQLite which all have statements that do not run at all within a transaction.

This is not to be confused with implicit transaction, as they occur in MySQL or Oracle, where even though a DDL statement was run within within a transaction, the database will issue an implicit commit before and after its execution.

[emphasis mine]

To me that says that if I turn on the “mixed” setting, flyway will never run a migration in a transaction. But testing that out, it still ran a simple migration in a transaction. Doing on a search on github issues, it seems this setting turns on a mode where flyway tries to guess whether the migration script should not automatically be wrapped in a transaction based on the presence of certain statements in the script. Is this correct? I didn’t see that in the docs.

I don’t want flyway to guess whether a script should be wrapped in a transaction or not. I would like to disable automatic transactions for all migration scripts and leave it up to the scripts to use transactions. I see that you can disable the automatic transaction on a script-by-script basis with a <script_name>.conf file that contains executeInTransaction=false. But that has to be done for every script. Is there any way to disable automatic transactions for all migrations without having to create a .conf file for every migration script?

Which version and edition of Flyway are you using?

Flyway Community Edition 6.4.1

If this is not the latest version, can you reproduce the issue with the latest one as well?

(Many bugs are fixed in newer releases and upgrading will often resolve the issue) This is the latest version.

Which client are you using? (Command-line, Java API, Maven plugin, Gradle plugin)

Command-line

Which database are you using (type & version)?

PostgreSQL 12.2

Which operating system are you using?

Flyway is running on Windows, PostgreSQL is running on the postgres:12.2 docker image.

What did you do?

(Please include the content causing the issue, any relevant configuration settings, the SQL statement that failed (if relevant) and the command you ran.)

flyway.conf:

flyway.locations=filesystem:.
flyway.mixed=true
flyway.cleanDisabled=true

V1__initial_schema.sql:

BEGIN TRANSACTION;

CREATE TABLE thing
(
  thing_id int NOT NULL PRIMARY KEY, -- trailing comma after last column is a syntax error
);

COMMIT TRANSACTION;

I ran

C:\projects\flyway_test_2>flyway -url="jdbc:postgresql://localhost:6543/flyway_test_2" -user=postgres -password=postgres_pw migrate

What did you expect to see?

I expected to see an error about the syntax error, but no warning about a transaction being already in progress.

What did you see instead?

C:\projects\flyway_test_2>flyway -url="jdbc:postgresql://localhost:6543/flyway_test_2" -user=postgres -password=postgres_pw migrate
Flyway Community Edition 6.4.1 by Redgate
Database: jdbc:postgresql://localhost:6543/flyway_test_2 (PostgreSQL 12.2)
Successfully validated 1 migration (execution time 00:00.017s)
Creating Schema History table "public"."flyway_schema_history" ...
Current version of schema "public": << Empty Schema >>
Migrating schema "public" to version 1 - initial schema
WARNING: DB: there is already a transaction in progress (SQL State: 25001 - Error Code: 0)
ERROR: Migration of schema "public" to version 1 - initial schema failed! Changes successfully rolled back.
ERROR:
Migration V1__initial_schema.sql failed
---------------------------------------
SQL State  : 42601
Error Code : 0
Message    : ERROR: syntax error at or near ")"
  Position: 116
Location   : .\V1__initial_schema.sql (C:\projects\flyway_test_2\.\V1__initial_schema.sql)
Line       : 3
Statement  : CREATE TABLE thing
(
  thing_id int NOT NULL PRIMARY KEY, -- trailing comma after last column is a syntax error
)

[MikielAgutu]

Excellent! I’ll note that we should make our docs clearer.

[MikielAgutu]

Not quite correct. Paraphrasing from the docs:

• By default, Flyway runs each migration within its own transaction
• If Flyway detects that a specific statement cannot be run within a transaction, it won’t run that migration within a transaction
• Transactional and non-transactional statements cannot be mixed within a migration run

So, by default Flyway will refuse to run a migration if it contains both transactional and non-transactional statements. To allow transactional and non-transactional statements inside a single migration run, you can set mixed to true.

executeInTransaction will override Flyway’s auto-detection process. It forces the migration to run as specified.

From your first post:

To me that says that if I turn on the “mixed” setting, flyway will never run a migration in a transaction.

The mixed setting doesn’t do this. Flyway will still try and put things in transactions if possible.

Does that help?