Évolution des schémas, migrations et compatibilité

Pourquoi les schémas doivent évoluer sans tout arrêter

Toute donnée stockée ou transmise a un schéma : les tables et les types de colonnes d’une base de données, les champs d’une réponse d’API JSON, la définition d’enregistrement d’un événement dans un flux. Les schémas changent sans cesse, parce que l’activité change : la banque ajoute un second titulaire de compte, la plateforme de livraison de repas commence à enregistrer les pourboires, un régulateur exige un nouveau champ. La question architecturale est de savoir comment modifier un schéma pendant que le système continue de fonctionner, alors que l’ancienne forme est encore utilisée par du code, par des données stockées et par d’autres équipes.

Trois faits rendent cela difficile. Premièrement, dans tout système déployé sans interruption de service, l’ancienne et la nouvelle version du code tournent côte à côte : un déploiement progressif (rolling deployment) remplace les instances une par une, un déploiement canari envoie une petite part du trafic vers la nouvelle version, et un retour arrière (rollback) ramène l’ancienne version. Chaque état du schéma doit donc fonctionner avec au moins deux versions du code. Deuxièmement, les données survivent au code. Les lignes écrites il y a cinq ans, les événements d’un journal conservé indéfiniment, les messages en attente dans une file et les sauvegardes gardent tous l’ancienne forme. Troisièmement, les schémas sont partagés : une colonne est lue par des rapports, des tâches d’extraction et parfois d’autres services, et un schéma d’événement est lu par des consommateurs dont le producteur ignore parfois jusqu’à l’existence. La section 7.1 plaidait pour que les données soient détenues derrière une interface ; c’est dans l’évolution des schémas que cette discipline porte ses fruits, car un schéma privé peut être modifié avec l’accord d’une seule équipe.

Rétrocompatibilité, compatibilité future et compatibilité totale

La compatibilité se définit en termes de lecteurs et de rédacteurs. Un changement est rétrocompatible lorsque du code utilisant le nouveau schéma peut lire des données écrites avec l’ancien. Ajouter un champ facultatif doté d’une valeur par défaut est rétrocompatible : le nouveau lecteur fournit la valeur par défaut lorsque le champ manque dans les anciennes données. Un changement offre une compatibilité future (forward compatibility) lorsque du code utilisant l’ancien schéma peut lire des données écrites avec le nouveau. Cela exige que les anciens lecteurs ignorent les champs qu’ils ne connaissent pas, ce qui est la discipline du lecteur tolérant (tolerant reader). Un changement est totalement compatible lorsqu’il est les deux à la fois, ce qui signifie que lecteurs et rédacteurs peuvent être mis à niveau dans n’importe quel ordre.

Le sens dont vous avez besoin découle de qui se met à niveau en premier. Si les consommateurs sont mis à niveau avant les producteurs (cas fréquent lorsqu’un flux a quelques consommateurs que vous contrôlez), il vous faut la rétrocompatibilité. Si ce sont les producteurs qui sont mis à niveau en premier, ce qui est le cas habituel pour une base de données (le nouveau code commence à écrire avant que chaque lecteur ait été redéployé) et pour les API publiques, il vous faut la compatibilité future. Lorsque vous ne pouvez pas contrôler l’ordre, ou devez pouvoir revenir en arrière d’un côté comme de l’autre, visez la compatibilité totale. Confluent Schema Registry, par exemple, applique par défaut une rétrocompatibilité vérifiée par rapport à la version précédente, et propose des variantes transitives qui vérifient par rapport à toutes les versions antérieures, ce qui compte lorsque des consommateurs peuvent rejouer d’anciennes données depuis le début d’un journal.

Un mot d’avertissement sur le vocabulaire. En conception d’API, rétrocompatible s’emploie souvent de façon approximative pour dire les clients existants continuent de fonctionner, ce qui, en termes de lecteurs et de rédacteurs, correspond à la compatibilité future pour les clients qui lisent vos réponses et à la rétrocompatibilité pour les requêtes que vous lisez de leur part. Lorsqu’une discussion repose sur ce terme, demandez quel côté change et quel côté doit continuer de fonctionner.

Expansion-contraction : la technique de base

La plupart des changements cassants peuvent être découpés en une suite de changements compatibles. Ce patron s’appelle expansion-contraction (expand and contract), ou changement parallèle (la description qu’en a donnée Danilo Sato en 2014 sur martinfowler.com, sous le nom de parallel change, nomme les phases expand, migrate et contract). D’abord l’expansion : ajoutez la nouvelle structure à côté de l’ancienne, de sorte que l’ancien comme le nouveau code fonctionnent. Ensuite la migration : faites en sorte que le code qui écrit maintienne les deux, copiez les données existantes, et faites passer les lecteurs à la nouvelle structure un par un. Enfin la contraction : lorsque plus rien n’utilise l’ancienne structure, supprimez-la. Chaque étape est déployée séparément, chacune est compatible avec la version qui la précède, et chacune peut faire l’objet d’un retour arrière sans perte de données.

Le prix à payer est du temps et un désordre temporaire : le changement s’étale sur plusieurs mises en production, et pendant des jours ou des semaines le schéma porte les deux formes. L’avantage est qu’aucune mise en production n’exige d’interruption de service, qu’aucun déploiement ne doit être coordonné entre équipes, et que chaque étape peut être mise en pause. Refactoring Databases (2006), de Scott Ambler et Pramod Sadalage, répertorie des dizaines de refactorisations de bases de données fondées sur la même idée, avec une période de transition pendant laquelle l’ancien et le nouveau schéma coexistent, maintenus en phase par l’application ou par des déclencheurs (triggers).

-- Migration V41 (expand): metadata-only change, no table rewrite in PostgreSQL 11+
SET lock_timeout = '3s';            -- fail fast rather than queue behind long queries
ALTER TABLE restaurants ADD COLUMN postal_code text;

-- Backfill job (run repeatedly by a script, not inside one big migration)
UPDATE restaurants
SET    postal_code = postcode
WHERE  id >= :from_id AND id < :from_id + 5000   -- one small batch per transaction
AND    postal_code IS DISTINCT FROM postcode;

-- Verify before switching reads
SELECT count(*) FROM restaurants WHERE postal_code IS DISTINCT FROM postcode;  -- expect 0

-- Migration V44: enforce NOT NULL without a long blocking scan
ALTER TABLE restaurants ADD CONSTRAINT postal_code_nn CHECK (postal_code IS NOT NULL) NOT VALID;
ALTER TABLE restaurants VALIDATE CONSTRAINT postal_code_nn;  -- scans, but allows writes
ALTER TABLE restaurants ALTER COLUMN postal_code SET NOT NULL;  -- PostgreSQL 12+: uses the check, skips scan
ALTER TABLE restaurants DROP CONSTRAINT postal_code_nn;

-- Migration V45 (contract), weeks later, once nothing reads postcode
ALTER TABLE restaurants DROP COLUMN postcode;

Les migrations en tant que code dans le pipeline de livraison

Les modifications de base de données ont leur place dans la gestion de versions, à côté du code de l’application, sous la forme d’une série ordonnée de migrations, chacune étant un petit script qui fait passer le schéma d’une version à la suivante. Evolutionary Database Design (publié pour la première fois en 2003, réécrit en 2016), de Pramod Sadalage et Martin Fowler, a posé cette pratique, et les outils sont mûrs. Flyway exécute dans l’ordre des fichiers SQL versionnés comme V41__add_postal_code.sql et consigne chacun dans une table flyway_schema_history. Liquibase décrit les changements sous forme de changesets en SQL, XML, YAML ou JSON, suivis dans une table DATABASECHANGELOG. Alembic, pour Python et SQLAlchemy, génère des scripts de révision comportant des fonctions upgrade() et downgrade() et enregistre la révision courante dans alembic_version. Flyway et Liquibase stockent aussi une somme de contrôle de chaque migration appliquée et s’arrêtent avec une erreur si l’une d’elles a été modifiée depuis, ce qui empêche les environnements de diverger en silence.

Dans un pipeline de livraison continue, les mêmes migrations s’exécutent sur une base de données vierge pendant les tests, puis en staging, puis en production, si bien que la production ne reçoit jamais un changement qui n’a pas été répété. Les bonnes pratiques ajoutent quelques règles. Ne modifiez jamais une migration qui a été appliquée où que ce soit ; écrivez-en une nouvelle. Placez les changements de schéma et le code qui en dépend dans des déploiements séparés, le changement de schéma en premier pour une expansion et en dernier pour une contraction. Testez les migrations sur une copie de données de la taille de la production, car une instruction qui prend 50 ms sur une base de test peut verrouiller une grande table pendant une heure. Préférez avancer avec une nouvelle migration plutôt que recourir à des migrations descendantes qui suppriment des colonnes, et les données avec elles. Enfin, laissez la base de données vous renseigner sur les verrous : dans PostgreSQL, un ALTER TABLE qui attend son verrou bloque toutes les requêtes arrivées après lui ; fixez donc un lock_timeout court et réessayez plutôt que de faire la queue derrière un rapport de longue durée.

Gros backfills et modifications de schéma en ligne

Un backfill (remplissage rétroactif) remplit une nouvelle colonne ou une nouvelle table pour les lignes existantes. Exécuté sous la forme d’un seul UPDATE portant sur 400 millions de transactions, il garde des verrous pendant des heures, génère un énorme volume de journal d’écriture anticipée (write-ahead log) que les répliques doivent rejouer (ce qui crée un retard de réplication), et laisse dans PostgreSQL des versions de lignes mortes que le vacuum doit nettoyer. L’approche professionnelle est une tâche séparée et redémarrable qui traite de petits lots par plages de clé primaire, valide (commit) chaque lot, enregistre sa progression, se bride elle-même lorsque le retard de réplication ou la charge de la base augmentent, et qui est idempotente, de sorte que relancer un lot ne cause aucun dégât. Exécutez-la en dehors de l’outil de migration, pour qu’un déploiement n’ait jamais à l’attendre.

Certains changements ne peuvent pas être faits sur place sans verrouillage. PostgreSQL propose CREATE INDEX CONCURRENTLY (qui ne peut pas s’exécuter dans un bloc de transaction, ce qu’il faut indiquer aux outils de migration) et la séquence NOT VALID puis VALIDATE CONSTRAINT présentée plus haut. Pour MySQL, des outils comme gh-ost et pt-online-schema-change construisent une copie fantôme de la table avec le nouveau schéma, la maintiennent en phase avec les écritures en cours et la mettent en place par un bref renommage. Pour changer le type d’une colonne, mieux vaut généralement une expansion-contraction vers une nouvelle colonne qu’un ALTER sur place, qui, dans la plupart des bases de données, réécrit toute la table.

Registres de schémas, Avro et Protocol Buffers

Pour les événements et les messages, l’équivalent d’un outil de migration est un registre de schémas. Les producteurs enregistrent chaque version de schéma ; le registre la vérifie par rapport à la règle de compatibilité configurée et rejette un changement cassant au moment du build ou du déploiement plutôt qu’en production. Chaque message porte un court identifiant de schéma, de sorte que les consommateurs peuvent récupérer le schéma exact avec lequel il a été écrit.

Apache Avro rend explicite le schéma du rédacteur : le décodage nécessite à la fois le schéma du rédacteur et celui du lecteur, et les règles de résolution d’Avro font correspondre les champs par leur nom, ignorent les champs du rédacteur que le lecteur ne connaît pas, et remplissent les champs du lecteur absents des données avec leurs valeurs par défaut déclarées. D’où la règle pratique : donnez une valeur par défaut à tout champ que vous pourriez ajouter ou supprimer. Dans l’exemple ci-dessous, currency et tip_pence ont été ajoutés dans des versions ultérieures avec des valeurs par défaut, si bien que les anciens événements se décodent toujours avec les nouveaux consommateurs.

Sur le réseau, Protocol Buffers identifie les champs par leur numéro, et non par leur nom. Ajouter des champs est sûr, et les anciens lecteurs conservent les champs inconnus lors d’une nouvelle sérialisation. Renommer un champ n’affecte pas l’encodage binaire (même si cela change la forme JSON). Les règles cardinales sont de ne jamais changer ni réutiliser un numéro de champ, et de marquer les numéros et les noms des champs supprimés comme reserved afin que personne ne les réutilise par accident. Confluent recommande la rétrocompatibilité transitive pour Protobuf, car l’ajout d’un nouveau type de message n’assure pas la compatibilité future. JSON Schema peut aussi être enregistré et vérifié, mais l’ouverture de JSON (une propriété inconnue est-elle autorisée ou non ?) rend les règles de compatibilité plus subtiles.

{
  "type": "record",
  "name": "OrderPlaced",
  "namespace": "food.orders.v1",
  "fields": [
    {"name": "order_id",       "type": "string"},
    {"name": "restaurant_id",  "type": "string"},
    {"name": "total_pence",    "type": "long"},
    {"name": "currency",       "type": "string", "default": "GBP"},
    {"name": "tip_pence",      "type": ["null", "long"], "default": null}
  ]
}

Faire évoluer les schémas d’API et d’événements

Les API et les événements suivent les mêmes principes avec des outils différents. Pour les API, privilégiez le changement additif, exigez que les clients soient des lecteurs tolérants, et réservez les changements cassants à une nouvelle version exécutée à côté de l’ancienne, avec une supervision de l’usage pour savoir quand l’ancienne version peut être retirée (la section 6.5 présente les approches de versionnage). Les tests de contrat pilotés par le consommateur permettent à chaque consommateur de publier les champs dont il dépend réellement, si bien que le fournisseur sait quels changements sont sûrs.

Les événements sont plus difficiles que les API parce qu’ils sont stockés : un consommateur peut rejouer un topic depuis le début, et un système fondé sur l’event sourcing (section 7.5) reconstruit son état à partir d’événements écrits il y a des années. Traitez un schéma d’événement publié comme un contrat public, versionnez-le dans le registre et, lorsqu’un changement est réellement cassant, publiez pendant un certain temps un nouveau type d’événement ou un nouveau topic (OrderPlaced.v2) à côté de l’ancien plutôt que de modifier l’existant. La section 6.4 traite plus généralement de la conception des événements.