Aller au contenu

Évolution du schéma

Dans Facet, changer un doctype ne réécrit jamais les documents stockés. La définition passe à une nouvelle version de schéma, et chaque document se met à jour à la prochaine lecture qui le touche. C’est la migration à la demandeà : pas de job de backfill, le travail de migration se fait à la lecture.

Read request Read request

Chaque doctype porte un entier schema_version, qui démarre à 1. Chaque document stocke son propre meta.schema_version : la version active lors de sa dernière écriture. Une lecture compare les deux nombres. Quand le nombre stocké est inférieur, la lecture exécute les fonctions de migration de chaque écart de version, dans l’ordre. Puis elle enregistre le résultat comme un instantané et renvoie le document migré. La lecture suivante saute ce travail, car la version stockée correspond désormais.

Lectures et listes migrent toutes les deux. Les lectures individuelles comme les listes migrent. Une liste migre chaque ligne périmée avant d’appliquer le masque de lecture. La migration tourne sur une connexion d’écriture, sous un verrou de ligne. Des lectures concurrentes ne peuvent donc pas migrer deux fois le même document.

Une mise à jour de doctype doit augmenter schema_version d’exactement un — impossible de sauter une version. Chaque écart entre l’ancienne et la nouvelle version demande une entrée de migration. Chaque fonction nommée doit exister dans le script Lua du doctype. La map migrations de la définition les nommeà :

{
"schema_version": 3,
"migrations": {
"1": "migrate_from_1",
"2": "migrate_from_2"
}
}

Une fonction de migration est du Lua ordinaire, dans le même script que les hooks de cycle de vie. Elle modifie le contenu du document en place, et les hooks de cycle de vie ne se réexécutent pas pendant la migration. Rien n’est automatique dans un changement de champ — c’est la fonction qui opère chaque changementà :

Changement La fonction de migration Exemple
Ajouter un champ avec une valeur par défaut Poser la clé sur l’ancien contenu ctx.root.department = "Engineering"
Supprimer un champ Retirer la clé de l’ancien contenu ctx.root.full_name = nil
Changer le type d’un champ Lire l’ancienne valeur, écrire la nouvelle forme Scinder full_name en first_name et last_name

Une fonction de migration signale un échec avec ctx.error. Facet écrit un marqueur migration_error dans le meta du document et renvoie le contenu périmé. Les lectures et les listes suivantes sautent le document marqué au lieu d’échouer. Le marqueur indique pourquoi la migration a échoué, vous pouvez donc lire la cause sans la relancer.

Réessayer depuis la CLI. La reprise passe par une commande CLI. facet doctype:migrate-retry hr.Employee efface le marqueur et relance la migration. Une tentative échouée n’écrit rien, la commande peut donc être relancée sans risque une fois la définition corrigée.

Le compromis, c’est la coexistence. Un document jamais lu garde sa forme ancienne pour toujours. Une fonctionnalité qui a besoin du nouveau champ le trouve absent sur ces documents. Le coût de la migration retombe sur les lectures, pas sur le changement de version. En échange, un changement de schéma se déploie sans backfill de toute la table.