Automating database migration (for a CD pipeline)

Hi !

My CD pipeline has a simple script which responsibility is to ensure that the Kong database is up-to-date before starting the tests. Until version 0.14, this script was very simple: kong migration up, as this single command was handling the various use cases:

  • creation of the schema / from scratch database
  • upgrade of the schema from a previous version of Kong
  • and in case the database schema is already up to date, nothing is done!

With the new migration framework, my simple scripts is no longer working and I’m trying to adapt it in order to manage the same use case.
Looking to the implementation of the kong migration list (https://github.com/Kong/kong/blob/master/kong/cmd/migrations.lua#L95), I see some interesting exit codes:

  • If kong migration list exists with code 0, then everything is up-to-date
  • If kong migration list exists with code 3, then a bootstrapping is required, and I can simply run kong migration bootstrap (and nothing more is to be done, am I right ? no kong migration finish)
  • Then, what is less clear for me is what I should do for the other error codes. I have the following feeling; can you please tell me if I’m right:
    – If kong migration list exists with code 4: there are some pending migrations (i.e. the kong migration up has been run previously) => I need to run kong migration finish
    – If kong migration list exists with code 5: there is a need for start the migration => I need to run kong migration up first, and then kong migration finish

BTW, one additional question: the migration from 0.14 to 1.0 requires the two steps: up and then finish. Will these two steps be also required for any further migrations (from 1.0.x to 1.1, from 1.1 to 1.2, etc) or will we be back to a single kong migration up ?

Thanks a lot for your help.

@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,

Thanks @thibaultcha,

which makes me think a status code for “some migrations are still running” might be necessary

yes, would be really helpful ! (even mandatory to script all use cases ??)

BTW, I was also just performing a simple test to get the exit codes of kong migrations list for the migration from version 0.14 to version 1.0: what is surprising is that, doing a kong migrations list in a Kong 1.0 instance but on a Kong 0.14 database, I receive a code 3 meaning: “database needs bootstrapping; run ‘kong migrations bootstrap’”. I was expecting a code 5 (migrations are required), no ?
Is it a specific behavior when migrating from the old to the new framework ?

Well, to complement my last post, I think returning code 3 in the above described situation is indeed a bug as, in this situation:

  • running kong migrations bootstrap generates a failure: “Error: cannot bootstrap a non-empty keyspace, run ‘kong migrations up’ instead”
  • running kong migrations up and then finish works perfectly

This seems like a bug indeed, good catch! I will backlog it and we will address migrations issues in an upcoming release (rather sooner than later).

@pamiel,

There is now a PR that tries to solve the issue, any feedback is welcomed:

Is there a way to run the migrations in one command? I am also struggling to understand when I ned to run kong migrations bootstrap