Schema versions

Due to https://github.com/Kinto/kinto/issues/1460, if you have ever "flushed" your Kinto server, you probably broke migration. Starting in Kinto 8.1.2, we start to log a very verbose error message when we detect a flushed server. Part of the error recovery procedure we follow is to guess about what the schema version is. However, if our guess was wrong, migration will fail and/or most queries will break.

This wiki page is meant to help you figure out what happened and how to recover.

Storage schema

A Kinto storage backend is responsible for storing and retrieving records, as well as marking them deleted, updating them, etc. The Kinto postgres storage backend stores records in PostgreSQL tables. Exactly what arrangement of tables and how they relate to each other has changed over time as we have benefited from experience of running Kinto at scale and discovered performance issues, race conditions, and other undesirable behaviors.

The postgres storage backend has a mechanism allowing these changes to be made relatively easily by the developers. A special table called metadata tracks the current schema "version", and when the developers want to change the schema, they write a migration explaining how to transform it into the new version. When you run a kinto migrate command, the storage backend "replays" every migration from the version you were on to the current one. If all goes well, at the end, you will have all your same data, but in a new format.

Kinto has a "flush" functionality that allows an administrator to completely wipe a Kinto server's data while leaving its structure in place. This was mostly used in tests, but it was also exposed as a separate endpoint for "dev" servers. However, this "flush" functionality in the postgres storage backend would also remove everything from the metadata table. This behavior (reported as #1460) means that Kinto would lose track of what version of the schema we had. While in principle it's possible to detect this by looking at the Postgres tables, doing so in an automated fashion seemed like a low-value fix since it's a one-off bug that only affects people who used the flush functionality (which seemed like it should be rare).

OK so what do I do?

If you are lucky, you may not need to do anything. Kinto will guess that you had the latest version of the schema where #1460 was present (version 20). At the next migration, it will record that you are at version 21, and you'll be fine.

If you are unlucky, you may have been running an earlier Kinto. In this case, guessing that you had version 20 is wrong. You will have to figure out what version your schema is, and manually set the schema_version information in a way that Kinto can detect it. You may be able to figure out what version you had based on the Kinto version you were running previously, or by looking at the Postgres tables yourself.

Once you know what schema version you have, you can put that information into the metadata table using a SQL command such as:

INSERT INTO metadata VALUES ('storage_schema_version', '19');

Rerunning the migrations should work, since migrations are usually OK to rerun.

List of versions

Kinto Version	Schema Version	What changed
2.1.1	11	Recreate triggers (mozilla-services/cliquet#698)
3.3.0	12	Wipe leftover tombstones (#715)
3.3.0	13	Tweak bump_timestamps procedure (#713)
5.0.0	14	Change conditions for calling bump_timestamps procedure (#900)
6.0.0	15	Update collection_timestamp and bump_timestamps procedure (#1125)
7.6.0	16	Removed collection_timestamp procedure (#1359)
7.6.0	17	Changed behavior of bump_timestamps procedure (#1361)
7.6.2	18	deleted table is merged with records table (#1386)
8.1.0	19	records table ID fields become COLLATE "C" (#1436)
8.1.1	20	timestamps table ID fields become COLLATE "C" (#1454)

Schema versions earlier than this were in the cliquet project, which has now long since been merged into Kinto. If you are on a version of Kinto this old, sorry, you're on your own!