connect-db
DOCUMENTATION

Bien démarrer avec Connect-DB

Connecter une base, l’explorer, l’interroger et la sauvegarder : tout ce qu’il faut savoir pour utiliser Connect-DB au quotidien.

Premiers pas

  1. Créez votre compte : choisissez une formule, puis renseignez vos informations et le nom de votre workspace (votre organisation).
  2. Créez un projet : il regroupe les connexions d’une même application ou d’un même environnement.
  3. Ajoutez une connexion à votre base : Connect-DB la teste immédiatement.
  4. Invitez votre équipe depuis les paramètres de l’organisation.

Ajouter une connexion

Dans un projet, cliquez sur Ajouter une connexion, choisissez le moteur puis complétez le formulaire. Les champs marqués d’un astérisque rouge sont obligatoires.

  • Hôte et port : l’adresse de votre serveur, telle que la voit Connect-DB (accès direct), le serveur SSH ou l’agent (bases privées, voir ci-dessous).
  • Base de données : la base exposée (nom de service pour Oracle, numéro de base pour Redis).
  • Utilisateur et mot de passe : de préférence un utilisateur en lecture seule (voir ci-dessous).
  • SSL : disable (non chiffré), require (chiffré) ou verify-full (chiffré, avec vérification du certificat et du nom d’hôte — recommandé en production).

Vous avez déjà une URL de connexion ? Ouvrez « Remplir depuis une URL de connexion » en haut du formulaire et collez-la : les champs se remplissent automatiquement, à vérifier avant d’enregistrer. L’URL elle-même n’est pas conservée.

postgresql://user:motdepasse@db.exemple.com:5432/ma_base?sslmode=require
mysql://user:motdepasse@db.exemple.com:3306/ma_base?ssl-mode=REQUIRED
mongodb://user:motdepasse@mongo.exemple.com:27017/app?authSource=admin&tls=true
sqlserver://user:motdepasse@sql.exemple.com:1433/ma_base?encrypt=true
oracle://user:motdepasse@ora.exemple.com:1521/ORCLPDB1
redis://user:motdepasse@redis.exemple.com:6379/0

Sont aussi acceptés : le format JDBC de SQL Server (jdbc:sqlserver://hôte;databaseName=…;user=…), le format Easy Connect d’Oracle (user/motdepasse@hôte:1521/service) et rediss:// pour Redis en TLS. Les URL mongodb+srv:// ne sont pas prises en charge. Un caractère spécial dans le mot de passe doit être encodé (@ → %40).

À l’enregistrement, Connect-DB teste la connexion et affiche le résultat. Une connexion en échec est tout de même enregistrée : vous pouvez la modifier et relancer le test.

Choisir l’accès réseau

En haut du formulaire, trois modes d’accès sont proposés :

  • Direct : la base doit être joignable depuis Internet. Les adresses privées ou locales (10.x, 192.168.x, localhost…) sont refusées.
  • Agent Connect-DB (recommandé pour une base privée) : un agent installé chez vous joint la base de l’intérieur. Aucun port à ouvrir, voir la section suivante.
  • Tunnel SSH : Connect-DB se connecte à un serveur SSH (votre bastion, ou le serveur qui héberge la base), qui relaie vers la base.
  • WireGuard : Connect-DB rejoint votre réseau WireGuard comme un pair, et joint la base par son adresse dans le tunnel (PostgreSQL pour l’instant).

Tunnel SSH

L’hôte de la base est alors celui vu depuis le serveur SSH : il peut être privé, par exemple 127.0.0.1.

  1. Renseignez l’hôte, le port et l’utilisateur du serveur SSH.
  2. Copiez la ligne authorized_keys proposée et ajoutez-la sur le serveur : la clé de votre organisation ne permet que le relais vers la base, sans shell.
  3. Au premier test, vérifiez puis approuvez l’empreinte du serveur SSH.
Le serveur SSH doit rester joignable depuis Internet (port 22 ouvert). Pour n’ouvrir aucun port, utilisez l’agent Connect-DB.

Tunnel WireGuard

Connect-DB génère sa propre clé WireGuard pour la connexion et se comporte comme un pair de votre serveur. L’hôte de la base est son adresse IP dans le tunnel, par exemple 10.8.0.1 : aucun nom n’y est résolu.

  1. Renseignez le serveur WireGuard (endpoint et port UDP, 51820 par défaut), sa clé publique, et une adresse libre du réseau pour Connect-DB, par exemple 10.8.0.2/32.
  2. Enregistrez : Connect-DB affiche un bloc [Peer]. Ajoutez-le à la configuration du serveur, puis rechargez-la (wg syncconf wg0 <(wg-quick strip wg0)).
  3. La base doit écouter sur son adresse dans le tunnel (listen_addresses, ou port Docker publié sur cette adresse) et autoriser l’adresse de Connect-DB dans pg_hba.conf.
  4. Cliquez sur « Tester à nouveau ».
# /etc/wireguard/wg0.conf (serveur)
[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = <clé privée du serveur>

# Connect-DB — Production
[Peer]
PublicKey = <clé publique affichée par Connect-DB>
AllowedIPs = 10.8.0.2/32
Le port UDP du serveur WireGuard doit être joignable depuis le connecteur Connect-DB. Régénérer la clé ou quitter le mode WireGuard invalide l’ancienne clé : le pair est alors à remplacer sur le serveur.

Bases privées : l’agent Connect-DB

L’agent est un conteneur Docker que vous installez sur un serveur qui voit vos bases. Ce peut être le VPS où tourne votre application, ou une machine de votre réseau.

  • Il ouvre une connexion sortante vers Connect-DB (WebSocket chiffrée, port 443) : aucun port entrant n’est à ouvrir, et vos bases restent invisibles depuis Internet.
  • Connect-DB lui transmet les opérations de vos connexions (test, schéma, requêtes, sauvegardes, restaurations). Il les exécute chez vous et ne renvoie que les résultats.

Installer l’agent

  1. Dans Organisation → Agents, cliquez sur Ajouter un agent (propriétaires et administrateurs). Donnez-lui un nom et listez les bases qu’il pourra joindre.
  2. Connect-DB affiche une commande docker run, ou un service à ajouter à votre docker-compose.yml. Elle contient un jeton à usage unique, valable une heure et affiché une seule fois.
  3. Exécutez la commande sur votre serveur : l’agent apparaît En ligne dans la page Agents.
docker run -d --restart=always --name dataflow-agent \
  -e DATAFLOW_URL=wss://…/agents/tunnel \
  -e DATAFLOW_ENROLL_TOKEN=dfa_… \
  -e DATAFLOW_ALLOWED_HOSTS="postgres:5432" \
  -v dataflow-agent:/data \
  ghcr.io/dataflow/agent:1

Au premier démarrage, l’agent crée sa clé d’identité et la garde dans le volume /data. Le jeton n’est plus utile ensuite. Conservez ce volume : sans lui, il faudra réinstaller l’agent avec un nouveau jeton.

Si votre application tourne déjà sous docker compose, ajoutez l’agent comme un service de plus : il rejoint le réseau de l’application et joint la base par son nom de service (postgres, db…). La base n’a alors besoin d’aucun port publié.

Bases autorisées

DATAFLOW_ALLOWED_HOSTS liste les seules destinations que l’agent accepte de joindre ; tout le reste est refusé par l’agent lui-même, même si Connect-DB le lui demandait. Séparez les entrées par des virgules :

  • un nom, avec ou sans port : postgres:5432, db.interne ;
  • une adresse : 10.0.3.7:5432 ;
  • une plage d’adresses : 10.0.3.0/24.

Pour modifier la liste, changez la variable puis redémarrez le conteneur : l’agent garde son identité.

Utiliser l’agent dans une connexion

Dans le formulaire de connexion, choisissez l’accès Agent Connect-DB puis l’agent. Renseignez l’hôte de la base tel que l’agent le voit : par exemple le nom du service Docker de la base. Il doit figurer dans DATAFLOW_ALLOWED_HOSTS.

Proxy d’entreprise et diagnostic

Derrière un proxy sortant, ajoutez -e HTTPS_PROXY=http://proxy:3128. Si le proxy inspecte le TLS, fournissez aussi son autorité de certification avec NODE_EXTRA_CA_CERTS. En cas de doute, lancez le diagnostic :

docker exec dataflow-agent node /app/dataflow-agent/dist/main.js doctor

Il vérifie l’accès à Connect-DB, la résolution des bases autorisées et l’identité de l’agent.

Révoquer un agent

Dans la page Agents, Révoquer déconnecte l’agent immédiatement et définitivement ; les connexions qui l’utilisent cessent de fonctionner. Pour le remplacer, installez un nouvel agent avec un nouveau jeton. Le nombre d’agents dépend de votre formule.

L’agent s’authentifie à chaque connexion par une signature avec sa propre clé : il n’y a ni mot de passe ni jeton longue durée. Seules sa clé publique, sa version et son adresse IP de connexion sont connues de Connect-DB.

Créer un utilisateur en lecture seule

Les connecteurs n’exécutent que des lectures, mais un utilisateur limité côté base reste la meilleure protection. Voici un exemple pour chaque moteur :

create role connect_db_ro login password '…';
grant usage on schema public to connect_db_ro;
grant select on all tables in schema public to connect_db_ro;
alter default privileges in schema public grant select on tables to connect_db_ro;

Explorer le schéma

La page Schéma liste les tables et vues de la connexion sélectionnée, avec leurs colonnes, types, valeurs par défaut et clés primaires, ainsi qu’une estimation du nombre de lignes et de la taille. Sélectionnez une table pour en prévisualiser les données, page par page.

La vue Diagramme des relations (bouton en haut à droite) dessine les tables et leurs clés étrangères : chaque lien relie la colonne qui référence à la colonne référencée (côté « plusieurs » et côté « un »). Les tables sont disposées automatiquement ; la molette zoome, glisser le fond déplace le plan, glisser l’en-tête d’une table la déplace, et Ajuster remet tout à l’écran. Survolez une table pour mettre ses relations en évidence, cherchez-en une (Entrée la centre), filtrez par schéma ou masquez les tables isolées. Un double-clic ouvre la table dans l’explorateur. La liste des relations, en bas, donne les mêmes informations sous forme de tableau.

  • MongoDB : chaque collection apparaît comme une table ; les champs sont déduits d’un échantillon de documents.
  • Redis : les clés sont regroupées par préfixe (la partie avant le premier :), à partir d’un échantillon.

Exécuter des requêtes

La page Requêtes exécute votre requête sur la connexion choisie (raccourci Ctrl + Entrée). Les résultats s’exportent en CSV ou en JSON.

SQL (PostgreSQL, MySQL, SQL Server, Oracle)

Une seule instruction SELECT (ou WITH … SELECT) par exécution.

SELECT id, email FROM users ORDER BY id LIMIT 50;
MongoDB

Un document JSON décrivant la collection et un find ou un pipeline aggregate.

{ "collection": "users", "find": { "active": true }, "limit": 50 }
Redis

Une commande de lecture, avec la syntaxe de redis-cli.

HGETALL user:42
Par défaut, les requêtes sont exécutées en lecture seule : les instructions d’écriture (INSERT, UPDATE, DELETE, DROP…) sont refusées. Le résultat est limité à 500 lignes et une requête est interrompue après 10 secondes.

Autoriser les écritures

Sur une connexion PostgreSQL, MySQL / MariaDB, SQL Server ou Oracle, un propriétaire ou un administrateur peut activer la lecture-écriture dans les paramètres de la connexion. Les éditeurs, administrateurs et propriétaires peuvent alors exécuter INSERT, UPDATE, DELETE et MERGE, ou modifier des lignes depuis l’explorateur :

  • chaque écriture passe d’abord par un aperçu (essai annulé) qui indique les lignes touchées ;
  • une instruction sans clause WHERE demande une confirmation explicite ;
  • la structure de la base reste protégée : CREATE, ALTER, DROP, TRUNCATE et GRANT sont refusés ;
  • chaque écriture appliquée est inscrite au journal d’audit, avec les instructions exécutées.
Les lecteurs restent en lecture seule, même sur une connexion en lecture-écriture.

Comparer deux sources

La page Comparaison confronte les schémas de deux connexions — par exemple production et recette — et liste chaque table, colonne, index, clé étrangère ou contrainte ajoutée, supprimée ou modifiée. Utile avant une mise en production pour vérifier que les migrations ont bien été appliquées.

La comparaison de données confronte le contenu d’une table dans les deux sources : lignes présentes d’un seul côté, lignes modifiées et lignes identiques, appariées par clé primaire (ou par ligne entière à défaut), avec des exemples pour chaque cas. Sur les grandes tables, la comparaison porte sur un échantillon plafonné.

Sauvegardes

Depuis la page Sauvegardes, programmez une sauvegarde récurrente pour une connexion (quotidienne, hebdomadaire…) avec sa durée de rétention, ou lancez une sauvegarde immédiate. Les sauvegardes plus anciennes que la rétention sont supprimées automatiquement ; chacune peut être téléchargée.

La restauration écrit dans la base choisie : elle est réservée aux propriétaires et administrateurs, demande de confirmer le nom de la connexion cible, et vous laisse choisir le comportement si une table existe déjà (par exemple refuser la restauration).

Équipe et rôles

Invitez des membres par e-mail depuis l’organisation. Chaque membre reçoit un rôle :

PropriétaireTous les droits, y compris sur l’organisation et ses membres.
AdministrateurGère les membres, les projets, leurs connexions et les agents Connect-DB.
ÉditeurCrée et modifie connexions, sauvegardes et comparaisons.
LecteurConsulte les projets, explore les schémas et exécute des requêtes (en lecture seule).

Les actions sensibles (connexions, requêtes, invitations…) sont enregistrées dans le journal d’audit de l’organisation.

Sécurité

  • Identifiants chiffrés au repos ; les mots de passe ne sont jamais renvoyés à l’interface.
  • Lecture seule par défaut, imposée par chaque connecteur, avec délai et nombre de lignes plafonnés ; les écritures ne sont possibles que sur les connexions où un administrateur les autorise.
  • Chiffrement en transit : TLS vers votre base selon le mode SSL choisi.
  • Protection réseau : en accès direct, les connecteurs refusent les adresses internes. Les bases privées passent par l’agent Connect-DB, qui ne joint que les destinations que vous autorisez, ou par votre serveur SSH, authentifié par son empreinte.
  • Aucun port entrant avec l’agent : la connexion est établie de chez vous vers Connect-DB, et vous pouvez la couper à tout moment en révoquant l’agent.

Pour en savoir plus sur les données que nous traitons, consultez notre politique de confidentialité.