Migration on Carnet de découvertes

Inspecter un catalogue avec pg_migrate

Florent Jardin — Tue, 15 Sep 2026 16:00:00 +0200

Au cours des dernières années, je me suis engagé à identifier les atouts et faiblesses d’outils dédiés à la migration vers PostgreSQL. Plusieurs articles publiés par mes soins ont pavé le chemin vers une direction ambitieuse que j’entreprends depuis 2024 avec mes collègues Étienne Bersac et Pierre-Louis Gonon.

… Et la version stable 1.0 de PostgreSQL Migrator est sortie le 4 septembre dernier. L’occasion de présenter des fonctionnalités que j’utilise au quotidien et ce qu’elles apportent par rapport aux autres outils. Dans cet article, je souhaite m’attarder sur l’une d’entre elles, particulièrement précieuse pour préparer une migration : le catalogue hors-ligne.

Consulter le catalogue Oracle

Le catalogue d’une base de données relationnelle renferme la structure du modèle, les noms et le typage des colonnes d’une table, les options de contraintes, la définition d’une vue ou d’une fonction, etc. Tout ce qui est déclaré par l’utilisateur avec du DDL (Data Definition Language) est maintenu dans un catalogue comme unique source de vérité.

Sur les systèmes comme PostgreSQL, MySQL ou MSSQL Server, la norme encourage l’utilisation d’un catalogue universel, l’espace information_schema. Par exemple, on peut y questionner les noms des tables avec la même requête :

SELECT table_name FROM information_schema.tables
 WHERE table_schema = 'scott'
 ORDER BY table_name;

Cependant, ce n’est pas la solution idéale pour reconstruire un modèle de données. Chacun des systèmes se conforment au mieux à la norme SQL mais très fréquemment, ils l’enrichissent avec des extensions du langage ou prennent des libertés sur l’implémentation d’une fonctionnalité. Il en résulte que le catalogue information_schema n’est pas la source universelle, à peine une collection d’alias dans un catalogue système propre à chacun.

À présent, parlons d’Oracle et d’Ora2Pg. Si nous souhaitons recréer la structure d’une table depuis l’écosystème Oracle, plusieurs méthodes existent et toutes s’appuient sur les vues du catalogue que je présente en dernier.

L’instruction DESCRIBE

Certainement la moins riche des solutions mais la plus rapide pour une première inspection. Il s’agit d’un équivalent de la méta-commande \d dans psql ou du pragma table_info pour SQLite.

DESCRIBE SCOTT.EMP;

-- Name Null? Type
-- -------- -------- ------------
-- EMPNO NOT NULL NUMBER(4)
-- ENAME VARCHAR2(10)
-- JOB VARCHAR2(9)
-- MGR NUMBER(4)
-- HIREDATE DATE
-- SAL NUMBER(7,2)
-- COMM NUMBER(7,2)
-- DEPTNO NUMBER(2)

L’API METADATA

Il est possible d’employer un package Oracle très utile pour générer la structure d’une table au format texte SQL. Les équivalents des autres systèmes seraient l’instruction SHOW CREATE TABLE de MySQL ou encore .schema de SQLite.

SET pagesize 0
SET long 20000
SELECT dbms_metadata.get_ddl(
 object_type => 'TABLE',
 schema => 'SCOTT',
 name => 'EMP');

-- CREATE TABLE "SCOTT"."EMP"
-- ( "EMPNO" NUMBER(4,0),
-- "ENAME" VARCHAR2(10),
-- "JOB" VARCHAR2(9),
-- "MGR" NUMBER(4,0),
-- "HIREDATE" DATE,
-- "SAL" NUMBER(7,2),
-- "COMM" NUMBER(7,2),
-- "DEPTNO" NUMBER(2,0),
-- CONSTRAINT "PK_EMP" PRIMARY KEY ("EMPNO")
-- USING INDEX PCTFREE 10 INITRANS 2 MAXTRANS 255
-- STORAGE(INITIAL 65536 NEXT 1048576 MINEXTENTS 1 MAXEXTENTS 2147483645
-- PCTINCREASE 0 FREELISTS 1 FREELIST GROUPS 1 BUFFER_POOL DEFAULT)
-- TABLESPACE "SYSTEM" ENABLE,
-- CONSTRAINT "FK_DEPTNO" FOREIGN KEY ("DEPTNO")
-- REFERENCES "SCOTT"."DEPT" ("DEPTNO") ENABLE
-- ) PCTFREE 10 PCTUSED 40 INITRANS 1 MAXTRANS 255 NOCOMPRESS LOGGING
-- STORAGE(INITIAL 65536 NEXT 1048576 MINEXTENTS 1 MAXEXTENTS 2147483645
-- PCTINCREASE 0 FREELISTS 1 FREELIST GROUPS 1 BUFFER_POOL DEFAULT)
-- TABLESPACE "SYSTEM"

Les vues du catalogue

Les résultats précédents sont compilés depuis plusieurs vues systèmes. Sans surprise, les explorateurs classiques comme SQL Developer ou DBeaver, ainsi qu’Ora2Pg et PostgreSQL Migrator, consultent directement les données des différentes vues pour obtenir le DDL complet.

Ora2Pg obtient la liste des tables depuis la vue ALL_OBJECTS et le stocke en mémoire dans un tableau associatif $self->{tables}. Puis, il itère sur ALL_TAB_COLUMNS pour collecter le détail de chaque table et les rattacher avec une nouvelle profondeur de ce même tableau global $self->{tables}{$table}{column_info}{$column}.

SELECT A.OWNER,A.OBJECT_NAME,A.OBJECT_TYPE FROM ALL_OBJECTS A
 WHERE A.OBJECT_TYPE IN ('TABLE','VIEW') AND A.OWNER='SCOTT';

SELECT A.COLUMN_NAME, A.DATA_TYPE, A.DATA_LENGTH, A.NULLABLE, A.DATA_DEFAULT,
 A.DATA_PRECISION, A.DATA_SCALE, A.CHAR_LENGTH, A.TABLE_NAME, A.OWNER
 FROM ALL_TAB_COLUMNS A
 WHERE A.TABLE_NAME NOT LIKE 'BIN$%' AND A.TABLE_NAME='EMP'
 ORDER BY A.COLUMN_ID

La structure en mémoire $self que maintient Ora2Pg ne persiste pas entre deux exécutions. La lecture du catalogue source est nécessaire à chaque fois. En opposition, j’ai eu l’occasion de découvrir une alternative nommée db_migrator, basée sur les Foreign Data Wrapper. Avec cette solution, le catalogue est stockée dans une base de données PostgreSQL.

Il était alors simple de lancer une inspection avec la méthode db_migrate_refresh() pour créer un instantané du catalogue distant et de pouvoir le questionner hors-ligne, sans se reconnecter à l’instance Oracle. De cette découverte émergera les premiers tâtonnements du catalogue au format JSON de PostgreSQL Migrator.

Questionner du JSON

Le stockage du catalogue requiert un format structuré, stable et non contraignant. De facto, le choix de conserver les données dans des tables PostgreSQL nous est apparu inadapté, bien qu’élégant pour des yeux de DBA. L’outil PostgreSQL Migrator se vante d’être portable et nous ne souhaitions pas encombrer l’instance PostgreSQL finale d’un schéma transitoire.

Comme Ora2Pg, une structure mémoire Catalog (internal/catalog/catalog.go) est initialisée au début de l’inspection. Ce catalogue peut être étendu en fonction que la source soit une base Oracle ou MySQL/MariaDB, pour collecter les objets spécifiques du moteur, comme les packages ou les synonymes. Dès lors que la lecture du catalogue distant est réalisée, il suffit de sérialiser la structure dans un fichier JSON. Actuellement, la version 1.0 s’appuit sur le module sonic.

L’inspection est la première étape pour démarrer un projet avec pg_migrate, le petit nom de l’interface en ligne de commande (CLI) de PostgreSQL Migrator. Après avoir initialisé un dossier vide et valider l’accès à la base distante Oracle, les traces nous invitent à exécuter la commande pg_migrate inspect.

$ ora-scott && cd ora-scott
$ pg_migrate init --source "oracle://system:manager@localhost:1521/freepdb1"
14:55:28 INFO Databases connections closed. source=1 target=0
14:55:28 INFO Initialized migration project. source="Oracle Database 23ai Free"
14:55:28 INFO Inspect source catalog using pg_migrate inspect.
$ pg_migrate --verbose inspect
14:56:03 DEBUG Cache miss. name=Source
14:56:03 INFO Inspecting source database. driver=oracle
14:56:03 INFO This may take some time.
14:56:04 DEBUG Inspected schemas. count=1 duration=84.735201ms
14:56:05 DEBUG Inspected roles. count=6 duration=465.814794ms
14:56:06 DEBUG Inspected sequences. count=0 duration=1.050025889s
14:56:07 DEBUG Inspected routines. count=0 duration=2.794483231s
14:56:07 DEBUG Inspected views. count=0 duration=2.63147026s
14:56:21 DEBUG Inspected tables. count=4 duration=15.720365706s
14:56:31 DEBUG Inspected columns. count=18 duration=10.735219841s
14:56:41 DEBUG Inspected keys. count=2 duration=19.945416304s
14:56:44 DEBUG Inspected tables-indexes. count=0 duration=23.287211484s
14:56:48 DEBUG Inspected foreign-keys. count=1 duration=6.525976802s
14:56:58 DEBUG Inspected checks. count=0 duration=10.622190194s
14:56:58 INFO Inspected schema. name=SCOTT
14:56:58 DEBUG Inspection completed. duration=54.968668546s
...
14:57:12 INFO Inspection terminated. errs=0 online=true
14:57:12 INFO Execute pg_migrate ui to browse project.
14:57:12 INFO Execute pg_migrate dump to migrate for PostgreSQL.

Lors d’une première exécution, le catalogue local est inexistant (Cache miss. name=Source), ce qui provoque une connexion à la base distante pour le créer de toute pièce. Les fichiers de cache sont écrits dans le dossier caché .pg_migrate. Le catalogue de la source se nomme sobrement Source.json.

$ tree .pg_migrate/
.pg_migrate
├── Info.json
├── Map.json
├── Source.json
├── Stats.json
└── Target.json

Il a alors fallu me faire violence pour mettre de côté mes précieuses connaissances en SQL pour apprendre le langage jq afin de questionner les fichiers JSON d’un projet pg_migrate. Par exemple, le filtre suivant liste toutes les colonnes et leurs types de la table SCOTT.EMP :

$ set filter '.Tables[] | select (.Name == "EMP") | .Columns[] | .objectDefinition'
$ jq -r $filter < .pg_migrate/Source.json
EMPNO NUMBER(4, 0) NOT NULL
ENAME VARCHAR2(10)
JOB VARCHAR2(9)
MGR NUMBER(4, 0)
HIREDATE DATE
SAL NUMBER(7, 2)
COMM NUMBER(7, 2)
DEPTNO NUMBER(2, 0)

Bien évidemment, l’outil a fait un très long chemin depuis 2024 et cette architecture de catalogue hors-ligne est devenue la colonne vertébrale du produit. Ces fichiers ont permis d’explorer des possibilités jusqu’ici inatteignables avec Ora2Pg, en plus du mode hors-ligne.

La conversion passe d’un fichier Source.json à un fichier Target.json en lui appliquant des règles de conversion génériques et spécifiques ;
Une phase d’audit parcourt tous les nœuds pour appliquer un score, voire des annotations sur les difficultés de conversion ;
Une interface Web de type SPA (single page app) permet d’explorer les deux modèles (source et cible) pour se passer des filtres jq.

L’outil vient avec une commande dump, que l’on peut détourner pour récupérer la forme DDL d’un objet stocké dans le Target.json. Pour le moment, la commande complète est la suivante :

$ pg_migrate dump --force --section=pre-data Tables/scott.emp 2>/dev/null | cat
--
-- Name: emp; Type: TABLE; Schema: scott; Owner: scott
--

CREATE TABLE "scott"."emp" (
 "empno" smallint NOT NULL,
 "ename" varchar(10),
 "job" varchar(9),
 "mgr" smallint,
 "hiredate" timestamp,
 "sal" numeric(7, 2),
 "comm" numeric(7, 2),
 "deptno" smallint
);

ALTER TABLE "scott"."emp" OWNER TO "scott";

Conclusion

Je suis profondément fier du travail accompli avec cette première version stable. Nous concluons une aventure palpitante avec mes collègues chez Dalibo, celle de plus de deux ans de développement d’un outil libre et gratuit et qui a vocation à dépasser son illustre prédécesseur Ora2Pg. La feuille de route est claire. Nous avons un retard métier conséquent sur la référence open-source de la migration, mais nous ne rougissont pas. Les fondations sont solides, le langage Go permet de répondre à de véritables besoins de simplification et de modernité.

À l’heure où les empires du numérique se gavent de nos données métiers, qu’ils siphonnent la valeur travail de nos entreprises, il est urgent de réagir et de croire qu’un autre numérique est possible. Les projets de migration deviennent complexes, exigeants, avec des profils très variés, nous tentons d’apporter une réponse qui ne repose pas exclusivement sur des agents LLM ou des services américains.

La voie du logiciel libre est devant nous depuis des décennies, il ne manque que les passerelles qui permettent de tourner le dos à ces technologies privatives de liberté, d’innovation et de moyens. À mon échelle de DBA et de Product Owner, engagé dans la coopérative Dalibo, j’œuvre pour cette urgence collective.

Substituer une variable dans un script SQL

Florent Jardin — Mon, 25 Nov 2024 09:00:00 +0100

Il est fréquent de vouloir automatiser une tâche répétitive en la scriptant rapidement, puis à force d’itérations, de l’enrichir, voire de l’intégrer dans la base de code d’un projet. À ce jeu, les outils comme SQL*Plus et psql peuvent être de puissants alliés et des interpréteurs aussi pertinents que Bash ou Python.

Dans le cadre des projets de migration que je mène régulièrement, il m’arrive de tomber sur ces scripts, en grand nombre. Certains ont la particularité de proposer des paramètres d’entrée, traités par SQL*Plus avec le mécanisme très confortable de substitution de variables. Dans cet article, je partage quelques astuces pour convertir certains aspects de ces scripts grâce aux fonctionnalités équivalentes que l’on retrouve sur l’outil psql de PostgreSQL.

Substituer une variable…

Comme point de départ, penchons-nous sur la syntaxe supportée par l’outil d’Oracle avec un exemple fil rouge. Nous incarnons un utilisateur qui souhaite obtenir le résultat des ventes d’une société factice, en appliquant deux filtres basés sur un numéro produit et deux dates passées en paramètres.

-- sqlplus-report-01.sql
CONNECT user/password@database

DEF product_id = '&1'
DEF start_date = '&2'
DEF end_date = '&3'

SELECT NVL(SUM(amount), 0) AS total_amount
 FROM orders
 JOIN products USING (product_id)
 WHERE product_id = &product_id
 AND order_date BETWEEN TO_DATE('&start_date', 'YYYY-MM-DD')
 AND TO_DATE('&end_date', 'YYYY-MM-DD');

QUIT

$ sqlplus -S /nolog @sqlplus-report-01.sql 20 2024-11-01 2024-11-30
old 3: WHERE product_id = &product_id
new 3: WHERE product_id = 20
old 4: AND order_date BETWEEN TO_DATE('&start_date', 'YYYY-MM-DD')
new 4: AND order_date BETWEEN TO_DATE('2024-11-01', 'YYYY-MM-DD')
old 5: AND TO_DATE('&end_date', 'YYYY-MM-DD')
new 5: AND TO_DATE('2024-11-30', 'YYYY-MM-DD')

TOTAL_AMOUNT
------------
 1378.98

Comme nous pouvons l’observer, la substitution s’opère en SQL*Plus dès que le caractère & est rencontré, que son contenu soit ou non entouré de guillemets simples. En début de script, j’ai appliqué une stratégie simple en définissant une variable avec un nom évocateur, pour faciliter la lisibilité et la maintenance du script et ne plus s’accommoder des variables nommées selon leur position dans la liste des arguments.

Pour obtenir un résultat équivalent avec psql, nous devons effectuer une assignation de variables en dehors du script, avec l’option -v ou --set fournie par psql. Ces variables seront alors substituées dans le script à l’aide du mécanisme d’interpolation.

-- psql-report-01.sql
\pset footer off

SELECT COALESCE(SUM(amount), 0) AS total_amount
 FROM orders
 JOIN products USING (product_id)
 WHERE product_id = :product_id
 AND order_date BETWEEN :'start_date'::date
 AND :'end_date'::date;

$ psql -f psql-report-01.sql \
$ -v product_id=20 \
$ -v start_date='2024-11-01' -v end_date='2024-11-30'
 total_amount
--------------
 1378.98

La reprise du script original est tout à fait triviale, on y retrouve une syntaxe similaire avec le caractère : en lieu et place de &. Toutefois, si la variable doit être comprise entre deux guillemets simples, nous constatons que le caractère : doit être saisi à l’extérieur et non à l’intérieur.

… dans un bloc anonyme

Les choses se gâtent lorsque le script devient plus complexe, et nécessite de manipuler nos précédentes variables dans un bloc anonyme PL/SQL. Reprenons notre script pour l’enrichir d’un message personnalisé si le produit demandé n’existe pas. Une première lecture sur la table products peut, éventuellement, retourner l’exception NO_DATA_FOUND que nous souhaitons intercepter.

-- sqlplus-report-02.sql
CONNECT user/password@database

DEF product_id = '&1'
DEF start_date = '&2'
DEF end_date = '&3'

SET serveroutput ON
SET feedback OFF
SET verify OFF

DECLARE
 p_id products.product_id%TYPE;
 p_sum NUMBER;
 p_start DATE := TO_DATE('&start_date', 'YYYY-MM-DD');
 p_end DATE := TO_DATE('&end_date', 'YYYY-MM-DD');

BEGIN
 SELECT product_id INTO p_id
 FROM products
 WHERE product_id = &product_id;

 SELECT NVL(SUM(amount), 0) INTO p_sum
 FROM orders
 WHERE product_id = p_id
 AND order_date BETWEEN p_start AND p_end;

 DBMS_OUTPUT.PUT_LINE('Total amount: ' || p_sum);

EXCEPTION
 WHEN NO_DATA_FOUND THEN
 DBMS_OUTPUT.PUT_LINE('Product ' || &product_id || ' does not exist');
END;
/

QUIT

$ sqlplus -S /nolog @sqlplus-report-02.sql 120 2024-11-01 2024-11-30
Product 120 does not exist

Du côté de notre alternative PostgreSQL et son invite de commande psql, il apparaît qu’un bloc anonyme en PL/pgSQL ne permet pas de réaliser la substitution comme nous le souhaitons. Si nous tentons de réaliser un contrôle avec le renvoi d’une exception, nous obtenons une erreur de syntaxe, car la variable n’est pas substituée.

-- psql-report-02-wrong.sql
DO $$
DECLARE
 p_id products.product_id%TYPE;
 p_sum numeric;
 p_start date := :'start_date'::date;
 p_end date := :'end_date'::date;

BEGIN
 SELECT product_id INTO STRICT p_id
 FROM products
 WHERE product_id = :product_id;

 SELECT COALESCE(SUM(amount), 0) INTO p_sum
 FROM orders
 WHERE product_id = p_id
 AND order_date BETWEEN p_start AND p_end;

 RAISE NOTICE 'Total amount: %', p_sum;

EXCEPTION
 WHEN no_data_found THEN
 RAISE NOTICE 'Product % does not exist', :product_id;
END;
$$;

$ psql -f psql-report-02-wrong.sql \
$ -v product_id=120 \
$ -v start_date='2024-11-01' -v end_date='2024-11-30'
psql:psql-report-02-wrong.sql:25: ERROR: syntax error at or near ":"
LINE 5: p_start date := :'start_date'::date;
 ^

Fort heureusement, psql ne nous laisse pas sans ressource. Les méta-commandes qu’il propose peuvent nous permettre d’obtenir le même résultat, moyennant une réécriture plus profonde du script. Nous allons utiliser la méta-commande \gset pour stocker l’état du produit puis la méta-commande \if pour réaliser le contrôle.

-- psql-report-02.sql
\pset footer off

SELECT NOT EXISTS(
 SELECT product_id
 FROM products
 WHERE product_id = :product_id
) AS unknown_product \gset

\if :unknown_product
 \echo 'Product' :product_id 'does not exist'
 \quit
\endif

SELECT COALESCE(SUM(amount), 0) AS total_amount
 FROM orders
 JOIN products USING (product_id)
 WHERE product_id = :product_id
 AND order_date BETWEEN :'start_date'::date
 AND :'end_date'::date;

$ psql -f report.sql \
$ -v product_id=120 \
$ -v start_date='2024-11-01' -v end_date='2024-11-30'
Product 120 does not exist

… à tout prix

Il est probable que les méta-commandes de psql ne viennent pas à bout de toutes les ingéniosités (et aberrations) que peuvent réserver les scripts compatibles avec SQL*Plus. Progressons encore avec une évolution plus complexe de notre exemple.

Notre utilisateur souhaite à présent obtenir un score de performance pour la période de vente de son produit, en comparant avec la période précédente. Nous aurions besoin ici d’un curseur pour réutiliser plusieurs fois la même requête de calcul des ventes ainsi que d’une fonction pour calculer le score de performance en gérant correctement la division possible par zéro.

-- sqlplus-report-03.sql
CONNECT user/password@database

DEF product_id = '&1'
DEF start_date = '&2'
DEF end_date = '&3'

SET serveroutput ON
SET feedback OFF
SET verify OFF

DECLARE
 p_id products.product_id%TYPE;
 p_sum NUMBER;
 p_prev_sum NUMBER;
 p_start DATE := TO_DATE('&start_date', 'YYYY-MM-DD');
 p_end DATE := TO_DATE('&end_date', 'YYYY-MM-DD');
 p_prev_start DATE := p_start - (p_end - p_start);
 p_prev_end DATE := p_start - 1;

 CURSOR c_orders (v_start DATE, v_end DATE) IS
 SELECT SUM(amount) AS total_amount
 FROM orders
 WHERE product_id = p_id
 AND order_date BETWEEN v_start AND v_end;

 FUNCTION score(p_sum NUMBER, p_prev_sum NUMBER)
 RETURN NUMBER IS
 v_score NUMBER;
 BEGIN
 RETURN ROUND((p_sum - p_prev_sum) / p_prev_sum * 100, 2);
 EXCEPTION
 WHEN ZERO_DIVIDE THEN
 RETURN NULL;
 END;

BEGIN
 SELECT product_id INTO p_id
 FROM products
 WHERE product_id = &product_id;

 OPEN c_orders(p_start, p_end);
 FETCH c_orders INTO p_sum;
 CLOSE c_orders;

 OPEN c_orders(p_prev_start, p_prev_end);
 FETCH c_orders INTO p_prev_sum;
 CLOSE c_orders;

 DBMS_OUTPUT.PUT_LINE('Total amount: ' || p_sum);
 DBMS_OUTPUT.PUT_LINE('Performance score: ' || score(p_sum, p_prev_sum));

EXCEPTION
 WHEN NO_DATA_FOUND THEN
 DBMS_OUTPUT.PUT_LINE('Product ' || &product_id || ' does not exist');
END;
/

QUIT

$ sqlplus -S /nolog @sqlplus-report-03.sql 20 2024-11-01 2024-11-30
Total amount: 1378.98
Performance score: 162.99

Bien que l’exemple soit volontairement simpliste et qu’il puisse faire appel à une fonction de fenêtrage, nous allons jouer le jeu de la conversion du script au plus proche de sa syntaxe originale. Pour cela, identifions les faiblesses du PL/pgSQL.

Les routines éphémères ne sont pas prises en charge

Le langage PL/pgSQL n’autorise pas la déclaration de fonctions ou de procédures stockées dont la portée serait exclusive au contexte d’exécution. La seule alternative est de définir globalement la routine, afin qu’elle soit connue de l’analyseur syntaxique et exécutée correctement. Dans le cas présent, je ne souhaite pas que la fonction persiste après l’appel de mon script. Qu’à cela ne tienne, nous pouvons créer une fonction temporaire dans le schéma pg_temp !

-- temp-function.sql
DO $$
BEGIN
 CREATE FUNCTION pg_temp.score(p_sum numeric, p_prev_sum numeric)
 RETURNS numeric LANGUAGE plpgsql AS $func$
 BEGIN
 RETURN ROUND((p_sum - p_prev_sum) / p_prev_sum * 100, 2);
 EXCEPTION
 WHEN division_by_zero THEN
 RETURN NULL;
 END;
 $func$;

 RAISE NOTICE 'Score: %', pg_temp.score(100.0, 50.0);
 RAISE NOTICE 'Score: %', pg_temp.score(100.0, 0);
END;
$$;

$ psql -f temp-function.sql
psql:temp-function.sql:16: NOTICE: Score: 100.00
psql:temp-function.sql:16: NOTICE: Score: <NULL>
DO

La fonction pg_temp.score(numeric, numeric) est dès lors accessible dans le reste de notre bloc anonyme, et ce, uniquement pour la durée de la session. La gestion des exceptions est conforme au besoin, il a suffit de remplacer ZERO_DIVIDE par division_by_zero comme le stipule la documentation.

La substitution ne s’applique pas dans un bloc anonyme

Comme nous l’avons vu précédemment, la substitution n’intervient pas lorsque nous nous trouvons dans un bloc de code PL/pgSQL. Pour contourner cette limitation, nous allons devoir utiliser les variables de session personnalisées mises à disposition pour l’écosystème d’extensions avec PostgreSQL.

Ces variables peuvent être manipulées aussi bien en psql avec le mot-clé SET qu’en SQL ou en PL/pgSQL avec les fonctions current_setting et set_config. La seule contrainte consiste à leur définir un préfixe qui n’entre pas en conflit avec celui d’autres variables déjà déclarées dans notre instance.

Pour revenir à notre exercice de conversion, cela signifie que nos paramètres de script peuvent être montés en variables de session dans les toutes premières instructions. Dès que nous sommes dans un bloc anonyme, il convient alors de les rappeler dans des variables classiques comme le montre le code suivant :

SET my.product_id = :product_id;
SET my.start_date = :start_date;
SET my.end_date = :end_date;

DO $$
DECLARE
 my_id int := current_setting('my.product_id')::int;
 p_start date := current_setting('my.start_date')::date;
 p_end date := current_setting('my.end_date')::date;
BEGIN
 ...
END;
$$;

Conversion complète

Toutes ces astuces mises bout à bout permet d’obtenir une nouvelle version du script, converti de PL/SQL à PL/pgSQL :

-- psql-report-03.sql
\set QUIET on

SET my.product_id = :product_id;
SET my.start_date = :'start_date';
SET my.end_date = :'end_date';

DO $$
DECLARE
 my_id int := current_setting('my.product_id')::int;
 p_id products.product_id%TYPE;
 p_sum numeric;
 p_prev_sum numeric;
 p_start date := current_setting('my.start_date')::date;
 p_end date := current_setting('my.end_date')::date;
 p_prev_start date := p_start - interval '1 day' * (p_end - p_start);
 p_prev_end date := p_start - interval '1 day';

 c_orders CURSOR (v_start date, v_end date) IS
 SELECT COALESCE(SUM(amount), 0)
 FROM orders
 WHERE product_id = p_id
 AND order_date BETWEEN v_start AND v_end;

BEGIN
 CREATE FUNCTION pg_temp.score(p_sum numeric, p_prev_sum numeric)
 RETURNS numeric LANGUAGE plpgsql AS $func$
 BEGIN
 RETURN ROUND((p_sum - p_prev_sum) / p_prev_sum * 100, 2);
 EXCEPTION
 WHEN division_by_zero THEN
 RETURN NULL;
 END;
 $func$;

 SELECT product_id INTO STRICT p_id
 FROM products
 WHERE product_id = my_id;

 OPEN c_orders(p_start, p_end);
 FETCH c_orders INTO p_sum;
 CLOSE c_orders;

 OPEN c_orders(p_prev_start, p_prev_end);
 FETCH c_orders INTO p_prev_sum;
 CLOSE c_orders;

 RAISE NOTICE 'Total amount: %', p_sum;
 RAISE NOTICE 'Performance score: %', pg_temp.score(p_sum, p_prev_sum);

EXCEPTION
 WHEN no_data_found THEN
 RAISE NOTICE 'Product % does not exist', my_id;
END;
$$;

$ psql -f psql-report-03.sql\
$ -v product_id=20 \
$ -v start_date='2024-11-01' -v end_date='2024-11-30'
psql:psql-report-03.sql:55: NOTICE: Total amount: 1378.98
psql:psql-report-03.sql:55: NOTICE: Performance score: 162.99

Conclusion

Convertir un script SQL*Plus pour qu’il devienne compatible avec l’outil psql de PostgreSQL est un exercice surmontable, pour peu que l’on connaisse les bonnes astuces et alternatives qui répondent au besoin initial. Bien sûr, une traduction un pour un, en conservant la syntaxe et un semblant de lisibilité, pourrait s’avérer plus ardue que l’exemple que j’ai concocté.

Je reste toujours sceptique face à celles et ceux qui souhaitent conserver ce genre de pratiques de développement, que je trouve obsolètes. Migrer vers PostgreSQL n’est-il pas l’occasion de moderniser sa base de code, ou de questionner son rapport à la technologie ? Dans notre exemple, comme je l’avais mentionné, il est possible d’obtenir le même résultat en une seule requête SQL, sans avoir à recourir à un bloc anonyme PL/pgSQL.

-- psql-report-04.sql
\pset footer off

SELECT NOT EXISTS(
 SELECT product_id
 FROM products
 WHERE product_id = :product_id
) AS unknown_product \gset

\if :unknown_product
 \echo 'Product' :product_id 'does not exist'
 \quit
\endif

SELECT :'end_date'::date - :'start_date'::date AS days \gset
SELECT :'start_date'::date - :days AS prev_start \gset

WITH periods AS (
 SELECT d AS start_date, d + :days * '1 day'::interval AS end_date
 FROM generate_series(:'prev_start'::date,
 :'start_date'::date,
 :days * '1 day'::interval) AS s(d)
), amounts AS (
 SELECT start_date, COALESCE(SUM(amount), 0) AS total_amount,
 LAG(SUM(amount), 1) OVER (ORDER BY start_date) AS prev_total_amount
 FROM orders
 JOIN periods ON order_date BETWEEN start_date AND end_date
 WHERE product_id = :product_id
 GROUP BY start_date
)
SELECT total_amount,
 ROUND((total_amount - prev_total_amount) /
 prev_total_amount * 100, 2) AS performance_score
 FROM amounts
 WHERE prev_total_amount IS NOT NULL;

$ psql -f psql-report-04.sql\
$ -v product_id=20 \
$ -v start_date='2024-11-01' -v end_date='2024-11-30'
 total_amount | performance_score
--------------+-------------------
 1378.98 | 162.99

Tous les scripts de cet article, ainsi que les commandes DDL pour construire le modèle de données, sont disponibles cette adresse.

Un assistant pour copier les données distantes

Florent Jardin — Tue, 28 May 2024 00:00:00 +0000

Lors de la dernière PGSession 16, j’ai rédigé et animé un atelier de trois heures au sujet de la migration vers PostgreSQL à l’aide des Foreign Data Wrappers, ou FDW. Ce fut notamment l’occasion de présenter au grand public, l’extension db_migrator pour laquelle j’ai dédié un article sur ce blog.

Au cours de cet atelier, nous pouvons constater que la copie des données avec l’extension db_migrator n’est pas parfaitement prise en charge. En effet, bien qu’il existe une fonction de bas niveau pour répartir sur plusieurs processus le transfert table à table, de nombreuses situations devront exiger de rédiger un grand nombre de requêtes SQL pour se tirer d’affaire. Au cours des mois qui suivirent, je me suis attelé à la conception d’un assistant écrit en PL/pgSQL dont le but est de simplifier la génération de ces requêtes.

Transfert des données sans assistant

Il n’y a pas de magie dans l’opération de copie des données à travers un Foreign Data Wrapper. Tout se résume à une série de requêtes INSERT qui doivent être exécutées dans un ordre prédéfini. Prenons les 16 tables du modèle de données très connu « Sakila » (disponible à cette adresse), pour illustrer le besoin de génération des requêtes de transfert.

Pour la pédagogie de cet article, je dispose d’une base de données PostgreSQL avec les deux schémas suivants que j’utiliserai dans mes démonstrations :

mysql : le schéma source contenant la définition des tables externes via l’extension mysql_fdw ;
public : le schéma cible où les données seront copiées.

Chaque table externe fait l’objet d’une étude rapide pour obtenir la bonne correspondance de type de colonne, et leur définition est conservée dans un fichier SQL à destination des équipes du projet. Par exemple, la table externe rental est définie comme suit :

CREATE FOREIGN TABLE mysql.rental (
 rental_id integer NOT NULL,
 rental_date timestamp without time zone NOT NULL,
 inventory_id integer NOT NULL,
 customer_id smallint NOT NULL,
 return_date timestamp without time zone,
 staff_id smallint NOT NULL,
 last_update timestamp without time zone NOT NULL
)
SERVER sakila_mysql
OPTIONS (
 dbname 'sakila',
 table_name 'rental'
);

Lors de la création de la table public.rental qui accueillera les données, il est opportun de décider si nous souhaitons mettre en place un partitionnement, chose que db_migrator est capable d’identifier et de mettre en place. Pour l’exemple, je reprends la structure stricte à l’aide de la syntaxe CREATE TABLE LIKE pour créer toutes mes tables cibles.

CREATE TABLE public.actor (LIKE mysql.actor);
CREATE TABLE public.address (LIKE mysql.address);
...

Avant même de mettre en place un générateur de requêtes INSERT, il est aisé d’entrevoir la forme de celles-ci. Chaque ligne de la table externe sera lue à travers un SELECT global, puis insérée dans la table cible. Le script de migration contient ainsi 16 instructions, une pour chaque table.

-- insert.sql
INSERT INTO public.actor SELECT * FROM mysql.actor;
INSERT INTO public.address SELECT * FROM mysql.address;
...
INSERT INTO public.store SELECT * FROM mysql.store;

Pour bénéficier de plusieurs processus, j’apprécie l’outil xargs qui permet de distribuer chaque ligne du fichier insert.sql sur une nouvelle session psql. Cette technique était présentée dans l’atelier de février, notamment pour paralléliser la construction des index et des clés primaires, définis dans un fichier SQL.

$ xargs -P 4 -a insert.sql -d '\n' -I % sh -c 'psql -c "%"'
INSERT 0 16
INSERT 0 603
...
INSERT 0 16044

C’est un peu rude, ça manque de verbosité, les requêtes SQL sont statiques. Bref, voyons la partie suivante pour découvrir ce que mon assistant peut apporter.

Démonstration de l’assistant

Contrairement à mes autres projets en PL/pgSQL, cet assistant n’est pas une extension et s’installe comme un vulgaire script. Une fois téléchargé, il suffit de l’invoquer sur la base de données de votre choix avec la commande suivante :

$ psql -d sakila -f fdw-assistant.sql

Le schéma par défaut se nomme assistant et contient une table de configuration sobrement appelée config. Pour chaque table à migrer, il suffit d’insérer une unique ligne qui servira d’élément de départ à la génération des requêtes de migration des données. On y retrouve dans la version actuelle les paramètres suivants :

source : la table externe qui contient les données à copier ;
target : la table cible où les données seront copiées ;
pkey : la colonne de clé primaire de la table cible ;
priority : les valeurs les plus faibles définissent les tables à traiter en premier ;
parts : le nombre de processus à lancer pour la copie des données ;
trunc : une option pour vider la table cible avant de copier les données ;
condition : une clause WHERE pour filtrer les données à copier ;
batchsize : le nombre de lignes à copier avant de réaliser un COMMIT intermédiaire.

Pour initialiser cette table en première intention, il est nécessaire de connaître a minima les colonnes de clé primaire de chaque table distante. En reportant les informations du diagramme relationnel de la base Sakila, nous pouvons remplir la table config de la façon suivante :

INSERT INTO assistant.config (source, target, pkey)
VALUES
 ('mysql.actor', 'public.actor', 'actor_id'),
 ('mysql.address', 'public.address', 'address_id'),
 ...
 ('mysql.store', 'public.store', 'store_id');

Pour chaque transfert, nous indiquons la table source et la table cible, ainsi que la colonne de clé primaire. Cette dernière est requise pour trier les lignes, découper le transfert en plusieurs lots (batchs) et redémarrer le transfert en cas d’interruption.

À l’aide de cette configuration, nous pouvons passer à la planification. Les tables stage et job sont alimentées avec de nouveaux éléments qui serviront au pilotage et au suivi des différents transferts à déclencher.

SELECT * FROM assistant.plan();

 target | invocation
---------------+--------------------------
 customer | CALL assistant.copy(1);
 address | CALL assistant.copy(2);
 ...
(16 rows)

Une vue nommée report permet de suivre l’avancement des différentes étapes en joignant les tables stage et job. Elle donne notamment des éléments très utiles pour suivre l’avancement et le débit des transferts.

SELECT target, state, rows FROM assistant.report WHERE stage_id = 1;

 target | state | rows
---------------+---------+------
 rental | pending | 0
 actor | pending | 0
 ...
(16 rows)

Les lignes retournées par la commande plan() peuvent alors être invoquées les unes après les autres avec la méta-commande \gexec de psql, ou alors en reprenant la technique du fichier et la distribution des requêtes avec xargs.

L’appel à la méthode copy() se charge de construire l’instruction INSERT relative à la copie des données d’une table distante vers une table locale. Par exemple, pour la table customer, le résultat de l’appel sera le suivant :

CALL assistant.copy(1);

NOTICE: Executing: TRUNCATE public.customer
NOTICE: Executing: SELECT count(customer_id) FROM mysql.customer
 WHERE customer_id > 0
NOTICE: Executing: INSERT INTO public.customer
 SELECT customer_id, store_id, first_name, last_name, email,
 address_id, active, create_date, last_update
 FROM mysql.customer
 WHERE customer_id > 0 ORDER BY customer_id
CALL

À l’issue du transfert, la vue report nous fait un résumé de l’opération.

SELECT * FROM assistant.report
 WHERE stage_id = 1 AND target = 'public.customer'::regclass;

-[ RECORD 1 ]-------------------------
stage_id | 1
target | public.customer
job_start | 2024-05-28 10:19:18.334917
state | completed
rows | 599
total | 599
elapsed | 00:00:00.081273
rate | 7370.22
progress | 1.00
eti | 00:00:00
eta | 2024-05-28 10:19:18.334917

Distribution sur plusieurs processus

Au fur et à mesure de la conception de l’assistant, j’ai éprouvé le besoin d’enrichir les requêtes sous-jacentes pour répondre à d’autres cas d’usage, récurrents dans le domaine de la migration de données. Parmi ceux-ci, on y retrouve la capacité de répartir les lignes d’une même table sur plusieurs sessions, chacune disposant d’une clause WHERE basé sur le résultat de la division euclidienne (modulo) de la clé primaire.

Pour activer cette fonctionnalité, il suffit de renseigner le paramètre parts dans la table config. Par exemple, pour la table film, nous pouvons définir :

UPDATE assistant.config SET parts = 4 WHERE target = 'public.film'::regclass;

Cette configuration prend effet lors de la prochaine planification. L’appel à la méthode plan() insère alors quatre lignes dans la table job pour la table film, chacune rattachée à une valeur comprise entre 0 et 3. La colonne condition est alors enrichie pour les lignes de la table task en vue de l’étape suivante.

SELECT invocation FROM assistant.plan('{public.film}');

 invocation
--------------------------
 CALL assistant.copy(17);
 CALL assistant.copy(18);
 CALL assistant.copy(19);
 CALL assistant.copy(20);
(4 rows)

SELECT job_id, job.target, state, part, condition
 FROM assistant.job JOIN assistant.task USING (job_id)
 WHERE stage_id = 2;

 job_id | target | state | part | condition
--------+--------+---------+------+-----------------
 17 | film | pending | 0 | film_id % 4 = 0
 18 | film | pending | 1 | film_id % 4 = 1
 19 | film | pending | 2 | film_id % 4 = 2
 20 | film | pending | 3 | film_id % 4 = 3

Lors de l’appel à la méthode copy(), l’assistant construit les requêtes INSERT sur la base des conditions précédemment définies. Par exemple, pour la première partie de la table film, la trace indique les requêtes INSERT qui ont été générées.

CALL assistant.copy(17);

NOTICE: Executing: TRUNCATE public.film
NOTICE: Executing: SELECT count(film_id) FROM mysql.film
 WHERE film_id > 0 AND film_id % 4 = 0
NOTICE: Executing: INSERT INTO public.film
 SELECT film_id, title, description, release_year,
 language_id, original_language_id, rental_duration,
 rental_rate, length, replacement_cost, rating,
 special_features, last_update
 FROM mysql.film WHERE film_id > 0 AND film_id % 4 = 0
 ORDER BY film_id
CALL

L’opération TRUNCATE intervient uniquement pour la session dont la valeur de part est égale à 0. Dans le cas nominal, cette session est lancée avant toutes les autres pour respecter le comportement attendu dans la configuration avec la colonne trunc (true par défaut).

L’intérêt évident de cette méthode est d’obtenir le meilleur débit d’insertion pour une table donnée, en reposant sur la puissance d’extraction du serveur distant et la capacité d’écriture du serveur local. Le débit peut être consulté avec la vue report, notamment pour comparer deux chargements pour une même table, comme l’exemple de la table film. La colonne rate est exprimée en nombre de lignes par seconde.

SELECT stage_id, target, state, rate FROM assistant.report
 WHERE target = 'public.film'::regclass;

 stage_id | target | state | rate
----------+-------------+-----------+----------
 1 | public.film | completed | 19162.59
 2 | public.film | completed | 51389.37

Reprise après interruption

La capacité de pouvoir relancer une copie par lot en cas d’interruption est une des raisons pour lesquelles la clé primaire doit être renseignée dans la configuration. L’assistant s’appuie sur la dernière valeur de clé primaire extraite (à l’aide d’une clause RETURNING) pour connaître le prochain point de reprise. Dans la conception de cette fonctionnalité, il m’a fallu arbitrer sur les limitations qu’impose ce mécanisme.

Les clés primaires ne doivent pas être composées, car la clause RETURNING ne peut retourner qu’une seule valeur ;
Les tables dont la clé primaire est composée ne peuvent pas bénéficier du traitement par lot, et donc de la reprise après interruption ;
Les données sont systématiquement triées lors de l’extraction, même si le traitement par lot n’est pas activé ;
La colonne de la clé primaire doit être de type numérique.

L’activation d’un traitement par lot consiste à mettre à jour la colonne batchsize de la table de configuration. Prenons l’exemple de la table rental :

UPDATE assistant.config SET batchsize = 1000
 WHERE target = 'public.rental'::regclass;

SELECT invocation FROM assistant.plan('{public.rental}');

 invocation
--------------------------
 CALL assistant.copy(21);
(1 row)

Le transfert des données de la table rental est alors découpé en lots de 1000 lignes. Il est bien sûr possible de combiner cette technique avec la parallélisation, la clause WHERE réalisera l’essentiel du travail de répartition pour empêcher que la même ligne soit exportée deux fois.

CALL assistant.copy(21);

TRUNCATE public.rental
SELECT count(rental_id) FROM mysql.rental WHERE rental_id > 0
INSERT INTO public.rental SELECT rental_id, ...
 FROM mysql.rental WHERE rental_id > 0 ORDER BY rental_id LIMIT 1000
...
...
INSERT INTO public.rental SELECT rental_id, ...
 FROM mysql.rental WHERE rental_id > 16005 ORDER BY rental_id LIMIT 1000
INSERT INTO public.rental SELECT rental_id, ...
 FROM mysql.rental WHERE rental_id > 16049 ORDER BY rental_id LIMIT 1000
CALL

Dès qu’une requête ne retourne plus aucune ligne, l’assistant considère que le transfert est terminé. La table job est mise à jour à chaque itération pour suivre la dernière valeur de la séquence de clé primaire.

SELECT target, lastseq FROM assistant.job
 WHERE stage_id = 3 AND target = 'public.rental'::regclass;

 target | lastseq
---------------+---------
 public.rental | 16049

En cas d’interruption, il est possible de relancer le transfert en appelant la méthode copy() avec le même identifiant de tâche. L’assistant se charge de reprendre le transfert à partir de la dernière valeur de clé primaire connue.

CALL assistant.copy(21);

NOTICE: Executing: SELECT count(rental_id) FROM mysql.rental
 WHERE rental_id > 16049
NOTICE: Executing: INSERT INTO public.rental SELECT rental_id, ...
 FROM mysql.rental WHERE rental_id > 16049
 ORDER BY rental_id LIMIT 1000
CALL

Conclusion

La conception d’un tel outil était un petit défi personnel dans la droite lignée de mes recherches autours de la migration vers PostgreSQL avec l’aide exclusive des Foreign Data Wrappers. Ma principale source d’inspiration reste le projet Ora2Pg, l’un des outils open-source le plus complet à ce jour.

J’ai conscience des limites techniques de cet assistant, et du bricolage qu’il reste à mettre en place pour faciliter la vie d’un consultant comme moi. Dans un autre article, j’aimerais présenter un autre outil nommé dispatch que je maintiens depuis quelque temps et avec lequel je réponds aux questions d’orchestration et traçabilité des étapes de la migration.

En prenant un peu de recul, les concepts de base sont là, n’importe quel autre outil dans d’autres langages pourrait parfaitement émerger et enrichir l’écosystème open-source dans la quête de la migration vers PostgreSQL.

Les modes de transfert dans une migration

Florent Jardin — Wed, 11 Oct 2023 00:00:00 +0000

En informatique, un projet de migration consiste à changer un ou plusieurs composants techniques sans qu’aucun comportement des applications n’en soit impacté. Dans le paysage des bases de données (et le métier que j’exerce), il s’agira de choisir un nouveau système (comme PostgreSQL) en remplacement d’un autre (comme Oracle ou Microsoft SQL Server).

Dans un précédent article, je décrivais les étapes exhaustives pour réaliser une migration complète à l’aide de la technologie des Foreign Data Wrappers, mais l’étape critique de transfert des données qui y était décrite ne s’adapte pas à toutes les situations. Voyons ensemble les alternatives qui permettent de couvrir une grande partie des besoins.

Les illustrations de cet article reprennent un schéma simple de chantier de migration où l’on transfère les données d’un système entre deux centres de données (dc1 vers dc2). Dans la situation où les données ne sortent pas de l’infrastructure de l’hébergeur, il s’agit d’un simple transfert de deux serveurs distincts.

Transfert sans réseau

Plusieurs raisons peuvent justifier que les deux serveurs ne soient pas en connexion directe de l’un à l’autre. Comme l’interdiction d’ouvrir l’accès à l’instance source depuis Internet ou la complexité de configurer un lien sécurisé (VPN) entre les deux infrastructures.

Dans ce genre de scénario, il devient nécessaire de déverser les données en dehors de la base en garantissant la cohérence de ces dernières. Une sauvegarde physique de la base ou un export au format SQL sont des moyens fiables pour consolider une archive complète de la base.

L’étape de transfert est opérée selon l’imagination des équipes. Le plus simple reste le transfert sur un dépôt SFTP mis à disposition par le deuxième datacenter ou tout autre protocole qui contrôle l’intégrité de l’archive une fois transférée. La méthode la plus improbable que j’ai pu observer, était le déplacement physique d’une copie de l’archive par une société spécialisée de coursiers, en voiture, en scooter, ou en avion selon la distance à parcourir.

Une fois l’archive réceptionnée par les équipes et jugée intègre, il peut être nécessaire d’importer les données dans une base tampon, pour peu que le format de fichiers (SQL ou propriétaire) ne soit pas encore compatible avec PostgreSQL. Dès ce moment précis, il est alors possible d’importer les données dans la base cible en respectant l’ordre de créations des objets et l’insertion des données.

Bilan de l’opération :

Temps d’interruption très élevé (de plusieurs heures à plusieurs jours) ;
Complexité de mise en œuvre faible avec les bons outils ;
Risque sur la cohérence des données très faible si les contrôles d’intégrité sont réalisés à chaque étape.

Transfert avec intermédiaire

Lorsque les systèmes sont hébergés au même endroit, la mise en place de règle de routage permet plus aisément de rendre possible la connexion entre les deux serveurs. Parmi les outils de migration, on retrouve la famille des ETL (pour Extract Transform Load) qui font office d’intermédiaire entre les deux bases de données.

Ces outils fournissent une grande quantité de pilotes de connexion ainsi que des méthodes de transformation de la donnée pour orchestrer la migration sans avoir besoin d’exporter la moindre table dans un fichier plat. L’essentiel du travail est donc réalisé en mémoire et à l’aide de plusieurs processeurs pour accélérer les opérations de transfert.

Bien que spécialisé pour les migrations vers PostgreSQL, je range l’outil libre Ora2Pg dans la catégorie des ETL. Il répond exactement à la définition précédente en ouvrant plusieurs connexions sur l’instance source pour lire les table par paquet de 10 000 lignes (directive DATA_LIMIT) et en ouvrant d’autres connexions sur l’instance cible pour les insérer avec des instructions COPY, grâce à la méthode pg_putcopydata du pilote DBD::Pg.

Bilan de l’opération :

Temps d’interruption élevé (plusieurs heures) ;
Complexité de mise en œuvre faible avec les bons outils ;
Risque sur la cohérence des données très faible.

Transfert en direct

Ce mode devrait vous paraître familier si vous êtes des habitué·es de mes articles (abonnez-vous) car le transfert direct entre un système tiers et PostgreSQL repose sur la technologie des Foreign Data Wrappers.

Cette solution permet d’ouvrir un canal direct entre l’instance PostgreSQL et l’instance distante par le biais de tables externes. Ainsi, il devient possible de consulter les données avec le langage SQL, pour peu qu’un wrapper ait été développé pour communiquer avec le bon pilote.

Les opérations d’extraction, de transfert et d’insertion sont réalisées dans la même transaction : il s’agit d’une bête requête INSERT INTO SELECT. Cette méthode est bien plus rapide que le mode précédent puisque l’on se débarrasse d’un intermédiaire coûteux en ressources (ETL).

Bien que séduisante, la copie par wrapper peut être particulièrement lente pour les données larges (comme les BLOB d’Oracle) car celles-ci ont une structure différente. Il est alors nécessaire de mixer les solutions : l’une avec un transfert direct pour les tables sans données larges, et l’autre avec un ETL pour optimiser plus finement le volume de lignes et la quantité de mémoire à allouer.

Bilan de l’opération :

Temps d’interruption élevé (de plusieurs minutes à plusieurs heures) ;
Complexité de mise en œuvre faible voire élevée pour les données larges ;
Risque sur la cohérence des données très faible.

Transfert avec rattrapage partiel

Pour de très hautes volumétries où l’interruption de service doit être la plus faible possible, les solutions citées plus haut peuvent être très limitantes. En effet, exporter/importer la totalité des données est une étape longue et incontournable.

Ce que j’appelle le transfert avec « rattrapage partiel » consiste à identifier les tables les plus volumineuses dont la plupart des lignes sont mortes. Il faut avoir l’assurance qu’aucune modification de type UPDATE ou DELETE n’ait lieu auprès de l’équipe de développement et que la table présente une clé primaire dont les nouvelles valeurs lors d’une insertion sont toujours supérieures à la précédente.

Ainsi, une première copie des données peut être réalisée à chaud, sans interruption de service où seules les lignes mortes seront déplacées vers le nouveau système. Selon la proportion sur le volume complet, cette étape peut faire économiser des dizaines d’heures à l’opération finale. En complément des opérations de transfert, il est nécessaire de maintenir un registre des valeurs de clé primaire qui permet de séparer les données mortes des données vivantes (ou à venir). Pour chaque table, cette valeur sera une sorte de point de reprise pour la phase de rattrapage.

Lors de l’étape cruciale de bascule, toutes les tables vivantes seront intégralement copiées et les lignes des tables mortes dont la clé est supérieure à la valeur mémorisée seront sélectionnées puis insérées dans leur table respective. Une étude préalable doit déterminer si les index méritent d’être créés lors de la première ou de la seconde étape de transfert, en fonction du temps effectif qu’ils font perdre ou gagner sur l’opération dans sa globalité.

Bilan de l’opération :

Temps d’interruption faible (plusieurs dizaines de minutes) ;
Complexité de mise en œuvre élevée ;
Risque sur la cohérence des données élevé si l’équipe de développement n’apporte pas toutes les garanties suffisantes dans le choix des tables mortes.

Transfert avec rejeu des transactions

Parler de « rejeu des transactions » revient très sobrement à parler de réplication physique ou de réplication logique. Chaque système propose des mécanismes qui lui sont propres et les outils à mettre en place peuvent donc varier. Je vous invite à vous pencher sur de brillants projets comme ora_migrator qui implémente une réplication par triggers avec Oracle et pg_chameleon qui décode les journaux de transactions de MySQL.

L’intérêt principal de ce mode de transfert repose sur la capacité du système à journaliser (logging) toutes les modifications qui lui ont été demandées et de les renseigner dans une succession de transactions. Ainsi, entre un instant T0 et un instant T1, il devient possible de reproduire l’ensemble des changements pour atteindre un état cohérent et fidèle.

Dans ce scénario, l’opération requiert un chargement intégral et cohérent des données dans la base cible. Cette phase d’initialisation se réalise sans interruption de service mais nécessite un soin particulier dans la supervision des disques ou les alertes du système source, car la capture des données provoque le maintien d’un instantané (snapshot) qui peut devenir coûteux si le transfert s’éternise.

À l’issue de l’initialisation, le rejeu peut démarrer à chaud sans pénaliser l’activité de la base source de production. L’outil consomme chaque événement dans l’ordre d’arrivée pour le transformer en écriture (INSERT, UPDATE ou DELETE) dans la base PostgreSQL. L’opération de bascule consiste alors à interdire toute nouvelle modification sur le système source, attendre la fin du rejeu et changer les chaînes de connexions pour que les applications se connectent sur la nouvelle base PostgreSQL.

Bilan de l’opération :

Temps d’interruption très faible (quelques secondes) ;
Complexité de mise en œuvre élevée voire très élevée selon les solutions retenues ;
Risque sur la cohérence des données très élevé si l’outil tombe en erreur pour une transaction qu’il ne parvient pas à décoder lors de l’étape de rejeu.

Le choix est libre

Cette revue complète et exhaustive me hantait depuis quelque temps, et il me semblait nécessaire de mettre en lumière les différentes contraintes que présente un projet de migration. Dans la sphère des consultants que je fréquente et des projets libres que je surveille activement, j’essaie de me convaincre qu’il peut exister une solution universelle, capable d’adresser chaque besoin et situation qui ont été dépeints dans cet article.

J’ai délibérément évité de parler du projet Debezium, car il repose sur de nombreuses briques techniques comme Kafka, Java et une myriade de connecteurs. Et bien qu’une conférence à ce sujet m’ait tenu en haleine en juin dernier, je n’ai pas encore eu l’occasion de mener un projet d’envergure qui justifiait un tel investissement humain dans sa mise en œuvre.

Les outils libres ou payants sont nombreux, tous n’ont pas la même vocation ni la même philosophie. Privilégier l’un plutôt qu’un autre revient aux équipes en charge de la migration et de leur maturité technique mais au final, le choix est libre !

En route vers la liberté avec db_migrator

Florent Jardin — Fri, 28 Jul 2023 00:00:00 +0000

J’ai passé plusieurs semaines ces derniers mois à contribuer à l’extension db_migrator. Rédigée uniquement en PL/pgSQL, elle permet de migrer les schémas et les données d’un système de bases de données vers PostgreSQL à l’aide des données externes que j’avais déjà présentées il y a quelques années.

Dans cet article, je présente le fonctionnement de l’outil, sa philosophie et la raison d’être que je lui ai trouvée, alors même qu’il rejoint l’écosystème des projets libres déjà bien installés dans le paysage de la migration. Que vaut-il aux côtés d’Ora2Pg ou de pgloader ?

db_migrator entre dans l’arène

Mon intérêt pour ce projet remonte à décembre dernier, alors qu’un collègue de chez Dalibo nous laissait en héritage un outil similaire avec lequel il lui était possible de copier les données d’instances Oracle ou Sybase à l’aide de la technologie des Foreign Data Wrappers (FDW). Bien que cet outil soit resté en alpha, beaucoup de bonnes idées y ont été expérimentées en interne.

La promesse des FDW réside dans le respect de la norme SQL/MED, à savoir qu’une instance PostgreSQL puisse s’interfacer sur un autre système de stockage et en manipuler les données à travers les tables externes avec de simples requêtes SQL. Ainsi, pour peu qu’une communauté ait développé le wrapper, il est possible de consulter un catalogue distant, reproduire la structure des tables, ses relations et ses contraintes, et de rapatrier les données vers PostgreSQL.

Et db_migrator entre dans l’arène.

Rendue publique en novembre 2019 par Laurenz Albe, connu pour sa contribution active sur PostgreSQL depuis des décennies et également pour le développement de oracle_fdw, l’extension se présente comme un outil générique avec lequel il faut employer des plugins pour la prise en charge des FDW. Il est aisé d’en créer de nouveaux, comme j’ai pu m’en rendre compte avec le plugin mysql_migrator, écrit en quelques jours, grâce à la documentation très complète de l’API des plugins.

Après avoir installé les extensions avec make install ainsi que le FDW du bon système, il est nécessaire de créer les objets dans la base de données qui va contenir les futurs schémas et leurs données.

CREATE EXTENSION mysql_fdw;
CREATE EXTENSION mysql_migrator CASCADE;

CREATE SERVER mysql FOREIGN DATA WRAPPER mysql_fdw
 OPTIONS (host 'mysql_db', fetch_size '1000');
CREATE USER MAPPING FOR PUBLIC SERVER mysql
 OPTIONS (username 'root', password 'password');

L’opération de migration peut être réalisée en une seule commande pour les cas les plus simples (pas de procédure stockée, ni de types de colonnes exotiques) avec la méthode db_migrate(). Sinon, en plusieurs étapes, s’il est nécessaire de faire des ajustements comme le changement du type de colonne ou le retrait d’une table dans le schéma cible.

Lors du développement de l’extension mysql_migration, je suis parti de la base d’exemple Sakila fournie par MySQL afin d’avoir une complexité exhaustive. La première étape consiste à créer deux schémas internes, l’un avec des tables externes fournies par le plugin, l’autre avec des tables de catalogue que l’on peut éditer avant que l’extension ne poursuive la migration.

SELECT db_migrate_prepare(
 plugin => 'mysql_migrator',
 server => 'mysql',
 only_schemas => '{sakila}'
);

Cette partie peut être relativement longue, puisqu’elle va permettre de rapatrier le modèle de données, que j’appelle le catalogue, sous la forme de plusieurs tables qui décrivent la structure des tables, le nom des colonnes ou les contraintes qui leur sont associées. L’extension importe également les sources de toutes les procédures stockées, les fonctions, les vues, mais ne réalise pas leur conversion en PL/pgSQL (vous ne vous rendez pas compte du travail que cela représente).

Dans le cas de la migration de la base Sakila, il est nécessaire de faire plusieurs modifications du catalogue. Comme le reste avec cette extension, toute la préparation se réalise en SQL, ce qui rend facile l’automatisation avec un unique script en guise de configuration.

/* exclude bytea columns from migration */
DELETE FROM pgsql_stage.columns WHERE type_name = 'bytea';

/* quote character expression */
UPDATE pgsql_stage.columns
 SET default_value = quote_literal(default_value)
 WHERE NOT regexp_like(default_value, '^\-?[0-9]+$')
 AND default_value <> 'CURRENT_TIMESTAMP';

/* disable view migration */
UPDATE pgsql_stage.views SET migrate = false;

On pourrait bien sûr aller plus loin, comme réinjecter la définition des vues réécrites dans la table pgsql_stage.views ou activer la migration des procédures en changeant la colonne migrate de la table pgsql_stage.functions. Mais progressons avec l’étape suivante.

SELECT db_migrate_mkforeign(
 plugin => 'mysql_migrator',
 server => 'mysql'
);

SELECT db_migrate_tables(
 plugin => 'mysql_migrator'
);

La première méthode db_migrate_mkforeign() va se charger de créer les schémas et les séquences, puis les tables étrangères avec les colonnes au regard des ajustements précédents. Ensuite, l’étape la plus cruciale, on exécute la fonction db_migrate_tables() : les tables vierges sont créées avec leurs partitions si besoin, et pour chacune d’entre elles, débute alors la copie des données avec l’instruction INSERT INTO SELECT *.

Les autres objets, tels que les index ou les contraintes, disposent de leur propre méthode. Il est nécessaire de créer les fonctions avant ces derniers si vous êtes confronté à des index fonctionnels ou que sais-je.

SELECT db_migrate_functions(plugin => 'mysql_migrator');
SELECT db_migrate_triggers(plugin => 'mysql_migrator');
SELECT db_migrate_views(plugin => 'mysql_migrator');
SELECT db_migrate_indexes(plugin => 'mysql_migrator');
SELECT db_migrate_constraints(plugin => 'mysql_migrator');

Il se pourrait que ce mécanisme change à l’avenir, notamment si je parviens à concrétiser cette issue qui permettrait de découper les méthodes db_migrate_*() en de plus petites étapes.

La fin de la migration consiste à supprimer les schémas temporaires dans lesquels se trouvaient les tables du catalogue.

SELECT db_migrate_finish();

Raison d’être de l’extension

Comme je le disais en introduction, c’est assez surprenant de voir un nouvel outil de migration émerger en 2023 (la version 1.0.0 est sortie en janvier avec mon patch sur l’ajout du partitionnement). Dans le paysage open-source, nous pouvons parler d’Ora2Pg qui a sorti en juillet sa version 24.0 avec le support de SQL Server ou bien de pgloader qui a une excellente réputation.

De très nombreux projets sont listés sur le wiki communautaire. Certains sont spécialisés pour un seul système, d’autres en migrent plusieurs. Une très grande majorité d’entre eux sont propriétaires ou n’ont plus de contribution récente. La plupart sont des boîtes noires et leur documentation peut paraître cryptique, voire quasi inexistante.

L’écosystème est riche, je ne prétends pas tous les connaître, mais j’ai une intuition que je me forge depuis quelques années. L’économie mondiale est en surchauffe. Certaines sociétés se portent bien, d’autres font des coupes budgétaires. La transition vers un système libre et sans licence commerciale comme PostgreSQL est toujours d’actualité, peut-être même plus urgente aujourd’hui en comparaison à la décennie qui vient de s’écouler.

Et pourtant, avec mes lunettes de DBA, je ne me satisfais pas encore des outils qui existent. J’aimerais qu’il y ait une nouvelle alternative, quelque chose d’universel et à portée de tout le monde. Si je me tourne aujourd’hui vers db_migrator, ce serait pour les principaux atouts suivants :

Une implémentation bas niveau au plus près de l’instance : avec le PL/pgSQL comme langage exclusif. Cela n’aurait pas été possible bien sûr sans le développement prolifique des Foreign Data Wrappers pour un grand nombre de systèmes ;
Une très grande flexibilité de configuration : puisque les ajustements se font avec des requêtes UPDATE ou DELETE sur le catalogue. Pour peu que l’on soit à l’aise avec le modèle de ce dernier, il devient facile de changer un comportement sans consulter une documentation technique sur les options qui se présentent à nous ;
Une liberté dans l’orchestration : à ce jour, les exécutions sont déclenchées de façon séquentielle pour les index et les contraintes, mais l’architecture de l’outil pourrait permettre que des outils externes soient responsables de consommer les résultats de l’extension et de déclencher les opérations en parallèle ;
Les plugins sont libres d’enrichir la migration : si une opération n’est pas générique, il est tout à fait possible de fournir une méthode supplémentaire à l’aide du plugin. C’est le cas de la copie incrémentale (et ses fonctions de réplication) du plugin ora_migrator ou bien la conversion des auto-incréments en colonnes d’identité avec le plugin mysql_migrator.

Le chemin vers la liberté me semble encore long pour prétendre faire la moitié de ce que propose déjà Ora2Pg, à commencer par la conversion automatique qui n’est pas du tout à l’ordre du jour. Mais avec de petites avancées, régulières et réfléchies, qui sait ?