Rename init to baseline to avoid confusion

[flavor8]

The documentation implies that your first migration can be V1. However, a migration with version 1.0.0 is not ever run; in mergeAvailableAndAppliedMigrations, the migration with version 1.0.0 is merged with the already applied init migration, and thus not picked up. Please either fix the merge logic (to never merge the init) or the documentation to be clearer about the first migration name.

[axelfontaine]

The documentation and the merge logic are fine.

The problem is people run init (only meant for tagging existing databases as having a specific version) on new databases. The init version is 1.0. This then rightly prevents a migration with version 1.0 from being applied.

I don't know exactly why people insist on running init. (You are far from being alone here)

My suspicion is that people don't read the docs about init, yet due to the name it seems logical to execute it.

Is this what happened in your case? Please help me understand the thought process so I have a better chance at making this more intuitive in the future.

I am thinking about addressing this in a future release by either:

• renaming init to something less attractive to blindly run/more descriptive of the intention
• change the initVersion default away from 1.0
• prevent init from being run against a blank database

What do you think? Which option(s) make the most sense and why?

Cheers
Axel

[flavor8]

Aha - yes, that's what I did. Init seems logical - it sounds like the first thing you want to do is install the metadata table. I think the issue is that the init documentation isn't particularly findable on the site; the "commands" table at the bottom of the page seem like logical and complete descriptions, and the "(existing database)" part of the init description doesn't particularly jump out. Even knowing that there should be a specific section about init on the site, I can't find it at a quick glance; I do see that you have an "Existing database setup" page, but a) as somebody with a new database I'm not going to read that and b) even scanning it quickly, it looks like it's using a super-advanced variant of init, i.e. it's not clear that this is exactly what init is for.

I would suggest a new sidebar section with each of the commands, above "execution modes". You should also link to them from the commands table. I think that'll make it more likely that people like me who skim docs will discover that init is not necessary.

But, worth also making a code change -- I would suggest that your 2nd option is the best; set init to be version -1, perhaps? Ugly, but then even if somebody started with V0 their migration would still be applied.

[dereknheiley]

Please help me understand the thought process so I have a better chance at making this more intuitive in the future.

• renaming init to something less attractive to blindly run/more descriptive of the intention
• change the initVersion default away from 1.0
• prevent init from being run against a blank database

Sorry to dig up a dinosaur here @axelfontaine, but i'm having an issue with using basselineOnMigrate over initOnMigrate. I'm not sure if it's a bug long since fixed from flyway 6.4.4 (can't upgrade at this time).

Scenario; trying to perform a 'factory reset' from java spring boot on postgres 12
0. user clicks factory reset

1. java drops all tables in schema, based on list in SELECT tablename FROM pg_tables WHERE schemaname = 'myschema'
2. restart java spring boot and flyway throws

DEBUG ..sys.PostgresDbService [128]dropTablesAndReleaseDiskSpace() dropped 'public' 'table_1'
DEBUG ..sys.PostgresDbService [128]dropTablesAndReleaseDiskSpace() dropped 'public' 'table_2'
DEBUG ..sys.PostgresDbService [128]dropTablesAndReleaseDiskSpace() dropped 'public' 'table_3'
DEBUG ..sys.PostgresDbService [128]dropTablesAndReleaseDiskSpace() dropped 'public' 'table_4'
DEBUG ..sys.PostgresDbService [128]dropTablesAndReleaseDiskSpace() dropped 'public' 'table_5'
DEBUG ..sys.PostgresDbService [128]dropTablesAndReleaseDiskSpace() dropped 'public' 'table_6'
DEBUG ..sys.PostgresDbService [128]dropTablesAndReleaseDiskSpaceBeforeRestart() also dropped unknown table 'public' 'unknown_1'
DEBUG ..sys.PostgresDbService [128]dropTablesAndReleaseDiskSpaceBeforeRestart() also dropped unknown table 'public' 'unknown_2'
DEBUG ..sys.PostgresDbService [128]dropTablesAndReleaseDiskSpaceBeforeRestart() dropped 'public' flyway_schema_history'
INFO ..sys.PostgresDbService [128]Completed dropTablesAndReleaseDiskSpaceBeforeRestart() from Postgres repos : 519.260637ms
//restart
INFO ..cor.int.lic.VersionPrinter [1]Flyway Community Edition 6.4.4 by Redgate
INFO ..cor.int.dat.DatabaseFactory [1]Database: jdbc:postgresql://localhost:5432/smart (PostgreSQL 12.12)
DEBUG ..cor.int.dat.DatabaseFactory [1]Driver : PostgreSQL JDBC Driver 42.2.24
DEBUG ..cor.Flyway [1]Schemas: public
DEBUG ..cor.Flyway [1]Default schema: null
...
INFO ..cor.int.com.DbValidate [1]Successfully validated 15 migrations (execution time 00:00.037s)
DEBUG ..cor.Flyway [1]Memory usage: 71 of 358M
...
ERROR org.flywaydb.core.api.FlywayException: Found non-empty schema(s) "public" but no schema history table. Use baseline() or set baselineOnMigrate to true to initialize the schema history table.

3. use intOnMigrate=true and Flyway creates version table without creating baseline migration as i'm expecting, and my first v1 migration runs normally (i could rename it to v1.1 i suppose).

In this case, i think the FlywayException: Found non-empty schema(s) "public" but no schema history table might be a bug caused by spring.flyway.schemas=${my.app.postgres.schema} being specified, because if i comment out that option, i do not get any error on the same schema (here i'm testing with my.app.postgres.schema=public for simplicity). The advantage of initOnMigrate i'm seeing is that it correctly warns me if the DB schema isn't empty - which i want, but otherwise creates the missing version table for me after i've dropped all my old tables

If i were to use baselineOnMigrate instead, it plows into the schema and assumes existing tables are fine - i don't want this to always be the assumption just to support a "factory reset". I want to configure with an application property and only enable 'baselineOnMigrate' when absolutely required (this would prevent dropping unknown tables as well - which is why i don't just drop the schema).

For example with
spring.flyway.initOnMigrate=true
spring.flyway.baselineOnMigrate=${my.app.postgres.allowAndIgnoreExisingTables}

[dereknheiley]

Nevermind, initOnMigrate didn't fix anything, manually dropping and recreating the DB gave me a false sense of hope that it did. My underlying problem seemed to be manually deleting tables along with the flyway version table resulting flyway throwing the above error because of something else in the schema related to flyway not being in an expected state.

Solution was;

• drop the entire schema (which was complicated for me)
• use flyway clean (which didn't work so great on timescale MATERIALIZED views)
• manually delete my tables with cascade, and then call flyway clean to handle it's internal state and worked as expected when app was restarted and flyway found a scheme without tables matching it's migrations