Connecteurs de bases de données

Ce qu'il faut installer sur le serveur pour se connecter à PostgreSQL, MySQL, Apache Doris, SQL Server ou Oracle, et comment le préparer sur un serveur sans accès à internet.

En résumé

Pour joindre une base distante, le serveur Linkr s’appuie sur des extensions DuckDB, et pour Apache Doris sur un pilote Python optionnel. SQL Server et Oracle passent par des extensions communautaires, que DuckDB ne vérifie pas. L’image Docker contient tout. En installation manuelle, les extensions se téléchargent à la première connexion, sauf les communautaires, qu’on installe sciemment : sur un serveur sans accès à internet, il faut toutes les installer avant, avec une commande.

Client Backend

Ce que demande chaque connecteur

DuckDB est le moteur de requêtes de Linkr. Il se connecte aux autres bases par des extensions — de petits modules qu’il télécharge la première fois qu’il en a besoin, puis garde dans le dossier de données.

Moteur	Ce qu’il faut sur le serveur	Image Docker	Ports à ouvrir vers la base
DuckDB, dossier de Parquet	rien	✓	—
SQLite	extension `sqlite`	✓	—
PostgreSQL	extension `postgres`	✓	5432 par défaut
MySQL	extension `mysql`	✓	3306 par défaut
Apache Doris	extension `mysql`, et l’extra Python `doris` pour les gros résultats	✓	9030 (port de requête du FE) ; 8070 (Arrow Flight SQL) et les BE pour les gros résultats
SQL Server	extension communautaire `mssql`	✓	1433 par défaut
Oracle	extension communautaire `oracle_scanner` (aucun client Oracle requis)	✓	1521 par défaut

Les fichiers Excel (.xlsx) importés en mode serveur passent aussi par une extension, excel.

L'extra « postgres » ne sert pas à se connecter à PostgreSQL

L’installation manuelle propose apps/api[dev,postgres]. Cet extra sert à ranger la base applicative de Linkr dans PostgreSQL (voir Configuration). Pour interroger un entrepôt PostgreSQL, il ne faut que l’extension DuckDB postgres.

SQL Server et Oracle : des extensions communautaires

Les connecteurs SQL Server (mssql) et Oracle (oracle_scanner) sont des extensions communautaires : écrites et maintenues par des tiers, publiées sur le dépôt communautaire de DuckDB, mais ni vérifiées ni garanties par DuckDB Labs. Linkr ne les télécharge donc jamais de lui-même : un administrateur les installe en connaissance de cause (ci-dessous), et d’ici là une base SQL Server ou Oracle échoue en le lui indiquant. Chacune fournit aussi des fonctions capables d’écrire dans la base ; Linkr les refuse dans les requêtes et n’accepte qu’un login en lecture seule, vérifié à chaque connexion.

Avec Docker

Rien à faire : l’image embarque les extensions et le pilote Doris, précisément pour fonctionner sans accès à internet. Il reste à ouvrir, depuis le conteneur de l’API, les ports de la base à joindre.

En installation manuelle

Les extensions DuckDB, sans accès à internet

Sur une machine connectée, la première connexion à une base télécharge l’extension depuis extensions.duckdb.org et personne ne s’en aperçoit. Sur un serveur coupé d’internet — un espace projet d’entrepôt de santé, par exemple — cette première connexion échoue sur une erreur de téléchargement.

Installez-les donc une fois, depuis la racine du dépôt, après avoir installé le backend :

npm run duckdb:extensions

Elles sont rangées dans le dossier de données (LINKR_DATA_DIR, sous _duckdb_ext), là où Linkr les cherche. Si le serveur n’a aucun accès à extensions.duckdb.org, deux solutions :

Un miroir : si votre établissement dispose d’un dépôt de type Nexus ou Artifactory, il peut relayer http://extensions.duckdb.org. Indiquez son adresse :
```
npm run duckdb:extensions -- --repository https://nexus.exemple.fr/repository/duckdb-extensions
```
Une copie : lancez la commande sur une machine connectée, avec le même système et la même version de DuckDB que le serveur, puis copiez son dossier _duckdb_ext dans le dossier de données du serveur.

SQL Server et Oracle

Leurs extensions communautaires ne s’installent que sur demande :

npm run duckdb:extensions -- --community

Sans accès à internet, --community-repository désigne un miroir de http://community-extensions.duckdb.org, comme --repository pour les autres. L’extension Oracle parle elle-même le protocole d’Oracle : pas d’Oracle Instant Client à installer.

Donnez ensuite à chaque utilisateur de Linkr un login en lecture seule ; Linkr refuse les autres :

SQL Server : un login membre de db_datareader (ou titulaire de droits SELECT), et d’aucun rôle qui écrit (db_datawriter, db_ddladmin, db_owner, sysadmin). La connexion est toujours chiffrée, mais la version de l’extension qu’utilise Linkr aujourd’hui ne vérifie pas le certificat du serveur : gardez SQL Server sur le réseau privé de la SPE.
Oracle : un login avec CREATE SESSION et SELECT sur les tables du schéma de l’entrepôt, qui ne possède lui-même aucune table — pas le propriétaire du schéma. Le formulaire prend le nom de service (par ex. FREEPDB1) et le schéma à lire.

Les requêtes de Linkr sont calculées par Oracle : comptages, statistiques, cohortes, données patient, catalogue de données et console SQL sont traduits en SQL Oracle et exécutés par Oracle via son pilote Python officiel (python-oracledb, qui ne demande pas non plus de client Oracle), dans une transaction en lecture seule. Ce qu’Oracle répondrait autrement (la concaténation de textes, entre autres) est calculé par Linkr, si bien qu’une réponse ne change jamais. Le SQL que vous écrivez dans les éditeurs, notebooks ou pipelines lit en revanche ses tables en entier : adapté à un datamart, lent sur un gros entrepôt.

La console SQL de la page de la base propose aussi le SQL Oracle natif : la requête part telle qu’écrite, avec ses indications à l’optimiseur ou ses fonctions propres à Oracle, dans une transaction en lecture seule. Linkr refuse les liens vers d’autres bases (@), le PL/SQL et les paquets qui sortent de la base (UTL_*, DBMS_*…).

Un index qui change tout. Un critère de cohorte limité au séjour (« séjours avec un lactate > 2 ») cherche, pour chaque séjour, les événements de son patient entre ses dates. Avec un index sur (person_id, date de début) de chaque table d’événements (condition_occurrence, drug_exposure, measurement…), Oracle lit directement ces événements : sur 25 000 patients Synthea, un tel critère passe de 45 s à moins de 3 s. Si l’entrepôt ne l’a pas, demandez-le à l’administrateur de la base.

Le pilote Arrow Flight SQL pour Apache Doris

Linkr se connecte à Doris par le protocole MySQL, qui suffit pour les comptages et les statistiques. Les résultats volumineux — une extraction de plusieurs millions de lignes — sont en revanche beaucoup plus rapides par Arrow Flight SQL, un protocole conçu pour transférer des données en masse. Il demande un pilote Python, l’extra doris :

pip install -e "apps/api[dev,doris]"

Sans lui, tout fonctionne, mais lentement pour les gros résultats, et la page de la base l’indique : « Le serveur Linkr ne peut pas utiliser Arrow Flight SQL (son extra « doris » n’est pas installé)… ». Arrow Flight SQL demande aussi que le port arrow_flight_sql_port du FE (8070 par défaut) et chaque BE soient joignables depuis le serveur Linkr.

Les extras se combinent : apps/api[dev,postgres,doris].

Pour aller plus loin

Bases de données — ajouter une base et configurer sa connexion.
Installation manuelle — installer le backend avant les connecteurs.
Configuration — les autres réglages d’un serveur en réseau fermé, dont les dépôts de packages.