Le blog technix

Suivi de la dérive de nos dépendances

2023-11-27T00:00:00+00:00

Le constat

Le suivi de nos dépendances logiciels n’a jamais été un sujet suivi chez Pix. Les mises à jour se sont fait donc au bon vouloir de quelques personnes.

Dans le passé, une petite équipe avait été créée pour mettre à jour Ember sur nos applications clientes. Cela fonctionne bien par à-coups, mais ne règle pas le problème de suivi.

C’est pourquoi Renovate a été mis en place. Renovate est présent sur tous nos dépôts et nous pousse en permanence des mises à jour de nos dépendances. Avec le “Dependency dashboard” (voir celui de 1024pix/pix), nous pouvons avoir les différentes mises à jour en attente. Cela nous donne une idée du retard mais cela reste très grossier.

C’est pourquoi lors des Tech Days 2023 (du travail technique réalisé pendant l’été), une équipe s’est chargée de remettre de l’effort sur les mises à jour de dépendances. Le travail a été de passer à node 18 sur notre application principale et de configurer Renovate pour que tout roule.

Le besoin de quantifier d’une manière commune le retard de mise à jour des dépendances sur les différents projets nous a amené à nous intéresser à une métrique intéressante, libyear.

Libyear à la rescousse

En bref libyear permet de quantifier l’âge de l’ensemble des dépendances.

En calculant cette métrique sur nos différents projets, nous avons une mesure comparable pour constater et décider des actions de mise à jour. C’est pourquoi nous avons développé dependency-drift-tracker qui nous permet de connaitre la dérive actuelle de nos dépendances, de voir l’évolution et de comparer ce retard avec les autres.

En plus du retard de nos dépendances, nous affichons également la mesure en années depuis la dernière release, appelée Pulse. Cela permet de repérer des dépendances qui sont devenues obsolètes ou dépréciées. Cela nécessite une analyse un peu plus poussée manuelle.

A quoi cela ressemble ?

À gauche, en un clin d’œil, on voit les dépôts suivis avec l’information du retard. Ensuite dans le panneau principal, 2 métriques sont affichées, le retard et et le pulse.

Les 2 graphs suivants permettent de suivre l’évolution de ces chiffres à travers le temps.

Enfin le tableau final affiche le résultat du dernier lancement de libyear avec les informations de dépendances individuelles.

Les données sont rafraîchies tous les jours. Un retour suffisamment régulier pour valoriser le travail accompli la veille, et planifier la suite.

Conclusion

Rendre visible notre retard nous a permis de nous améliorer sur le suivi des versions. Voir la baisse de la courbe après une mise à jour est toujours un plaisir. Même si, d’une manière continue et semble t’il inexorable, la courbe remonte suite aux mises à jour des dizaines de dépendances utilisées par nos applications.

Curieux·ses, voici le suivi des applications Pix.

Essayez-le

Nous avons rendu le code de suivi générique pour être utilisable par n’importe quel projet javascript. Vous pouvez facilement gérer les fichiers de suivi manuellement via dependency-drift-tracker, ou encore plus simplement avec l’action GitHub dependency-drift-tracker-action.

Et lisez la documentation.

Migrer de CommonJS vers ECMAScript Modules - #2

2023-09-06T12:04:00+00:00

Cet article est la suite de la théorie sur la migration ESM. Il explique comment nous nous y sommes pris pour migrer l’API du monorepo Pix.

Si vous n’avez que cinq minutes, lisez la stratégie.

Si vous avez un peu plus de temps, choisissez dans le menu.

Voilà les plats principaux :

monter et faire vivre l’équipe dédiée ;
la stratégie de migration ; un zoom sur deux décisions d’implémentation de la codebase ;
faire de la mise en production un non-évènement.

Et si vous êtes gourmands, lisez tout du début à la fin…

L’équipe

Traiter les besoins internes

Chez Pix, le développement est effectué par des Feature Teams (FT), qui reçoivent les besoins utilisateurs principalement du Product Owner (PO). Les développeurs peuvent participer au recueil et au raffinement du besoin, et le questionner lors de l’implémentation (le détail est expliqué ici).

Les besoins d’amélioration interne au pôle engineering, dont fait partie la migration ESM, suivent un processus particulier, appellé “Impact Team”. Des développeurs sont détachés de leur équipe pour un temps défini, en général quelques semaines, avec un objectif clair, même si le sujet est exploratoire.

Pour la migration ESM, un développeur a fait une présentation de 15 minutes à tous les autres développeurs, en exposant le besoin et la solution qu’il proposait. Il a ensuite proposé qu’un autre développeur, volontaire, le rejoigne pour deux semaines afin de réaliser la migration.

Travailler ensemble

La taille de l’équipe, 2 personnes, est importante :

suffisamment grande pour résoudre le problème théorique et permettre les absences ponctuelles ;
suffisamment petite pour minimiser le surcoût de coordination.

Le développement, dès le début, s’est fait en pair programming, en rotations de 30 minutes, la plupart du temps en présentiel. Le pair programming est encouragé chez Pix et il a été crucial ici : répartir la connaissance, trouver les solutions et se soutenir lorsqu’il fallait effectuer des corrections manuelles.

Les corrections manuelles ont aussi été faites en pair programming, même si on pense spontanément à paralléliser les tâches répétitives. En effet, la personne qui ne code pas, pendant que son partenaire modifie les fichiers :

signale les erreurs d’inattention ;
pense aux cas qui ne sont pas couverts ;
suggère de meilleurs moyens d’effectuer la correction (ex: grouper les fichiers) ;
prend du recul sur ce qui se passe.

Être deux nous a aussi permis de prendre soin l’un de l’autre et de mener à bien la migration. Seuls, nous n’aurions pas reconnu la fatigue et aurions persisté dans des solutions qui étaient des impasses. Mon ressenti est qu’il a été plus facile de prendre soin de l’autre que de moi-même, et que l’autre me rappelait quand je ne prenais pas soin de moi. Et vice-versa, dans un cercle vertueux.

En plus de cette boucle de feedback de 30 minutes, il y avait une boucle quotidienne. La journée commençait avec un partage de 15 minutes de l’avancée avec les CTO, sur la base d’un résumé fait en fin de journée sur le Wiki interne. Cela permet de s’assurer que nous étions sur le bon chemin, et d’envisager des actions pour enlever des obstacles, par exemple demander de l’aide en dehors de l’équipe.

Ce partage quotidien a assuré la confiance. Lorsque les deux semaines initialement imparties étaient écoulées, les CTO ont décidé que la migration pouvait être poursuivie, sachant que nous traitions les risques les plus importants en premier. Si la migration s’avérait impossible, ils le sauraient rapidement et pourraient décider d’arrêter le chantier.

Ne gardons pas le suspense plus longtemps, d’autant que la présentation de l’article le mentionne : la migration a pris deux mois au lieu des 2 semaines annoncées (ce qui était prévisible après tout).

La stratégie

Parler de stratégie n’est pas tout à fait honnête, car nous n’avions pas de plan, uniquement quelques principes. Nous partageons ici notre expérience pour vous aider à en avoir une si vous vous lancez dans l’aventure.

Un feedback rapide ?

Nous n’avons envisagé la migration que parce que nous avions des tests automatisés avec une bonne couverture.

La démarche classique de refactoring (car c’en est un) aurait été de migrer un fichier (SUT) en ESM et de vérifier que le test passe toujours. Le test (CJS) importerait le SUT (ESM), qui lui-même importerait des dépendances (ESM). Pour cela, il faudrait que ESM et CJS soient interopérables, et bien que le sujet commence à être implémenté et documenté, l’investissement ne semblait pas être un bon compromis.

Nous pensions procéder en trois étapes :

migrer l’implémentation et effectuer un test manuel, à savoir démarrer l’API ;
exécuter les tests automatisés de bout en bout (front + back) ;
migrer les tests automatisés de l’API puis les exécuter.

La conséquence était la suivante : pendant la première partie, nous n’avions plus aucun test qui nous couvrait. Autrement dit : nous modifions la moitié de la codebase sans savoir si nos modifications étaient correctes. Même la vérification statique (lint) n’a pas fonctionné tout de suite, car un fichier dont le code est invalide ne peut être parsé. Les modifications étant effectuées par des codemods et des modifications manuelles, si elles se révélaient incorrectes et qu’il fallait les rejouer, nous n’étions pas à l’abri de devoir refaire ces actions manuelles.

Lorsque les deux semaines se sont allongées, nous ressentions de plus en plus cette épée de Damoclès. À la prochaine migration de codebase, il serait judicieux de remettre en cause cette stratégie.

Des compromis, encore et toujours

Dès le début, nos réflexes de développement ont été mis à rude épreuve. Voilà les observations des équipes sur le travail de l’impact Team.

La migration a duré deux mois au lieu des deux semaines annoncées. Son développement a duré un mois et demi et la mise en production 15 jours. La PR principale modifiait la moitié de la codebase, et devait être rebase manuellement avant chaque livraison. Elle comportait 130 commits, dont une centaine pour les corrections manuelles. Les codemods ont été écrits par l’équipe en charge de la migration, ne sont pas dans la codebase et ne sont pas réutilisables. La manière de travailler de l’impact team ne semble pas leur avoir simplifié la vie.

Nous avons pourtant travaillé dur pour que la solution soit simple et viable, ce qui nous fait dire : La solution la plus simple n’a pas toujours l’air d’être la plus simple. Faire des compromis est un challenge intellectuel.

Tout d’abord, nous n’avons pas utilisé les codemods de la communauté. Bien qu’ils traitent une partie du problème, leur compréhension et leur extension auraient pris plus de temps qu’une réécriture. Nous avons décidé d’écrire nos propres codemods, et d’en écrire le moins possible. Pourquoi ? Parce que cela demande un investissement conséquent pour s’assurer que seul le code à modifier est modifié. Nous avons écrit des tests unitaires pour vérifier que le code n’est pas modifié, mais cela ne couvre que les cas que nous avons identifié. De plus, ils ne testent pas le comportement lorsque les codemods sont appliqués successivement sur un même fichier : des dépendances temporelles peuvent se produire.

Ensuite, nous avons choisi à de nombreuses reprises de migrer manuellement le code. Cela correspond à deux cas distincts : le code CJS est complexe à migrer en ESM, ou le cas est très peu présent. Nous préférons de loin développer des codemods et nous avons acquis de l’expérience, mais comme expliqué ci-dessus, nous avois choisi d’en écrire le moins possible.

Et pour finir, nous avons travaillé sur plusieurs branches/PR CJS et sur une seule branche/PR ESM. Lorsqu’une fonctionnalité CJS est difficile à migrer en ESM, on la remplace par une autre fonctionnalité CJS, elle-même plus facile à migrer, couverte par les tests et mergeable de suite. Ces modifications ont été faites par codemods (CJS → CJS) et manuellement.

Le résultat final de toutes ces contraintes est un état d’esprit que nous avons appelé “codemodception”. Lorsque nous identifions une syntaxe CJS non traitée, nous pensons à la manière la plus efficace de le faire entrer dans des cas déjà traités. Cela demande une bonne connaissance de la syntaxe CJS et ESM, de mémoriser les codemods et leur enchaînement.

Deux choix d’implémentation de la codebase

Nous avons conservé les fonctionnalités existantes d’import/export lorsque cela était possible. Dans deux cas exposés ci-dessous, nous avons fait des choix structurants d’implémentation, après avoir consulté toutes les équipes et validé la solution ensemble.

Les exports nommés

Les exports nommés ont des avantages, et nous trouvons important celui de l’amélioration de la maintenabilité du code : permettre l’import sélectif des composants d’un module. En l’absence de standards sur ce point, le codebase CJS contenait des exports nommés et des exports anonymes.

Nous avons proposé aux équipes de choisir :

garder la situation existante : permettre les exports nommés et anonymes ;
utiliser uniquement des exports nommés, en transformant les exports anonymes via des codemods.

La solution n°2, la suppression des exports anonymes, a été choisie. Elle comporte tout de même un inconvénient : si un fichier n’exporte qu’un seul composant, le développeur est obligé de lui trouver un nom, alors que le nom du fichier contient déjà toute l’information nécessaire.

Cette décision aurait pu être prise indépendamment de la migration ESM, mais la prendre de suite nous permettait de ne pas écrire de codemod ESM d’export/export anonymes, dont la syntaxe est complexe.

Nous l’avons mise en œuvre en CJS avec un codemod, partant du principe que le nom de l’import anonyme existant était celui du fichier, transposé de snake-case en PascalCase. C’est un usage que nous avions constaté dans la plupart des fichiers, mais il y a bien eu des exceptions, que nous avons corrigées manuellement.

La PR a ainsi pu être envoyée en production au plus tôt

Les tests et l’injection de dépendance

Lorsque l’API démarrait enfin, et que les tests manuels et de bout-en-bout passaient, nous avons entamé la migration des tests automatisés API. Le message qui allait hanter les jours suivants apparut très vite : ES Modules cannot be stubbed.

Il provient de la librairie de test SinonJs, dans les tests unitaires, lorsque dans la section “Given” du test, nous remplaçons un composant importé par une doublure de test. Pour faire court, les exports CJS sont mutables alors que les exports ESM sont immutables (pour être précis, on parle de live bindings. La conséquence : tous les tests qui substituent une doublure de tests à un composant importé ne sont plus valables en ESM.

Après quelques jours à explorer les librairies de doublure, nous nous sommes rendus à l’évidence : le problème n’est pas ESM, mais le fait que nous n’avons pas injecté les dépendances à plusieurs endroits dans l’API. Si nous l’avions fait, au lieu de substituer une doublure de test dans un import, nous aurions injecté dans le composant à tester la doublure de test (voir cet exemple).

Nous avons longuement réfléchi à la solution :

écrire un codemod qui injecterait les dépendances ;
injecter manuellement les dépendances ;
écrire un codemod qui encapsulerait les exports dans un objet, contournant ainsi le problème en rendant mutables les exports.

Nous avons fini par conclure que l’injection de dépendances, bien que plus verbeuse, était souhaitable. Elle rend explicite les dépendances d’un module, et rend les tests plus compréhensibles. Il n’est plus nécessaire de connaître le pattern proxy et son implémentation en Javascript pour comprendre comment fonctionnent les tests.

Il est apparu assez rapidement qu’injecter les dépendances via un codemod était complexe, et comme la migration avait du retard, nous avons préféré une solution manuelle dont le temps pouvait être prévu à une solution automatisée dont le temps était difficilement prévisible. Nous avons recensé le volume de fichiers à modifier en modifiant le code source de SinonJs pour qu’il mentionne le nom du module : pour chaque composant d’un module utilisant un composant importé, on ajoute la dépendance en tant que paramètre du composant à tester (on utilise une valeur par défaut), et on modifie le test pour injecter la doublure au lieu du composant. Cela donnait un total de 500 fichiers.

Nous avons décidé de demander de l’aide aux autres équipes, sur base du volontariat, pour effectuer ces corrections manuelles en CJS. Durant deux après-midi, après un exposé du principe, chaque groupe de quelques personnes injectait manuellement les dépendances sur un périmètre défini.

En approchant de la production

Après quelques semaines de développement, il est devenu clair que le sujet était bien plus complexe que nous ne l’imaginions. Même une fois que tous les tests automatisés passaient, des comportements imprévus pouvaient apparaître en production. Nous avons alors décidé de demander de l’aide à l’équipe en charge à mitiger les risques liés au changement, l’équipe captains. Une seule séance de brainstorming de deux heures a permis de trouver une stratégie pour sécuriser ce changement. Je vous l’expose ici.

Le suivi et la motivation

L’état et la vitesse d’avancement de la migration n’était pas très visible, aussi l’équipe captains a affiché en dynamique l’état des tests automatisés sur Are we ESM yet ?. C’est une Github page qui interroge la CI via une API : simple et efficace. Elle rend le travail et les difficultés visibles à tous.

Sécuriser le déploiement

Pour vérifier le comportement d’ESM, la production était le meilleur endroit. Le tout était de limiter l’impact qu’un problème éventuel aurait pu avoir si cela se produisait.

Nous avons listé des scénarios que nous avons priorisés par ordre d’importance décroissant :

les utilisateurs internes de Pix, dans l’interface d’administration ;
les utilisateurs externes de Pix, dans des usages non critiques ;
les utilisateurs externes de Pix, dans des usages critiques, à savoir le passage de certification.

Ensuite, nous avons réfléchi à la manière d’utiliser ESM sur une fraction du traffic API dans ces scénarios.

Nous avons fini par trouver une implémentation satisfaisante de ce qui est connu sous le nom de canary release : deux instances d’APi tournent simultanément : l’une en CJS, l’autre en ESM. On paramètre les front-end pour qu’ils envoient progressivement une partie des requêtes sur la version ESM.

Un tableau de suivi Steampipe donne une vue d’ensemble de la situation.

Voilà un exemple à mi-chemin de l’expérimentation : les front-end utilisent ESM pour une requête sur deux, sauf l’application principale. Les traitements asynchrones (workers) utilisent déjà uniquement la version ESM.

Happy end

Le 1er juin 2023, 3 mois après avoir donné le coup d’envoi, toute la production tourne en ESM !! Le changement a été un non-événement.

And finally, monsieur, a wafer-thin mint

Le code

Voilà la pull request principale :

+35/-40 k fichiers
132 commits
les codemods.

Canary release

Le canary release a été implémenté avec ningx depuis les serveurs front-end.

Il était paramétrable dynamiquement via des scripts bash, en modifiant les variables d’environnement du PaaS via le CLI.

Il a complexifié le workflow de déploiement, en ajoutant des interventions manuelles à un workflow sur lequel les PO étaient autonomes.

Nous avons limité la complexité de coordination entre PO et développeurs en modifiant le workflow de déploiement Slack, pour y mentionner les actions manuelles.

Coût de coordination et complexité

Un problème qui ne peut être résolu seul demande de la coordination, qui a un coût.

In tasks that can be partitioned but which require communication among the subtasks, the effort of communication must be added to the amount of work to be done. The added burden of communication is made up of two parts, training and intercommunication. Each worker must be trained in the technology, the goals of the effort, the overall strategy, and the plan of work. This training cannot be partitioned, so this part of the added effort varies linearly with the number of workers. Intercommunication is worse. If each part of the task must be separately coordinated with each other part, the effort increases as n(n-1)/2. Three workers require three times as much pairwise intercommunication as two; four require six times as much as two.

If, moreover, there need to be conferences among three, four, etc., workers to resolve things jointly, matters get worse yet. The added effort of communicating may fully counteract the division of the original task

in Fred Brooks, The mythical man-month, Chapter “The Man-month”, page 18

Estimation

L’informatique n’est plus si jeune, les développeurs non plus, et nous sommes toujours obstinément optimistes. Le mystère reste entier..

All programmers are optimists.

Perhaps this modern sorcery especially attracts those who believe in happy endings and fairy godmothers. Perhaps the hundreds of nitty frustrations drive away all but those who habitually focus on the end goal. Perhaps it is merely that computers are young, programmers are younger, and the young are always optimists.

But however the selection process works, the result is indisputable: ‘This time it will surely run,’’ or “I just found the last bug.”. So the first false assumption that underlies the scheduling of systems programming is that all will go well, i.e., that each task will take only as long as it “ought” to take.

in Fred Brooks, The mythical man-month, Chapter “Optimism”, page 15

Migrer de CommonJS vers ECMAScript Modules #1

2023-08-25T07:49:00+00:00

Cet article partage avec vous deux mois d’efforts (et de doutes, aussi) pour migrer une base de code NodeJS de 400 kLoC. Spoiler : nous y sommes arrivés !

Vous y trouverez de l’histoire, de la syntaxe, des considérations techniques et organisationnelles, de l’outillage et du monitoring : il y en a pour tous les goûts.

Voilà, en entrée, le résumé du challenge à accomplir :

comprendre ce qu’est un système de module ;
se souvenir de ce qu’il en est en Javascript ;
savoir si ESM peut t’être utile ;
comprendre la syntaxe ESM ;
comment modifier le code (la syntaxe est un pré-requis).

Si vous êtes déjà familier avec tout ça, attendez plutôt la sortie de l’article en plat principal, à savoir comment nous avons mené la migration.

Une histoire de modules

Dans la plupart des langages de programmation (C, Java, JavaScript…), le fichier de code (source) est un élément important. Il est implémenté dans le système de fichiers de l’OS, par un fichier texte. Il y a quelque chose de fondamentalement réconfortant à cela. Utiliser un langage qui stocke le code source dans des fichiers aux noms cryptiques et au contenu binaire, c’est une perte d’autonomie.

Pourquoi ? Parce que ranger des fichiers dans des dossiers est une métaphore puissante : elle permet de regrouper ce qui se ressemble en traçant des frontières. C’est la même chose qui se passe au niveau en-dessous lorsqu’on crée des fonctions.

Aside from the computer itself, the routine is the single greatest invention in computer science. (…) Create a routine to hide information so that you won’t need to think about it. (…) Without the abstractive power of routines, complex programs would be impossible to manage intellectually.

in Steve McConnell, Code Complete - Chapter 7 : High-quality routine

En théorie informatique, ce genre de découpage (de décomposition) porte le nom de module, un terme déjà utilisé en construction pour exprimer la capacité à bâtir un système en assemblant des composants. La réutilisation de code, sous forme de librairie, en fait partie.

Les modules côté Javascript

La notion de module est assez large en Javascript : on désigne parfois la même chose par librairie, package, script, balise <script>, module, fichier … Revenons en arrière pour mieux comprendre.

Tout débute dans un navigateur

Au début de Javascript (1995), il n’y avait pas de système de module natif : tout le code était contenu dans la balise <script></script>. Pour que les “pages web” (contenu statique) puissent devenir des applications web (contenu dynamique), des fonctionnalités génériques (ex : appeler une API REST) sont distribuées sous forme de librairies Js. Elles pouvaient être importées depuis un fichier via l’attribut src de la balise script, par exemple <script src="my-library.js">. Le code de l’application (composant) pouvait aussi être modularisé ainsi.

Un petit tour côté serveur

Le passage de Javascript côté serveur (2009) changea l’approche.

Dans NodeJS, les libraires (packages) :

déclarent leur interface (API) avec le mot-clef module.exports (notion de module) ;
sont enregistrées par l’application dans le fichier package.json ;
sont installées par npm dans le fichier node_modules (encore le module) ;
sont importées avec le mot-clef require.

Les composants internes de l’application utilisent les mêmes mot-clefs require et module.exports. Il n’y a pas de différence visible entre l’import d’une libraire et d’un composant, à part le fait qu’une libraire est mentionnée par son nom et le composant par son chemin.

// library
const { pick } = require('lodash');
// component
const { controller } = require('./lib/application/certification/certification-controller');

Happy end ?

Maintenant que nous sommes familiers avec le concept de modules dans Javascript, nous arrivons enfin à ESM.

Actuellement, il y a plusieurs systèmes de modules en Javascript : AMD, CJS, ESM, UMD.

Le système CommonJs (en abrégé CJS) est le plus utilisé côté serveur, car :

CJS était fourni avec NodeJs ;
il n’existait pas de système de module natif, partagé par les navigateurs et NodeJs.

En 2015, le comité chargé du langage met un terme à cette situation, à savoir :

le comité TC39 (chargé de Javascript)
de l’organisation de normalisation ECMA
publie dans la version 2015
la spécification ECMAScript module, en abrégé ESM.

Cinq ans plus tard, en 2020, les navigateurs web et NodeJs (v12) l’ont implémenté de manière stable.

Pourquoi migrer en ESM ?

La base de code Pix, créée en 2016, utilise le format CJS. Si le format qu’elle utilise est éprouvé, pourquoi migrer pour un système qui n’a que trois ans de support officiel ? La décision tient à une raison : faciliter le passage à Typescript.

Si vous n’êtes pas dans cette situation et cherchez ce que ESM pourrait vous apporter, nous conseillons cet article, écrit par un membre de l’équipe qui a implémenté ESM dans NodeJS

CJS vs ESM is not a war, rather a topic to talk even more about, once constraints and respective features are clear, as opposite of just taking a side out of habits, or effort needed, to move on (to ESM).

Voilà tout de même les avantages d’expérience de développement après quelques mois d’utilisation :

mode strict actif ;
autocomplétion des imports par les IDE ;
vérification statique des imports, absente en CJS;
syntaxe moins permissive, qui améliore la lisibilité du code.

Pour illustrer la syntaxe, voilà une version valide en CJS.

const Ham = require('./ham').Ham;
const carrot = require('./garden').digCarrot();
const potatoes = require('./field').harvestPotatoes(require('./tools').basket);

/* some code */

if( some_condition()){
   require('./orchard').spray();
}

const omelette = cook(require('./egg'));

/* some code */

module.exports = {
  ham: new Ham(),
  someFunction : require('./spam').someFunction
}

Et voilà la version équivalente en ESM :

les imports sont visibles en haut du fichier ;
l’interface (= les exports) est claire.

import { Ham } from './Ham.js';
import egg from './egg.js';
import { someFunction } from './spam.js';
import { digCarrot } from './garden.js';
import { spray } from './orchard.js';
import { harvestPotatoes } from './field';
import { basket } from './tools';

const potatoes = digPotatoes(basket);
const carrot = digCarrot();

/* some code */

if( some_condition() ){
   spray();
}

const omelette = cook(egg);

/* some code */

const ham = new Ham();

export {
   ham,
   someFunction
}

Un peu de syntaxe

Pour que vous puissiez suivre la démarche de migration, il est important d’avoir les bases de la syntaxe ESM. Partons du principe que vous connaissez la syntaxe CJS.

Tous les composants (nombre, objets, fonctions, classes) peuvent être exposés dans les modules ESM. Ils portent un nom d’export. Celui-ci peut être remplacé par un autre lors de l’import dans un autre module. Il est aussi possible de supprimer leur nom à l’export, pour le remplacer par le nom default. Il ne s’agit pas à proprement parler d’export anonyme, simplement d’un export nommé default, aussi appelé export par défaut.

Les imports et exports doivent être à la racine du fichier (top-level). Ils sont interdits dans une structure de contrôle ou une fonction.

Les imports doivent figurer en début de fichier. Leur syntaxe est la suivante, du plus simple au plus complexe :

import from './module.js' : si l’on ne veut pas récupérer d’import, uniquement exécuter du code
import module from './module.js' : pour récupérer l’export par défaut et le nommer module
import { foo, bar } from './module.js' : pour récupérer certains exports nommés
import { foo , bar as baz } from './module.js' : même chose, en les renommant
import * as module from './module.js' : pour récupérer tous les exports nommés dans un objet

La syntaxe des exports est la suivante, du plus simple au plus complexe :

export foo; : exporter un objet, peut être invoqué plusieurs fois
export default foo : export par défaut (l’objet exporté perd son nom foo pour prendre celui de default)
export { foo, bar } : export de plusieurs objets
export { foo , bar as baz } : même chose, avec renommage
export { foo, bar } from './module.js : vous avez bien lu, on importe les exports nommés et on les exporte (ré-export)
export * from './module.js : même chose, pour sélectionner tous les exports nommés

Si vous êtes curieux de connaître l’implémentation de ESM, cet article est une excellente introduction sur les modules en général et ESM en particulier.

Modifier le code

Une solution simple

Le passage de CJS à ESM concerne tous les fichiers avec au moins un import/export, autrement dit tous les fichiers. Étant donné la volumétrie, une modification de code manuelle est exclue. Quelles sont les solutions pour modifier du code ?

Si les modifications sont mineures, par exemple supprimer le s de exports, les outils quotidiens du développeur suffisent : soit IDE (Find/Replace avec expressions régulières), soit un script bash utilisant find, grep, sed. Si l’on veut éviter d’écrire du bash, une solution est de modifier le fichier avec NodeJs, en utilisant la librairie I/O standard. Les lignes de code sont des chaînes de caractère comme les autres, après tout.

L’affaire se complique si la transformation modifie la syntaxe et pas seulement un mot-clef.

// CJS
const { Ham } = require('./ham');
// ESM
import { Ham } from './Ham.js';

Car, même si transformer const { <TOKEN> } en import { <TOKEN } semble simple, il faut aussi éviter les effets de bord sur des expressions qui y ressemblent, mais qui n’en sont pas, par exemple les imports nommés non sélectifs.

// CJS
const egg = require('./egg.js');
// ESM
import egg from './egg.js';

Et que dire si la transformation est multi-lignes ?

// CJS
const ham  = new (require('./ham')).Ham();
// ESM
import { Ham } from './Ham.js';
const ham = new Ham();

Et encore, ici les lignes sont consécutives, alors qu’il est indispensable en réalité de pouvoir modifier les exports, qui peuvent être n’importe où dans le fichier.

Bref, il nous fallait une autre solution. Nous avons cherché comment d’autres avaient fait, car nous ne sommes pas les seuls à vouloir migrer en ESM. Nous avons constaté que leurs solutions (celle-ci ou celle-là) ne fonctionnaient pas sur notre codebase, mais elles nous ont mis sur la voie.

Entrons dans le monde de l’AST, dirigé par les codemods.

Une solution complexe et puissante : les codemods

L’AST

Les outils dédiés à la modification de code sont appelés “code modificators” (codemods en abrégé). Ils s’appuient sur une représentation du fichier plus riche qu’une suite de chaînes de caractères, pour que nous puissions, par exemple :

sélectionner un import nommé sélectif CJS ;
mais pas un import par défaut, ou un import nommé global ;
et le remplacer par un autre import nommé, cette fois-ci en ESM, ainsi qu’une déclaration de variable.

Pour cela, ils vont effectuer un travail similaire à l’interpréteur NodeJS :

un lexer qui transforme une chaîne de caractères en “mots” (tokens)
un parser qui transforme cette suite de tokens en éléments du langage, organisés en arbre.

Cet arbre s’appelle un “Abstract Syntax Tree” (AST).

Sélectionner un élément à modifier

Voyons ce que donne le fichier contenant un import CJS dans un constructeur d’AST.

const egg = require('./egg.js');

AST

 {
    "type": "VariableDeclaration",
    "declarations": [
      {
        "type": "VariableDeclarator",
        "id": {
          "type": "Identifier",
          "name": "egg"
        },
        "init": {
          "type": "CallExpression",
          "callee": {
            "type": "Identifier",
            "name": "require"
          },
          "arguments": [
            {
              "type": "Literal",
              "value": "./egg.js",
              "raw": "'./egg.js'"
            }
          ]
        }
      }
    ],
    "kind": "const"
    }

Cet “Abstract Syntax Tree” (AST) peut être interrogé, tout comme on interroge le DOM avec Xpath: la requête s’appelle un sélecteur.

Ici, nous voulons récupérer les imports nommés globaux, le sélecteur qui nous intéresse est un nœud :

avec affectation à une variable (sans invocation de code), donc de type VariableDeclaration;
sans déstructuration, donc avec un descendant de type Identifier;
d’import CJS, donc avec un descendant de type CallExpression et de name require.

Les autres syntaxes d’import (ex : import sélectif) ne sont pas inclus pour la lisibilité, mais il faut tous les comparer pour trouver leurs points communs et leurs différences, pour éviter les faux :

positifs : sélectionner un import indésirable ;
négatifs : ne pas sélectionner un import désiré.

Modifier l’élément sélectionné

Une fois le sélecteur écrit, il faut réécrire le code. Nous avons utilisé un outil JS, jscodeshift, comme exemple ci-dessous. Dans Jscodeshift, le code ne peut pas être modifié “sur place” via des mutations, il est remplacé par du code que nous allons générer. La librairie sous-jacente, recast, fournit des constructeurs pour les éléments du langage.

Pour générer le code ESM suivant

import egg from './egg.js';

La syntaxe est

j.variableDeclaration("const", [j.variableDeclarator(
    j.identifier("egg"),
    j.callExpression(j.identifier("import"), [j.literal("./egg.js")])
)]);

Notez que certains paramètres de fonction doivent être récupérés dans l’AST précédent :

le nom de la constante egg;
le chemin du fichier ./egg.js.

Si on assemble tous les éléments, le codemod ressemble à ça.

Un périmètre de travail parfois limité

Jscodeshift suit les étapes suivantes :

lire (récursivement) tous les fichiers d’un répertoire ;
sur chaque fichier :
- générer l’AST ;
- appliquer les sélecteurs ;
- pour chaque sélection qui matche, appeler le constructeur de code ;
- assembler le code obtenu et réécrire le fichier d’origine.

Le plus grand périmètre de travail est le fichier, tout comme dans eslint. Même si Jscodeshift traite les fichiers en parallèle, il n’est pas possible d’accéder à l’AST d’un autre fichier depuis l’AST courant. La conséquence : il n’est pas possible de faire une modification qui impacte deux fichiers.

Si les modifications de code ne concernent que l’intérieur d’une fonction, cela ne pose pas de problème. Dans les cas d’ESM, qui par définition traite des interfaces entre fichiers, cela a été une sérieuse limitation.

Se faire aider

Tests automatisés

Il n’est pas possible, à part avec une profonde expérience du langage et des AST, de se représenter tous les cas possibles. Il est donc à peu près exclu de garantir que tous les cas seront traités et qu’ils le soient correctement.

Une suite de tests automatisés est donc indispensable pour :

d’une part, documenter les cas traités ;
détecter les cas qui ne sont pas bien traités ;
éviter les régressions, à savoir modifier du code qui ne doit pas être modifié.

Jscodeshift embarque un framework de test dédié et les cas de test sont lisibles. Ils contiennent le code en entrée (given) et celui attendu en sortie (then).

// input.js
const datasource = require('./datasource.js');
// output.js
import * as datasource from './datasource.js';

Lint

Après l’exécution du codemod, si l’exécution du fichier retourne une erreur, c’est que le codemod est incorrect. Si l’on inspecte le contenu du fichier, on peut constater l’erreur et corriger le codemod. Mais parfois, on a besoin d’une vue d’ensemble pour modifier le codemod pour s’assurer que tous les imports référencent un fichier existant ?

C’est là que le plugin eslint-plugin-import peut faire gagner du temps, par exemple en remontant tous les cas d’imports non résolus avec la règle no-unresolved.

Il peut aussi y avoir beaucoup de violations.

Pour y voir plus clair, vous pouvez :

utiliser le package eslint-nibble qui groupe par règle ;
exécuter une seule règle sur tous les fichiers avec l’option --rule de eslint : npx eslint --rule eslint-plugin-import/no-unresolved ./lib
aussi utiliser des expressions régulières avec sed pour extraire la liste des fichiers à modifier.

Heuristique d’automatisation

Maintenant que vous savez qu’il est possible de modifier du code complexe, va-t-on écrire des codemods pour gérer tous les cas possibles ? Sinon, quels sont les codemods qu’il faut absolument écrire ? Voilà quelques règles, inspirées de la matrice d’automatisation.

Cas 1 - Evidence : il faut automatiser

Si une fonctionnalité CJS est reprise telle quelle dans ESM et qu’elle est utilisée dans la plupart de la codebase, écrire le codemod. Il pourrait être réalisé en script bash, mais le framework de test de jscodeshift évite les erreurs.

C’est le cas de l’import nommé.

// CJS
const egg = require('./egg.js');
// ESM
import egg from './egg.js';

Cas 2 - Questionnement : faut-il automatiser ?

Si une fonctionnalité CJS n’est pas reprise dans ESM et est facilement simulable (ex : avec plusieurs instructions au lieu d’une), alors se demander si elle est utilisée dans la plupart de la codebase.

Si c’est le cas, écrire le codemod. Si ce n’est pas le cas, modifier les fichiers manuellement.

C’est le cas CJS de l’import + invocation dans la même instruction, remplacée par un import nommé avec assignation + invocation dans une autre instruction en ESM.

// CJS
const ham  = new (require('./ham')).Ham();
// ESM
import { Ham } from './Ham.js';
const ham = new Ham();

Cas 3 - Impasse : il est impossible d’automatiser

Si une fonctionnalité CJS n’est pas reprise dans ESM et qu’elle n’est pas simulable facilement, la seule solution est de modifier le fichier manuellement.

C’est le cas des exports immuables en ESM. Tous les tests CJS qui substituent une doublure de test à la volée ne sont plus valables : seule l’injection des dépendances permet de résoudre le problème. Bien sûr, il est possible en théorie d’écrire un codemod qui injecterait les dépendances : à vous de voir le coût.

Conclusion

Nous avons vu les avantages d’ESM et qu’il était possible d’automatiser la migration du code.

Si vous envisagez une migration, le plus important est de garder l’heuristique d’automatisation en tête et de vous concentrer sur le cas 2, où l’automatisation peut être envisagée, mais pas systématique. C’est ce cas qui demande le plus de recul, les deux autres cas étant évidents.

Il est en effet possible de :

sous-estimer le coût de développement d’un codemod ;
mais aussi de sous-estimer le caractère répétitif et frustrant de modifier des centaines de fichiers manuellement.

Nous vous conseillons de suivre votre intuition en se fixant des limites pour éviter le biais d’investissement, puis d’apprendre en essayant. Si tout ne se déroule pas comme prévu, s’autoriser à revenir en arrière.

Par exemple, si l’on estime que :

la modification manuelle de fichier prend 1 jour ;
le codemod prend 2 jours ;
et qu’au bout d’un jour de correction manuelle, on comprend qu’il reste en fait 3 jours.

Alors, on peut supprimer les modifications manuelles de fichiers et développer un codemod. Bien sûr, le développement prendra peut-être plus de temps, mais parfois les modifications manuelles peuvent saper l’énergie de l’équipe. Tout est question de contexte.

Bonus

ESM apporte aussi les modifications suivantes :

remplacement des pseudo-variables __dirname et __filename par la fonction fileURLToPath de la librairie url ;
l’extension de fichier devient obligatoire dans l’import, exemple from './egg.js' ;
la lecture de fichier JSON demande une clause supplémentaire assert { type: 'json' }, exemple import packageJSON from '../package.json' assert { type: 'json' };.

Voilà quelques références pour démarrer les codemods :

un tutoriel JScodeshift ;
une sandbox pour écrire des codemods (activez l’option Transform avec recast);
la définition des constructeurs pour générer le code.

Tester unitairement les composants sous Embroider

2023-05-22T10:27:00+00:00

Nous avons récemment migré nos applications Ember.js sous Embroider, le nouveau builder pour Ember.js. Embroider offre une fonctionnalité intéressante appelée “route splitting”, qui permet d’envoyer uniquement les fichiers JavaScript nécessaires pour une ou un groupe de routes. Cela réduit la taille du JavaScript téléchargé par les utilisateurs, à condition que le découpage des routes soit bien pensé.

Cependant, l’activation de cette fonctionnalité nécessite plusieurs options, dont staticComponents, qui a pour effet de résoudre tous les composants nécessaires et de les inclure dans la construction finale.

En activant cette option et en suivant le guide de migration pour les composants helpers, les tests unitaires de nos composants ne passaient plus.

Le défi des tests unitaires avec Embroider et les composants Glimmer

Lors de la migration vers les composants Glimmer, nous nous étions rendu compte que Glimmer ne supportait plus nativement les tests unitaires, nous avions utilisé une parade proposée par la communauté sur le Discord d’Ember, que vous pouvez retrouver en détail sur cet article et dont voici la solution :

import { getContext } from '@ember/test-helpers';
import GlimmerComponentManager from '@glimmer/component/-private/ember-component-manager';

export default function createComponent(lookupPath, named = {}) {
 const { owner } = getContext();
 const { class: componentClass } = owner.factoryFor(lookupPath);
 const componentManager = new GlimmerComponentManager(owner);
 return componentManager.createComponent(componentClass, { named });
}

Qui permet dans un test unitaire de faire :

const component = createComponent('component:component-name', { argument });

Cette solution est désormais obsolète, car avec Embroider et l’option staticComponents la méthode factoryFor ne retourne rien. Cela parait cohérent avec la volonté d’Embroider qui souhaite créer des builds statiques analysables.

Une nouvelle solution avec importSync de @embroider/macros

La nouvelle solution que nous utilisons se sert d’importSync proposé par @embroider/macros, qui permet à Embroider de signaler l’existence d’un module et de l’inclure dans le build.

Voici donc le code avec la modification :

import { getContext } from '@ember/test-helpers';
import GlimmerComponentManager from '@glimmer/component/-private/ember-component-manager';
import { importSync } from '@embroider/macros';

export default function createComponent(lookupPath, named = {}) {
 const { owner } = getContext();
 const componentClass = importSync(`../../components/${lookupPath}`).default;
 const componentManager = new GlimmerComponentManager(owner);
 return componentManager.createComponent(componentClass, { named });
}

Et son usage

const component = createComponent('component-name', { argument });

Grâce à cette simple modification, nous pouvons à nouveau continuer de tester unitairement nos composants Glimmer et commencer à utiliser les fonctionnalités proposées par Embroider.

Une montée de version PostgreSQL en PaaS surprenante

2023-04-21T12:27:00+00:00

TL;DR

Les Database-as-a-service, c’est pratique pour ne pas avoir trop d’expertise en interne. Mais parfois, on a quand même des surprises.

Si vous :

êtes hébergés par Scalingo;
utilisez les addons PostgreSQL;
souhaitez passer de la version 13.7 à 13.9.

Alors prévoyez un créneau de maintenance pour recréer certains index.

Pourquoi ?

parce qu’une mise à jour d’addon inclut, en plus de l’application “base de données”, potentiellement, des mises à jour de l’OS ;
un lien existe entre l’OS et les index qui utilisent une collation par défaut.

Le décor

Pix utilise un PaaS, Scalingo, pour l’hébergement de la plupart ses applications. Il fournit un service de base de données sous la forme d’addon, dont la gestion (sauvegarde, PITR, réplication, maintenance) est garantie. Nous utilisons ce service, car notre utilisation ne justifie pas la formation d’une équipe dédiée en interne.

Nous gardons toutefois la main sur le déclenchement des montées de version, car celles-ci requièrent des interruptions de service dans certains cas.

If your database uses a business plan, we are able to achieve zero-downtime upgrade of minor version. In the case of major version upgrade, we need to completely stop the nodes, hence we can’t achieve zero-downtime.

Nous effectuons préalablement des tests automatisés:

de non-régression sur la version de BDD en local et dans la CI;
de performance sur l’environnement cible Scalingo.

A la sortie de PostgreSQL 14 sur Scalingo en janvier, nous avons déroulé notre scénario habituel.

Le drame

Le lendemain de la mise à jour en production, le monitoring remonte des erreurs 500 sur plusieurs routes API. Les erreurs n’étant pas nombreuses et limitées à l’authentification, nous analysons les logs de manière détaillée.. et nous rendons compte qu’il y a deux comptes actifs possédant le même email. Cela nous surprend, puisque nous nous sommes assurés que cela n’arriverait pas, grâce au mécanisme de contrainte d’unicité en base de données qui exclut cette possibilité.

Fait troublant, les logs mentionnent aussi des requêtes de mise à jour de données rejetées pour cause de violations de contraintes.

Une première requête nous rassure.

SELECT id, email FROM users WHERE email = 'john.doe@example.net';
id  | email
----------
1   | john.doe@example.net
(1 row)

Mais une deuxième nous inquiète.

SELECT id, email FROM users WHERE id IN (1,666);
id  | email
----------
1   | john.doe@example.net
666 | john.doe@example.net
(2 rows)

Force est de constater qu’il y a plusieurs enregistrements :

avec des identifiants différents ;
et un champ email identique.

Il existe pourtant une contrainte UNIQUE.

\d users
Indexes:
"users_email_unique" UNIQUE CONSTRAINT, btree (email)

Nous ne savons pas pourquoi cela se produit, mais nous avons accepté le fait qu’il y ait des doublons. Comme nous n’arrivons pas à récupérer tous les enregistrements en doublons (probablement une optimisation basée sur la contrainte d’unicité), nous revenons à une détection bas-niveau avec un hash sur le champ en question.

SELECT md5(email) AS hash,
COUNT(*) FROM users
HAVING COUNT(*) > 1;

hash          | count(*)
------------------------------------
40c05(..)     | 2

L’enquête

Nous sommes parti d’un seul indice : nous avions mis à jour la base de données la veille. Notre hypothèse est que la mise à jour de PostgreSQL ne concerne à priori que la base de donnée, donc nous parcourons la documentation. Et tombons sur ce paragraphe

When an instance needs to be upgraded to a new glibc release, for example to upgrade the operating system, then after the upgrade all indexes involving columns of type text, varchar, char, and citext should be reindexed before the instance is put into production.

Il existerait donc une dépendance entre la montée de version d’une librairie de l’OS (glibc) et le tri dans la BDD, qui pourrait expliquer ce comportement, et pour laquelle il existe une solution (la reconstruction des index).

Il n’y a à priori aucun lien entre une montée de version de la BDD et de l’OS qui la supporte, mais à bien y réfléchir, pourquoi pas ? Scalingo met à disposition pour les conteneurs un environnement nommé stack, qui embarque l’OS. Le service de base de données n’utilise pas cette notion de stack, pour la bonne raison que c’est un service managé. Une montée de version de l’addon peut donc inclure des mises à jour d’OS.

Inspectons l’image docker dans ses versions successives sur le repository Scalingo: on voit que glibc a été mise à jour lors du passage de la version docker de 13.7 à 13.9.

docker run --rm -it scalingo/postgresql:13.7.0-1 ldd --version
ldd (Debian GLIBC 2.24-11+deb9u4) 2.24

docker run --rm -it scalingo/postgresql:13.9.0-1 ldd --version
ldd (Debian GLIBC 2.31-13+deb11u5) 2.31

Cette version est explicitement mentionnée comme embarquant des mises à jours de locales, lesquelles sont impliquées dans le tri exploité par les index, eux-mêmes utilisés pour implémenter la contrainte d’unicité. CQFD.

For Postgres databases (..), it means that certain strings might sort differently after this upgrade. A critical consequence is that indexes that depend on such collations must be rebuilt immediately after the > upgrade

S’en sortir

Si vous vous retrouvez dans la même situation que nous, à savoir que vous n’avez pas reconstruit les index, et que la base de données a été ouverte au traffic, voilà la solution que nous avons trouvée.

Détecter les index impactés

SELECT
   indrelid::regclass::text AS table,
   indexrelid::regclass::text AS index_name,
   pg_get_indexdef(indexrelid) AS index_source,
   collname AS collation_type
FROM
   (SELECT indexrelid, indrelid, indcollation[i] coll
    FROM pg_index, generate_subscripts(indcollation, 1) g(i)
    ) s
         JOIN pg_collation c ON coll=c.oid
WHERE collprovider IN ('d', 'c') AND collname NOT IN ('C', 'POSIX');

Source: Wiki PostgrSQL

Rechercher les données invalides

Rechercher les doublons sur les champs protégés par les contraintes uniques utilisant les index détectés ci-dessus. En effet, la reconstruction d’index unique n’est pas possible si les données sont en doublon.

SELECT md5(column) AS hash,
COUNT(*) FROM table
HAVING COUNT(*) > 1;

Déterminer quel enregistrement doit être supprimé, car créé par erreur après la montée de version. Pour cela, s’assurer qu’aucune données liée ne soit perdue.

Recréer les index

Il est temps de recréer les index, maintenant que les tables sont saines.

SELECT
   'REINDEX INDEX ' || indexrelid::regclass::text || ';'
FROM
   (SELECT indexrelid, indrelid, indcollation[i] coll
    FROM pg_index, generate_subscripts(indcollation, 1) g(i)
    ) s
         JOIN pg_collation c ON coll=c.oid
WHERE collprovider IN ('d', 'c') AND collname NOT IN ('C', 'POSIX');

Ce qui nous donne :

REINDEX INDEX users_email_unique;
REINDEX INDEX users_username_unique;

Assurez-vous de planifier un créneau de maintenance pour cela, la recréation d’index posant en général un verrou en écriture sur la table. Il existe d’autres options prenant en compte les traitements concurrents, mais dans ce cas elles ne sont probablement pas indiquées.

Passer une PK référencée du type INT en BIGINT

2022-12-14T14:59:42+00:00

TL;DR

Dans un précédent article, nous partagions comment modifier une propriété du type INT vers le type BIGINT:

si celle-ci n’était pas référencée par une autre table;
en minimisant le temps d’indisponibilité;
en modifiant les données dans une colonne temporaire de la table.

Depuis, nous avons modifié une propriété référencée, en l’occurrence par une clef étrangère. Nous avons essayé de migrer les données progressivement sur une copie de la table:

pour limiter la fragmentation;
pour ne pas modifier l’organisation des données;
en modifiant l’allocation des ressources CPU/mémoire de la migration.

Nous avons fini par comprendre que le facteur limitant était l’I/O, et que celle-ci, contrôlée par notre PaaS, ne pouvait être améliorée.

Nous avons abandonné cette piste et utilisé un créneau de maintenance d’une journée pour migrer en utilisant la solution native.

Nous avons surtout retenu de consulter le métier le plus tôt possible (ici pour se mettre d’accord sur les plages de maintenance planifiées), afin de faire les choix techniques les mieux informés.

Motivation

La motivation reste la même que sur la propriété non référencée, pour rappel:

pas d’interruption de service;
pas de dégradation des temps de réponse pendant l’ensemble des opérations.

A l’arrivée, on souhaite que ces 3 éléments soient de type BIGINT:

la propriété elle-même : id sur la table answers;
la séquence utilisée pour alimenter cette propriété : answers_id_seq;
les propriétés référençant cette propriété : clef étrangère answerId sur la table knowledge-elements.

Recherche de solution

Solution 1 : instructions natives PostgreSQL

Nous avons commencé par obtenir le temps d’exécution de la solution native sur un environnement comparable à l’environnement cible. Il servira de référence pour le temps maximal d’indisponibilité: si l’on trouve une solution avec un temps inférieur à la solution native, elle est retenue comme candidate.

La solution native se résume à ces instructions, et prend 15h.

ALTER TABLE "knowledge-elements" ALTER COLUMN "answerId" TYPE BIGINT;
ALTER TABLE "flash-assessment-results" ALTER COLUMN "answerId" TYPE BIGINT;
ALTER TABLE "answers" ALTER COLUMN "id" TYPE BIGINT;
ALTER SEQUENCE AS BIGINT;

Le temps d’exécution est partagé de manière à peu près égale entre les deux tables, et celles-ci sont successivement inaccessibles en lecture et en écriture. Ces tables étant utilisées de manière conjointe, cela donne un temps d’indisponibilité de 15 heures.

Solution 2 : migration en arrière plan

Investigation

Les données à modifier sont:

les méta-données de la table, utilisées lors de la création d’un enregistrement;
les données existantes brutes, c’est à dire les enregistrements de table.

Cependant, les données d’index doivent aussi être modifiées explicitement dans cette solution alors que ces modifications sont implicites dans les instructions natives. Nous y reviendrons en détail dans la seconde partie.

Migration des données

Migration dans la même table

Comme dans l’article précédent, le temps d’indisponibilité ne peut être réduit qu’à condition d’effectuer:

tout d’abord la plus grande partie du travail, la migration des données existantes, en tâche de fond;
et ensuite de migrer les données récentes lors d’un créneau de maintenance réduit.

Si la migration en tâche de fond est effectuée sur la même instance de base de données, ou la même table, elle peut impacter l’activité habituelle.

C’est pour cela que nous commençons par un POC, qui migre les données:

par batch;
avec un délai d’exécution;
pouvant être interrompu et relancé sans recommencer toute la migration;
avec des réglages (ex: taille de batch) modifiables en temps réel.

Devant cette complexité, qui nous expose à la corruption de données, nous choisissons d’implémenter:

la migration en NodeJs, afin de disposer de tests automatisés;
la copie des données insérées entre-temps (qui ne peut être faite que coté serveur) via des triggers PostgreSQL.

Le dispositif est le suivant:

une migration de BDD crée:
- la colonne de type BIGINT;
- la table de paramétrage;
- les triggers de copie ;
un script client migre les données existantes:
- il lit le paramétrage dans une table;
- il migre un batch de données et trace les données traitées;
- il relit le paramétrage au cas où il aurait été mis à jour;
- il traite le prochain batch là où il s’était arrêté.

Le code client a été réalisé:

en TDD, avec des tests unitaires/intégration/acceptance (700 lignes sur les 1000 de la pull-request);
en Clean Architecture (voir le use-case).

Obstacle: la fragmentation

Il y a un compromis à trouver en ce qui concerne la taille des batchs:

plus le nombre de lignes traité par batch est petit, plus l’impact est réduit sur les autres requêtes;
plus le nombre de lignes traité par batch est grand, plus l’exécution de la migration est rapide.

Lors de la migration sur la table non référencée, nous avions effectué des batchs de 1 million d’enregistrements, pour une durée moyenne de 2 minutes, en gardant une expérience utilisateur dégradée mais acceptable (pc98 de l’ordre de 100 ms => 1 s). Il est maintenant possible de baisser la taille de ces batchs à 100 000 enregistrements pour moins impacter le temps de réponse. Mais il faut prendre en compte un autre facteur: la fragmentation des données dans la table.

Lorsque PostgreSQL met à jour l’enregistrement (UPDATE answers SET id_bigint = id), il ne met pas à jour l’original, mais insère un autre enregistrement et marque le précédent comme obsolète (c’est le MVCC). De plus, l’insertion de données se fait par ensemble d’enregistrements (page) pour des questions de performance. Sans oublier que les données normalement insérées par l’application continuent d’arriver.

Ici, nous demandons la modification de tous les enregistrements de la table: PostgreSQL va progressivement réécrire sur le disque l’intégralité de la table. Il est possible qu’à la fin de cette opération, les données:

soient physiquement stockées dans un ordre différent que celui dans lequel elles ont été écrites initialement;
prennent plus de place.

Après la migration sur la table non référencée, nous avons constaté:

une densité d’enregistrements par page qui varie de 60 à 35;
sur des pages contigües, des données d’octobre 2020 côtoient des données de février 2021, puis l’on repasse à octobre 2020.

Cela n’est pas forcément un problème:

si vos index sont suffisamment sélectifs;
si vos données ne sont pas interrogées chronologiquement.

Dans notre cas, la perspective d’obtenir des résultats encore plus accentués en diminuant la taille des batchs ne nous convenait pas.

Migration des données dans une table séparée

Exploration

Prenons du recul sur le but: migrer les données en BIGINT sans modifier l’activité sur la table cible.

Comme application ne fait qu’insérer des données dans la table, nous décidons:

d’isoler les données existantes dans une nouvelle table;
de les transformer;
dans le créneau de maintenance, de rajouter les données insérées au fil de l’eau;
de remplacer la table d’origine par la nouvelle table.

Lorsque se pose la question d’alimentation de la nouvelle table, nous nous rendons compte qu’il est possible de transformer les données en même temps. Si la propriété de la nouvelle table est de type BIGINT, PostgreSQL effectue une coercition de type (cast) sur la donnée INT.

CREATE TABLE "answers_bigint" (id BIGINT,..);
INSERT INTO "answers_bigint" (id, ..)
SELECT id, ... FROM answers;

Nous avons aussi envisagé deux variantes:

pour décharger la BDD de la lecture des données, il est possible d’importer un dump;
pour insérer les données dans un ordre particulier, en délégant le tri à un processus hors BDD.

Nous sommes restés sur la solution INSERT INTO :

l’impact sur la BDD était négligeable;
elle est la plus rapide;
nous n’étions pas sûr du tri qui nous serait le plus bénéfique;
elle était la plus simple.

Implémentation

Comme on travaille avec deux tables, pour garder l’intégrité des données, nous choisissons d’implémenter:

la migration en NodeJs, afin de disposer de tests automatisés;
la copie des données insérées entre-temps (qui ne peut être faite que coté serveur) via des triggers PostgreSQL.

Le tout se compose de 6 pull-requests, afin de faciliter les revues:

partie 1: création des tables cibles;
partie 2: copie des données;
partie 3: création des index;
partie 4: recopie des données au fil de l’eau;
partie 5: récupération des données non recopiés au fil de l’eau;
partie 6: exposition des tables cibles.

Création des index

Dans l’implémentation précédente, vous avez peut-être remarqué que la création des index était effectué après la copie des données.

Nous avons fait ce choix pour deux raisons:

intuitivement, la création d’index en une seule fois, qui requiert la lecture toute la table, semble plus efficace que des mises à jour d’index à chaque insertion d’enregistrement;
cela permet de contrôler les ressources CPU allouées.

Une partie de la création d’index peut être effectuée en parallèle par des agents (worker) sur des CPU différents.

La documentation explique les pré-requis de cette allocation.

PostgreSQL can build indexes while leveraging multiple CPUs in order to process the table rows faster for index methods that support building indexes in parallel (currently, only B-tree).

(..)

Generally, a cost model automatically determines how many worker processes should be requested, if any.

(..)

Increasing max_parallel_maintenance_workers may allow more workers to be used, which will reduce the time needed for index creation, so long as the index build is not already I/O bound. Of course, there should also be sufficient CPU capacity that would otherwise lie idle.

Elle ajoute mentionne:

Parallel workers are taken from the pool of processes established by max_worker_processes, limited by max_parallel_workers. Note that the requested number of workers may not actually be available at run time. If this occurs, the utility operation will run with fewer workers than expected.

(..)

Note that parallel utility commands should not consume substantially more memory than equivalent non-parallel operations.

(..)

However, parallel utility commands may still consume substantially more CPU resources and I/O bandwidth.

Allouer peu de ressources

Nous souhaitons allouer un seul agent pour créer cet index, pour laisser la majorité des ressources disponibles à l’application.

Nous essayons d’abord de modifier ce paramètre pour toute la base de données. Cela affecte les création d’index et les VACUUM.

Il vaut par défaut 2, nous le passons au minimum: 1.

SHOW max_parallel_maintenance_workers;
> max_parallel_maintenance_workers
>----------------------------------
> 2
SET max_parallel_maintenance_workers = 1;

Nous démarrons des simulations d’activité sur l’application et démarrons la création d’index. On observe une dégradation nette des temps de réponse.

Nous essayons de limiter cette modification uniquement à cette table.

ALTER TABLE answers_bigint  SET (parallel_workers = 1);
SELECT reloptions FROM pg_class WHERE oid = 'answers_bigint'::regclass::oid;
>      reloptions
>----------------------
> {parallel_workers=1}

On observe toujours une dégradation.

Allouer beaucoup de ressources

L’hypothèse de ne pas impacter les temps de réponse semble compromise. Nous nous dirigeons alors vers un créneau de maintenance, où l’on essaierait de créer l’index le plus rapidement possible. Pour cela, il nous faut donner la majorité des ressources. Nous augmentons le nombre de worker pour qu’il soit le même que le nombre de CPU.

Nous suivons le nombre de worker réellement utilisés.

SELECT
    current_setting('max_parallel_workers')::integer AS max_workers,
    COUNT(*) AS active_workers
FROM pg_stat_activity
WHERE backend_type = 'parallel worker';

Malgré cela, le temps d’exécution ne change pas.

Nous explorons d’autres pistes, comme la mémoire ou les tablespace alloués. Nous ne constatons pas de changement de comportement.

Utiliser l’allocation native

Notre dernier essai est d’abandonner la création d’index en parallèle, pour tester cet extrait de la documentation.

However, parallel utility commands may still consume substantially more CPU resources and I/O bandwidth.

La durée d’exécution est la même, 12 heures, un peu moins que la solution native, pour une complexité bien supérieure.

Table answers
- PK: 35 minutes
- FK: 21 minutes
- NOT NULL: 2 heures 16 minutes
- Autres index: 31 minutes

Table knowledge-elements
- PK: 1 heure 17 minutes
- FK: 2 heures 50 minutes
- NOT NULL: 3 heures 28 minutes
- Autres index: 1 heure 8 minutes

Le temps de la réflexion

Nous avons testé beaucoup de réglages et prenons un peu de recul, à savoir relire la documentation. Cette phrase attire enfin notre attention.

Increasing max_parallel_maintenance_workers may allow more workers to be used, which will reduce the time needed for index creation, so long as the index build is not already I/O bound.

Nous faisons appel à la communauté pour savoir comment vérifier si l’I/O est le facteur limitant. La réponse est de nous tourner vers notre PaaS, car ces métriques ne sont pas accessibles dans la base de données. C’est ce que nous faisons, et la réponse est claire

D’après nos hypothèses, la limitation ici serait lié aux IOPS. Pourquoi ? Lors de vos opérations intenses en lectures/écritures, vous pouvez voir que le CPU ne monte pas tellement considérant qu’ils y a 8 cores disponibles avec 4 garanties (400% CPU) pour le plan. Le nombre d’IOPS disponible est proportionnel à la capacité de la base (..) donc 4500 IOPS.

Les IOPS dans l’univers du cloud est souvent ce qui est le plus coûteux par rapport à la capacité et nous ne pouvons pas simplement vous donner 20 000 IOPS par exemple.

Bilan

La solution native prenait 15 heures et la solution en arrière plan nécessitait avec un créneau de maintenance de 12 heures. Lors d’essais quelques mois après, la durée d’exécution de la solution en arrière plan prenait encore plus de temps, alors que la solution native restait stable.

Il restait la possibilité de répartir la création des index dans le temps, dans les plages de faible activité de la plateforme (nuit, week-end). Cela entrainait malgré tout une baisse de la qualité de service pendant la création d’au moins un index, qui pouvait prendre jusqu’à 2h50 pour le plus important. Il serait dans ce cas nécessaire de mobiliser une équipe pendant ce créneau, pour monitorer les opérations et les interrompre si la qualité de service était trop impactée.

Nous avons alors proposé ces deux solutions, native et en arrière plan, à l’équipe métier, au contact des utilisateurs et ayant une vision d’ensemble. Leur réponse fut claire; ils préféraient une solution simple, avec interruption totale de service, prévisible et annoncée à l’avance aux partenaires et aux utilisateurs.

Nous avons donc choisi la solution native, pour sa constance en termes de temps d’exécution et sa faible complexité. Cela a été l’occasion de multiples apprentissages, notamment du risque de réorganisation de la table et des facteurs limitant sur des opérations intensives.

Il existe peut-être une solution sans interruption de service, par exemple dans une instance séparée et une réplication logique, mais ces services ne sont pas disponibles pour l’instant.

Implémentation

La solution native est dans cette courte pull-request.

Exécution en production et perspectives

Nous avions appris dans la phase d’exploration que la durée d’exécution assez longue de la migration sans état d’avancement était frustrant. L’exécution de la solution native étant prévue sur un créneau de faible fréquentation, à savoir la nuit, il était important de disposer d’informations claires sur ce qui se passait pour pouvoir prendre les bonnes décisions, même sous la fatigue et la pression.

Un monitoring complet a été mis en place sur les 3 phases:

arrêt des applications;
avancement de la migration;
redémarrage des applications.

L’exécution en production s’est bien passée. La durée de traitement a été plus longue que sur l’environnement de test, à savoir 19 heures au lieu de 12 heures. Nous ne connaissons pas la cause de cet allongement; on peut faire l’hypothèse que les données étaient éparpillées sur le disque en production alors que sur la plateforme de test, importée par dump, les données étaient contigües.

Nous en retenons la nécessité de prévoir un créneau de maintenance un peu plus important.

Suivi de migration avec Steampipe

2022-09-20T08:10:42+00:00

Le 23 juillet 2022 à 22h et jusqu’au 24 juillet à 17h, Pix était en maintenance. La raison ? Nous avons profité de la période de calme de l’été pour migrer l’identifiant primaire de l’une des tables de notre base de données de int à bigint. Cela fait suite à la précédente migration d’août dernier.

Dans ce genre de moment, tout le monde doit être aligné. En effet pour que la migration se fasse, il faut s’assurer que l’ensemble des applications impactées soient en maintenance, que la base de données soit dans le bon état, lancer le script de migration, attendre (longtemps), vérifier le bon résultat, et relancer les applications.

Pour tout cela il est nécessaire d’avoir de bons outils. Des outils nous en avons justement à foison, entre le monitoring externe de nos applications Freshping, Datadog pour les logs des applications, Scalingo notre hébergeur et Confluence pour la documentation.

Tous ces outils, associés à 6 personnes qui doivent se relayer pas toujours à l’aise avec les outils de suivi de la production, rendent l’alignement complexe.

Pour résoudre ce problème nous avons donc utilisé un nouvel outil, Steampipe, pour les gouverner tous.

Nous utilisons déjà Steampipe pour vérifier l’état de la production tous les jours, mais c’était notre première utilisation des dashboards.

Nous l’avons construit pour permettre un suivi chronologique de la migration:

La mise en maintenance des applications Pix impactées
Le suivi de la migration
La réouverture

Le dashboard agit comme une tour de contrôle de la migration. En un coup d’oeil, nous savons où nous en sommes. Le code du dashboard est, comme beaucoup de choses chez Pix, accessible sur GitHub.

Trêve de bavardage, à quoi il ressemble ?

Au début tout est rouge:

Et puis une fois la mise en maintenance effectuée, cela passe au vert (vous avez remarqué les jolies icônes ?)

Tout est éteint certes, mais est-ce que nous n’avons pas oublié des applications qui auraient des connexions ouvertes sur la base ?

Ensuite on lance le processus de migration:

Au bout de quelques heures, on y est ?

OUI

Sous le capot

Coté hébergement, comme pour tout le reste, nous l’avions déployé sur Scalingo grâce au buildpack steampipe. Comme nous manipulions des informations de production, il était sur la région osc-secnum-fr1.

La partie suivie de la mise en maintenance utilisait le plugin net, en vérifiant le code HTTP 503 des applications. Pour les applications non directement accessibles depuis internet, nous avons utilisé le plugin scalingo pour vérifier que tous les conteneurs étaient éteints. La vérification de la désactivation du monitoring a été faite avec le plugin freshping.

Avant de lancer la migration, nous avions le nombre de connexions ouvertes a PostgreSQL affichées. Utile pour savoir si tout avait bien été éteint. La récupération se faisait avec le plugin datadog, qui récupérait les infos de pix-db-stats.

Le suivi de la migration était plutôt minimale, parce que c’est PostgreSQL qui faisait le travail, sans réelle possibilité de connaitre de suivre précisément la progression. Mais nous pouvions monitorer les différentes étapes du script de migration, et ce sur les 2 bases à migrer simultanément. Pour cela le plugin datadog regardait les logs générés par les conteneurs pour afficher l’étape en cours.

Conclusion

La migration s’est bien déroulée, et nous sommes contents d’avoir pu expérimenter les tableaux de bord Steampipe. Sa capacité à interroger différents services, de les mixer et d’avoir une jolie interface permet de démarrer très rapidement et de rajouter au fur et a mesure des informations.

Des choses étaient tout de même perfectibles, comme le suivi de la migration qui était un peu fragile, ou bien certaines étapes de la mise en maintenance qui n’étaient pas visibles dans Steampipe, comme l’arrêt de l’infrastructure data sur OVH (par manque de temps principalement).

Si nous espérons ne pas avoir souvent à mettre en maintenance tout pix, avoir un outil qui nous permet de centraliser toutes les informations nous sera certainement utile à l’avenir avec l’expérience accumulée cette fois-ci.

Passer une PK de INT en BIGINT en zéro downtime

2021-09-03T08:10:42+00:00

TL;DR

Dans quelques mois, la table la plus volumineuse (nombre de lignes) aurait épuisé les valeurs disponibles pour sa clef primaire. Pour éviter cette situation, nous souhaitions changer de type en minimisant l’impact utilisateur, en visant des migrations de BDD “zero-downtime”.

Nous avons réussi et partageons avec vous nos apprentissages. Pour les impatients, la solution est ici.

Ceci dit, cela a eu lieu dans des circonstances particulières :

table non référencée par d’autres tables ;
trafic réduit (vacances).

Nous avons prévu de migrer d’autres tables, référencées, en charge nominale. Nous partagerons les résultats dans un autre article.

Motivation

En un an, depuis septembre 2020, la fréquentation de Pix a augmenté de manière spectaculaire. La charge a été bien absorbée par l’infrastructure, mais nous nous sommes rendu compte d’une autre conséquence: une table allait épuiser l’identifiant utilisé par sa clef primaire.

Il est bien sûr possible de modifier le type de cette propriété avec l’instruction native ALTER TABLE foo ALTER COLUMN id SET DATA TYPE BIGINT, mais cela a un coût proportionnel au remplissage de la table. Une exécution de cette instruction sur les données de production, sur un environnement moins puissant, a duré 8 heures.

Nous souhaitions trouver une alternative, à savoir effectuer ce changement sans que les utilisateurs ne s’en rendent compte :

pas d’interruption de service, même sous la forme d’une fenêtre de maintenance planifiée ;
pas de dégradation sensible des temps de réponse pendant les opérations.

Recherche de solution

Ce thread Stack Overflow est un excellent point d’entrée sur le sujet.

Deux solutions y sont proposées :

soit utiliser une colonne temporaire ;
soit utiliser une base de données temporaire, alimentée par une réplication logique.

Nous avons choisi la colonne temporaire, car cette solution peut être mise en œuvre immédiatement dans notre environnement.

En effet, nous utilisons les services d’un PaaS, Scalingo, et sommes heureux de ne pas avoir à installer et maintenir nos bases de données. Le service spécifique de la réplication logique n’est pour l’instant pas offert.

Examinons pour commencer la solution d’origine, celle avec colonne temporaire, puis voyons les modifications que nous y avons apportées.

Étape 1 : convertir les données en tâche de fond

La commande ALTER TABLE foo ALTER COLUMN id SET DATA TYPE BIGINT effectue (entre autres) une conversion des données (cast) de INTEGER à BIGINT.

La documentation mentionne en effet :

Changing the type of an existing column will require the entire table and its indexes to be rewritten. As an exception, when changing the type of an existing column and the old type is either binary coercible to the new type a table rewrite is not needed; but any indexes on the affected columns must still be rebuilt. Table and/or index rebuilds may take a significant amount of time for a large table; and will temporarily require as much as double the disk space.

Comme l’opération native pose un verrou exclusif sur la table, il faut attendre sa réécriture complète pour y accéder.

An ACCESS EXCLUSIVE lock is held unless explicitly noted.

L’alternative à la solution native est d’effectuer la conversion des données en tâche de fond :

dans une colonne de type BIGINT, non exposée à l’API ;
pour les nouveaux tuples, à l’aide d’un trigger ;
pour les tuples existants, par un traitement batch.

Étape 2 : substituer les colonnes et créer la clef primaire

Une fois la migration achevée, une fenêtre de maintenance est requise (1h dans le cas d’origine) pour :

supprimer les contraintes sur la colonne INTEGER (PK, FK) ;
promouvoir la colonne de type BIGINT en tant qu’identifiant ;
recréer les contraintes (PK et FK).

Améliorations

Cette solution va dans le bon sens, mais ne satisfait par tous nos critères : il reste une fenêtre de maintenance. Nous pensons qu’il est possible de pousser la solution et d’éliminer totalement cette fenêtre.

Le principe est le suivant :

la contrainte de clef primaire comporte une contrainte NOT NULL et une contrainte UNIQUE ;
c’est la validation de ces contraintes qui prend le plus de temps dans la fenêtre de maintenance ;
ces validations peuvent être effectuées en amont.

Pour valider les contraintes en amont :

ajouter une contrainte NOT NULL dès la création de la colonne ;
créer un index UNIQUE de manière concurrente CREATE INDEX CONCURRENTLY.

Il ne reste plus, comme dernière opération, qu’à créer la PK sur base de l’index UNIQUE. ALTER TABLE "foo" ADD CONSTRAINT "foo_pkey" PRIMARY KEY USING INDEX "foo_id_unique"

PostgreSQL détecte lui-même la contrainte NOT NULL.

Implémentation

Le code présenté a été modifié pour les besoins de l’article, mais un lien est fourni vers chaque commit pour les détails.

A l’état initial, la table contient 700 millions d’enregistrements. fd7273f9

CREATE TABLE "knowledge-elements"(
    id             SERIAL PRIMARY KEY,
    source         varchar(255),
    (...)
);

La première étape est l’ajout d’une colonne temporaire, avec une migration de BDD, incluse dans le déploiement de la release. eecfd941

ALTER TABLE "knowledge-elements" ADD COLUMN "bigintId" BIGINT NOT NULL DEFAULT -1;

Puis, un trigger est créé pour alimenter la valeur pour les nouveaux enregistrements.

CREATE OR REPLACE FUNCTION copy_int_id_to_bigint_id() RETURNS TRIGGER AS $$ BEGIN NEW."bigintId" = NEW.id::BIGINT; RETURN NEW; END $$ LANGUAGE plpgsql;
CREATE TRIGGER "trg_knowledge-elements" BEFORE INSERT ON "knowledge-elements" FOR EACH ROW EXECUTE FUNCTION copy_int_id_to_bigint_id();

Ensuite, le script de migration inclus dans la PR est lancé manuellement (durée: 48h pour 700 millions de lignes). d89cb206

const data = await client.query('SELECT MAX(id) FROM "knowledge-elements"');
const startId = 0;
const endId = maxData.rows[0].max;
for (let id = startId; id < endId; id += chunkSize) {
  const result = await client.query(`
        UPDATE "knowledge-elements"
        SET "bigintId" = id
        WHERE ID BETWEEN ${id} AND ${id + chunkSize - 1}`);
}
await client.query('CREATE UNIQUE INDEX CONCURRENTLY "indexidBigInteger"');

Pour finir, une dernière migration, celle qui expose la colonne BIGINT 9985cafe

BEGIN TRANSACTION;
LOCK TABLE "knowledge-elements" IN ACCESS EXCLUSIVE MODE;
DROP TRIGGER "trg_knowledge-elements" ON "knowledge-elements";
DROP FUNCTION "copy_int_id_to_bigint_id";
ALTER SEQUENCE "knowledge-elements_id_seq" OWNED BY "knowledge-elements"."bigintId";
ALTER SEQUENCE "knowledge-elements_id_seq" AS BIGINT;
ALTER TABLE "knowledge-elements" ALTER COLUMN "bigintId" SET DEFAULT nextval('"knowledge-elements_id_seq"');
ALTER TABLE "knowledge-elements" ALTER COLUMN "id" DROP DEFAULT;
ALTER TABLE "knowledge-elements" DROP CONSTRAINT "knowledge-elements_pkey";
ALTER TABLE "knowledge-elements" ALTER COLUMN "id" DROP NOT NULL;
ALTER TABLE "knowledge-elements" ADD CONSTRAINT "knowledge-elements_pkey" PRIMARY KEY USING INDEX "knowledge-elements_bigintId_index";
ALTER TABLE "knowledge-elements" RENAME COLUMN "id" TO "intId";
ALTER TABLE "knowledge-elements" RENAME COLUMN "bigintId" TO "id";
COMMIT TRANSACTION;

Validation de la solution

Cette hypothèse de solution a été mise progressivement en contact avec la réalité, pour garder un feedback rapide :

exécution sur une table de test, ne comportant qu’une seule colonne, sur une volumétrie comparable à la production ;
même test, en soumettant la BDD à des requêtes concurrentes de lecture/écriture sur la table pour estimer l’impact sur les temps de réponse ;
exécution sur une copie de la table de production ;
même test, en soumettant la BDD à un échantillon des requêtes de production sur la table pour estimer l’impact sur les temps de réponse ;
intégration du code dans le processus de migration de BDD (knex) ;
déploiement du code, via le processus de migration, sur une instance de reporting de production.

Les apprentissages ont été les suivants :

l’intégration maximale au processus de déploiement augmente la fiabilité ;
les tests menés dès le début ont entraîné la mise en place au plus tôt d’un monitoring (extension pg_stat_statements + Datadog) sur :
- la vitesse de la migration et sa date de fin estimée;
- les temps de réponse BDD et API;
la pertinence des tests est limitée par:
- la capacité de reproduire un trafic similaire à la production ;
- le fait que l’environnement soit sur une plateforme dédiée, avec une disponibilité des ressources partagée (ex: I/O) non déterministe.

Exécution en production et perspectives

Le plan se déroule sans accroc

La migration préalable s’est déroulée sans erreur.

La migration des données proprement dite a pris environ 24h.

L’exposition de la nouvelle colonne, lors du déploiement, a pris un temps négligeable pour les utilisateurs finaux (< 1 seconde).

2021-08-27 14:10:40.368443479 +0200 CEST [postdeploy-2719] > pix-api@3.92.0 postdeploy /app
2021-08-27 14:10:40.368393446 +0200 CEST [postdeploy-2719]
2021-08-27 14:10:41.566685265 +0200 CEST [postdeploy-2719] Batch 188 run: 1 migrations
2021-08-27 14:10:42.176473412 +0200 CEST [manager] container [postdeploy-2719] (6128d63ffcff1013ac9e57c1) has stopped

Mais

Un impact non négligeable du traitement de migration sur le temps de réponse

Bien que l’opération soit un succès, lors des étapes préparatoires :

le temps de réponse de l’API a augmenté d’un facteur 10, en passant d’une moyenne de 70 ms à 1 000 ms ;
lors de l’étape de migration des données, ont eu lieu 4 pics à 3 secondes, d’une demi-heure chacun ;
lors de l’étape de validation des contraintes, a eu lieu 1 pic à 10 secondes, d’une heure et demie.

Malgré cela, l’impact utilisateur a été faible, car :

cela eu lieu en été, période de faible fréquentation de la plateforme ;
le plus long pic a eu lieu à un horaire de faible fréquentation (nuit).

Si l’impact utilisateur s’était avéré plus fort, nous aurions ralenti le traitement en réduisant :

la taille des batchs ;
le rythme d’exécution (pauses périodiques).

Un impact sur l’organisation des données sur le disque

Nous avons constaté que la table est bien plus fragmentée après migration qu’avant migration. Bien que nous n’ayons pas fait de test comparatif, il est possible que cela soit dû à notre solution.

En effet :

la solution native réécrit la table en une seule fois ;
notre solution la réécrit en plusieurs fois.

Cela peut avoir deux effets :

occupation de disque plus importante ;
impact sur les temps de réponse.

Nous monitorons actuellement les temps de réponse pour déterminer s’il y a un impact.

Perspectives

Nous avons prévu de changer le type d’identifiant sur d’autres tables. Nous ne pourrons pas appliquer exactement la même approche à l’avenir, pour deux raisons qui seront détaillées. Aussi, nous allons continuer à y travailler et cela fera l’objet d’un nouvel article.

Diminuer les impacts possibles

Le contexte de faible fréquentation de la plateforme ne peut pas être pris comme un pré-requis.

Nous pensons à :

rendre le traitement de migration paramétrable à chaud, en passant de variables d’environnement à une table de paramétrage.
modifier notre approche en passant d’une colonne temporaire à une table temporaire .

Généraliser la solution

“Rudy’s Rutabaga rule” de Gerald Weinberg nous dit

Once you eliminate your number one problem, number two gets a promotion.

Notre problème n°2 est une table dont l’identifiant :

dont le type doit aussi être modifié en BIGINT ;
est référencé par une autre table (FK).

Nous allons réutiliser le principe de “faire le maximum en amont” sur cette nouvelle situation :

deux colonnes à mettre à jour au lieu d’une ;
une contrainte de type FK en plus de la contrainte de type PK.

Des suggestions d’amélioration ?

Afin de rester sur un format court, cet article :

prend comme pré-requis le MVCC de PostgreSQL, et ses conséquences lors d’ajout et de suppression de colonne (bloat) ;
ne précise pas la raison des détails d’implémentation, notamment du script de migration des données.

Si vous avez des questions, contactez-nous pour que nous puissions améliorer cet article !

Gestion des environnements

2021-08-31T13:00:00+00:00

Une bonne gestion de production ne va pas sans une bonne gestion des environnements.

Avec le temps, nous en sommes venus à considérer et gérer au quotidien 6 types d’environnements, aux besoins, contraintes et cahier des charges bien définis :

local (ou localhost)
review app
intégration
recette
production
autres / ad hoc

1. Localhost

Il s’agit de l’environnement de développement propre à chaque développeur, sur son poste de travail professionnel individuel.

Chaque développeur est libre de travailler dans l’environnement qui lui convient le mieux (Mac OS, Linux, Windows), avec les outils qu’il préfère (WebStorm, Visual Studio, Vim).

Des outils sont développés, fournis et automatiquement mis en œuvre pour s’assurer que l’agent respecte les standards de l’organisation (versions de logiciel, format du code, etc.).

C’est le seul environnement qui n’est pas hébergé sur notre PaaS.

2. Review app (RA)

Il s’agit d’un environnement d’exécution (du code) éphémère, généré à chaque ouverture d’une pull request (PR) sur GitHub. Le but de ces environnements est de valider en autonomie un changement de code, qu’il soit lié à une fonctionnalité, une correction de bug, une modification technique ou une procédure / script / manipulation particulière.

Pour ce faire, nous utilisons la fonctionnalité Review Apps de Scalingo. Lorsque la PR est fermée (fusionnée ou annulée), l’environnement est automatiquement détruit.

Chaque environnement de RA reprend les spécifications techniques de la production, modulo certaines caractéristiques telles que la taille des ressources mobilisées, les données qui l’alimentent ou encore la présence / mutualisation ou non de serveurs front / CDN.

À chaque création d’une RA, des jeux de données sont générés, afin de faciliter, accélérer et fiabiliser les tests accomplis sur la version déployée.

À noter que nous avons déjà utilisé ce type d’environnement afin de tester rapidement une idée ou un prototype auprès d’un panel utilisateurs ou lors de phase de test terrain.

Autre remarque : par soucis d’économie et d’écologie, nous faisons en sorte (via Pix Bot) d’éteindre automatiquement les RA les soirs et week-end. Nous avons développé une petite bibliothèque (Node.js) Open Source pour l’occasion – scalingo-review-app-manager.

3. Intégration

Il s’agit d’un environnement unique, dont le but est de tester et valider la bonne intégration d’un changement sur l’ensemble du code.

Dans les faits, nous gardons un œil et une vigilance plutôt technique sur cet environnement. Mais les Product Owners (PO), de même que n’importe qui chez Pix, peuvent être susceptibles de l’utiliser pour remonter un problème, une erreur ou un feedback.

En ce sens, nous faisons en sorte que cet environnement soit disponible à tout moment.

Les données présentes au sein de cet environnement sont exclusivement des données de test. Il nous arrive quelquefois de les réinitialiser complètement ou d’en générer aléatoirement.

L’environnement d’intégration peut contenir plusieurs changements prêts à être propagés en recette.

Cet environnement est directement rattaché à la branche dev (sorte de branche tronc-commun) et donc automatiquement mis à jour à chaque fusion de branche / fermeture de PR.

4. Recette

Autre environnement unique, le but de l’environnement de recette est de contrôler plus finement les changements apportés récemment à la plateforme. Il s’agit de la dernière étape pour un changement avant la production.

Cet environnement peut aussi nous servir d’environnement de démonstration lors d’événements (notamment externes) ou de rituels (démonstration de fin d’itération), ou encore en interne pour tester les épreuves conçues par l’équipe de créateurs d’évaluations pédagogiques (postes ouverts).

Les principaux utilisateurs de la recette sont les PO qui valident les impacts fonctionnels et ergonomiques. Mais les développeurs ne sont pas en reste et contrôlent assidûment les autres points critiques de la plateforme : performance, sécurité, autres répercussions techniques ou organisationnelles.

Encore plus que l’intégration, cet environnement doit être opérationnel à chaque instant.

De même que pour l’intégration, les données sont exclusivement des données de test. Celles-ci ne sont pas réinitialisées et conservées telles quelles depuis le début, afin de se préparer et valider une dernière fois d’éventuelles manipulations ou attentions à avoir pour la production.

Contrairement à l’intégration, la recette n’est attachée à aucune branche Git. Sa mise à jour, c’est-à-dire la fusion de changements issus de la branche dev, est manuelle, déclenchée – la plupart du temps par les PO – via une procédure dite de “mise en recette” (ou MER).

5. Production

Il s’agit de l’environnement mis à la disposition des utilisateurs finaux de Pix (citoyens, partenaires, prescripteurs, certificateurs, etc.). C’est donc l’environnement le plus important de la plateforme.

En tant que tel, il se doit d’être fonctionnel, performant, sécurisé, disponible à tous, partout, tout le temps, en toutes circonstances, dans les meilleures conditions d’exploitation possibles.

Au plus fort de l’activité, l’environnement de production doit être capable d’accueillir efficacement plus d’une centaine de milliers d’utilisateurs par jour.

L’idée de cet article n’est pas de rentrer dans tous les détails opérationnels concernant la production et sa mise en œuvre. Certains éléments sont toutefois notables et intéressants pour la suite.

D’un point de vue “sécurité”, les applications sont hébergées sur des serveurs hébergés sur la zone SecNumCloud de Scalingo / Outscale. Tout est mis en œuvre pour dissocier le plus strictement possible l’environnement de production des autres environnements. Les données sont sauvegardées très régulièrement. De nombreux outils de monitoring / alerting sont développés et déployés pour assurer le parfait maintien opérationnel de cet environnement et chacun de ses composants.

Les ressources sont évidemment boostées, dupliquées et configurées en conséquence. A noter que nous utilisons pour les applications en production la fonctionnalité auto-scaling de Scalingo.

De même que la recette, la production n’est rattachée à aucune branche Git. Là aussi, le déploiement de changements en production est déclenché manuellement mais traité automatiquement via une procédure dédiée dite de “mise en production” (MEP).

6. Ad hoc

Il s’agit d’un dernier type d’environnement très particulier dont le but est de tester ou valider un changement, une opération, une procédure ou une idée dans un contexte particulier.

Par exemple, il nous est arrivé de monter un environnement ad hoc en zone SecNumCloud afin de descendre certaines informations de production pour évaluer le comportement et les impacts d’un script de migration sur une table de plus de 700 millions de lignes.

Nous pouvons aussi être amenés à créer un environnement ad hoc (en zone standard) pour nous aider à configurer un outil ou un service.

Ces environnements sont toujours temporaires et détruits lorsque nous n’en avons plus l’usage.

Remarques

Les données utilisateurs (de production) ne sont jamais descendues vers un autre environnement.

Lorsque les travaux l’obligent (ex : grosse migration de données), nous préférons créer un environnement ad hoc en zone SecNumCloud, avec des droits et des accès restreints et contrôlés.

Poisson d’avril !

2021-05-11T08:10:42+00:00

Parce que nous aimons rire, pour le 1er avril, nous avons décidé de faire une blague à nos utilisateurs. J’aimerais vous raconter comment cette blague est née, codée et déployée, car à l’échelle de Pix, une blague doit être réalisée sérieusement.

Tout a été imaginé et implémenté en une après-midi du 31 mars 2021, lors d’un “Tech Time”. Le “Tech Time” c’est une après-midi toutes les 2 semaines dans laquelle l’équipe de développement se retrouve pour travailler sur des sujets non fonctionnels, et pas forcément en rapport avec Pix.

Prise de décision

Nous nous retrouvons vers 14h30 pour discuter de quoi faire. Rapidement, nous envisageons de faire quelque chose avec le compteur de Pix, élément central de l’interface. Décision est prise de le faire inexorablement baisser.

Voilà à quoi ressemble le compteur à la base :

Implémentation

Nous implémentons rapidement la première itération en décrémentant le compteur avec comme valeur minimale -999. Tout se passe en TDD et en mob programming, par plage de 15 minutes. Tests unitaires, tests d’intégration tout y passe.

Nous nous rendons compte que nous devons gérer le cycle de vie de la blague. Il va falloir l’activer le 1er avril mais surtout l’arrêter dans la nuit. Pas question de déployer une version spécifiquement pour cela. Nous utilisons alors un mécanisme présent dans l’API de bascule de fonctionnalités (feature toggle) pour pouvoir le faire à chaud.

Les comportements sont testés, l’API est modifiée et nous faisons la pull request sur le dépôt.

Le spectacle

A 17h, c’est l’heure du spectacle. Nous montrons le résultat à l’équipe. Le voici:

Hilarant n’est-ce pas ?

La communication interne

Vers 18h, il est temps d’informer le reste de Pix de cette “fonctionnalité”, et surtout de valider que nous pouvons la déployer et l’activer.

Pour ne pas perturber les sessions de certifications du matin, il est décider de n’activer le poisson que le 1er Avril à 16h30.

Le déroulé

31 mars - 19h30 : La PR est fusionnée.
1er Avril - 10h20 : Une mise en recette est faite.
1er Avril - 17h10 : La mise en production est effectuée. La blague est ensuite activée en ajoutant la variable d’environnement FT_IS_APRIL_FOOL_ENABLED=true.
1er Avril - 22h30 : La variable d’environnement est supprimée. La blague n’est plus active :(
6 avril : la blague est supprimée du code

Conclusion

Nous remercions tout d’abord le support qui a géré les retours d’utilisateurs, certains amusés, d’autres moins.

Qu’avons-nous appris ?

Si la fonctionnalité a été rapidement codée, la plus grosse partie du boulot a été de faciliter le déploiement pour que tout se passe bien. La bascule à chaud de fonctionnalité est bien précieuse pour cela.

Imaginer, coder, tester et déployer une fonctionnalité non prévue en ~24h, c’est possible, et c’est bien sympa.

Si tu aimes le service public, coder et surtout t’amuser, nous recrutons.

Le blog technix

Suivi de la dérive de nos dépendances

Le constat

Libyear à la rescousse

A quoi cela ressemble ?

Conclusion

Essayez-le

Migrer de CommonJS vers ECMAScript Modules - #2

Y’a quoi au menu ?

L’équipe

Traiter les besoins internes

Travailler ensemble

La stratégie

Un feedback rapide ?

Des compromis, encore et toujours

Deux choix d’implémentation de la codebase

Les exports nommés

Les tests et l’injection de dépendance

En approchant de la production

Le suivi et la motivation

Sécuriser le déploiement

Happy end

And finally, monsieur, a wafer-thin mint

Le code

Canary release

Coût de coordination et complexité

Estimation

Migrer de CommonJS vers ECMAScript Modules #1

Y’a quoi au menu ?

Une histoire de modules

Les modules côté Javascript

Tout débute dans un navigateur

Un petit tour côté serveur

Happy end ?

Pourquoi migrer en ESM ?

Un peu de syntaxe

Modifier le code

Une solution simple

Une solution complexe et puissante : les codemods

L’AST

Sélectionner un élément à modifier

Modifier l’élément sélectionné

Un périmètre de travail parfois limité

Se faire aider

Tests automatisés

Lint

Heuristique d’automatisation

Cas 1 - Evidence : il faut automatiser

Cas 2 - Questionnement : faut-il automatiser ?

Cas 3 - Impasse : il est impossible d’automatiser

Conclusion

Bonus

Tester unitairement les composants sous Embroider

Le défi des tests unitaires avec Embroider et les composants Glimmer

Une nouvelle solution avec importSync de @embroider/macros

Une montée de version PostgreSQL en PaaS surprenante

TL;DR

Le décor

Le drame

L’enquête

S’en sortir

Détecter les index impactés

Rechercher les données invalides

Recréer les index

Passer une PK référencée du type INT en BIGINT

TL;DR

Motivation

Recherche de solution

Solution 1 : instructions natives PostgreSQL

Solution 2 : migration en arrière plan

Investigation

Migration des données

Migration dans la même table

Obstacle: la fragmentation

Migration des données dans une table séparée

Création des index

Allouer peu de ressources

Allouer beaucoup de ressources

Utiliser l’allocation native

Le temps de la réflexion