Automating database migration (for a CD pipeline)

Questions
2

@pamiel Good observations! Yes, one of the goals for the new migrations framework was to be more scriptable (easier to automate).

We don’t have yet a section documenting the new migrations framework, but we will be working on it in the next few weeks. In the meantime, let me clarify your questions:

If kong migration list exists with code 0, then everything is up-to-date

Correct.

If kong migration list exists with code 3, then a bootstrapping is required

Correct. And yes, running kong migrations bootstrap does not require running kong migrations up afterwards.

If kong migration list exists with code 4: there are some pending migrations

Correct. This means that some migrations executed their first step, but not their second one (they are “pending”). Running kong migrations finish is necessary (if you are sure that all of your old nodes are decommissioned and that all migrations have finished executed their first step, which makes me think a status code for “some migrations are still running” might be necessary).

If kong migration list exists with code 5: there is a need for start the migration

Correct, kong migrations up, followed by kong migrations finish.

Will these two steps be also required for any further migrations

It depends on the migrations themselves. Two-step migrations allow for temporary backwards-compatibility with previous nodes (e.g. renaming columns, moving data around, etc…). If migrations don’t require backwards-compatibility (i.e. they add new tables, columns, or else, that old nodes will not even see/use), then they can be one-stap migrations. Remember that once kong migrations up has finished, you must decommission old nodes before running kong migrations finish (and that whether or not you need to run finish can be indicated by list).

The “algorithm” to follow isn’t too complicated, we may write it in pseudo-code in the upcoming documentation about migrations in 1.0. Also, have a look at this earlier message in the 1.1 release thread, it will be helpful too: Kong 1.1.0rc1 available for testing - #5 by thibaultcha

Best,