Connexions aux bases de données
Une exécution sur base de données ne porte jamais de mot de passe. Elle porte le nom d'une connexion, et Avatar conserve le reste. Cette page explique à quoi vous pouvez vous connecter, qui peut voir une connexion, et comment en ajouter, en tester, en renommer et en supprimer une.
Vous pouvez gérer les connexions dans le client web, dans Compte > Connexions aux bases de données, ou depuis le client Python. Ce sont les mêmes connexions.
Moteurs pris en charge
| Moteur | Type | Statut |
|---|---|---|
| PostgreSQL | Tables (SQL) | pris en charge |
| MySQL | Tables (SQL) | pris en charge |
| MariaDB | Tables (SQL) | pris en charge |
| Oracle | Tables (SQL) | pris en charge |
| SQL Server | Tables (SQL) | pris en charge |
| ClickHouse | Tables (SQL) | pris en charge |
| MongoDB | Documents (NoSQL) | pris en charge |
| Snowflake | Tables (SQL) | aperçu |
| Google BigQuery | Tables (SQL) | aperçu, source uniquement |
| IBM Db2 | Tables (SQL) | aperçu, sur certaines installations seulement |
| SQLite | Tables (SQL) | bases de démonstration uniquement |
Votre installation peut proposer moins de moteurs. Le client web n'affiche que les moteurs que votre installation peut atteindre. Aperçu signifie que le moteur est proposé mais pas encore validé sur un vrai serveur : essayez-le d'abord sur une base de données où une erreur est sans conséquence.
Chaque moteur, bases de démonstration comprises, est ouvert par le connecteur de bases de données. Sans lui, une installation n'atteint aucune base de données, PostgreSQL compris.
Dans MongoDB, chaque collection est lue comme une table. Ses variables sont les champs de premier
niveau trouvés dans un échantillon de 500 documents, _id est la clé, et les valeurs imbriquées
arrivent sous forme de texte JSON. La méthode Avatar ne sait pas modéliser une valeur JSON :
supprimez les champs imbriqués dont les utilisateurs de la copie n'ont pas besoin. Une collection
n'a pas de clés étrangères : chaque collection est donc anonymisée seule. Pour donner à un même
individu la même identité dans plusieurs collections, déclarez une
entité partagée.
Chaque moteur a son propre formulaire. Vous n'écrivez jamais de chaîne de connexion vous-même.
| Moteur | Champs | Sous Plus d'options |
|---|---|---|
| PostgreSQL | hôte, port, base de données, utilisateur, mot de passe | mode SSL : prefer (par défaut), disable, require, verify-ca, verify-full |
| ClickHouse | hôte, port, base de données, utilisateur, mot de passe | TLS (désactivé par défaut) |
| MongoDB | hôte, port, base de données, utilisateur, mot de passe | base d'authentification, replica set, TLS (activé par défaut) |
| Snowflake | compte, utilisateur, mot de passe, base de données, schéma (facultatif), entrepôt | rôle |
| Google BigQuery | projet, jeu de données, clé de compte de service |
Les autres moteurs demandent un hôte, un port, une base de données, un utilisateur et un mot de passe. Un port est un nombre compris entre 1 et 65535. Tester avant d'enregistrer reste désactivé tant que chaque champ obligatoire n'est pas valide.
Portée des connexions
Une connexion a une portée, qui indique qui peut la voir :
| Portée | Qui peut l'utiliser | Qui peut la modifier |
|---|---|---|
| Moi seul | vous seul. Les administrateurs ne la voient pas. | vous |
| Toute l'organisation | chaque membre de votre organisation | les administrateurs de l'organisation |
| Déploiement | chaque utilisateur de l'installation | votre opérateur, dans la configuration de l'installation. Un administrateur peut la retirer de l'usage pour l'organisation. |
Dans le client web, une nouvelle connexion est Moi seul par défaut. Seul un administrateur
peut créer une connexion Toute l'organisation. Le client Python et l'API utilisent par défaut
la portée de l'organisation : un utilisateur qui n'est pas administrateur doit passer
scope="user", sinon la connexion est refusée.
Une connexion de déploiement n'a pas de bouton Modifier. Seul un administrateur voit Supprimer à côté d'elle, et la supprimer ne fait que la retirer de l'usage pour l'organisation.
Identifiants en écriture seule
Le mot de passe et les autres identifiants d'une connexion sont envoyés une fois, stockés chiffrés, et jamais renvoyés : ni par le client web, ni par l'API, ni dans un job. Une liste affiche l'hôte et le nom de la base de données, assez pour distinguer deux connexions, et rien qui permette de s'y connecter.
Quand un job s'exécute, son worker ne reçoit pas le mot de passe. Il reçoit un jeton de courte durée pour une seule connexion. Un service séparé, le connecteur de bases de données, présente le jeton, reçoit la chaîne de connexion de l'API et ouvre la base. Les lignes vont de votre base de données vers le stockage du job.
Ajouter une connexion
- Allez dans Compte > Connexions aux bases de données et cliquez sur Nouvelle connexion. Vous pouvez aussi cliquer sur Nouvelle connexion dans les sélecteurs de source et de cible lorsque vous créez une exécution sur base de données.
- Choisissez le Type de base de données et remplissez son formulaire.
- Choisissez un Nom, par exemple
crm_prod. Le client web en propose un à partir du champ de la base de données. Un nom compte au plus 63 caractères : des lettres, des chiffres, des tirets bas, des tirets et des points, et il commence par une lettre ou un chiffre. Les jobs et les configurations enregistrées désignent une connexion par son nom. - Choisissez un Nom affiché (facultatif), par exemple CRM (production). C'est seulement ce que les utilisateurs voient dans un sélecteur.
- Choisissez Qui peut utiliser cette connexion : Moi seul ou Toute l'organisation.
- Cliquez sur Tester avant d'enregistrer, puis sur Enregistrer.
Tester une connexion
Cliquez sur Tester à côté d'une connexion. Avatar l'ouvre depuis le serveur et indique trois faits :
- La base de données est-elle joignable ?
- A-t-elle un schéma (des tables) ?
- Est-elle vide ?
Ce sont les trois faits qu'une exécution sur base de données vérifie sur une cible : testez donc une cible avant de lancer une exécution. Quand le test échoue, le message indique le type d'échec : la base de données est injoignable, les identifiants sont faux, la base de données n'existe pas, ou un privilège manque. Le message ne répète jamais la chaîne de connexion.
Renommer, relibeller, remplacer ou supprimer une connexion
Cliquez sur Modifier à côté d'une connexion.
- Relibeller : changez le nom affiché à tout moment. Rien d'autre ne change.
- Renommer : les jobs déjà soumis ne sont pas affectés. Une configuration enregistrée qui utilise l'ancien nom ne trouvera plus la connexion, pas plus qu'une relance d'une exécution précédente (Relancer ce groupe, Relancer tous les groupes, Ajuster et relancer) : les jobs portent le nom d'une connexion, pas la connexion elle-même.
- Remplacer : pour changer l'hôte ou le mot de passe, cliquez sur Remplacer les détails… et remplissez à nouveau chaque champ. Le nom reste. Avatar ne renvoie jamais les identifiants stockés : il n'y a donc rien à modifier sur place.
- Supprimer : Avatar oublie la connexion et ses identifiants. Les jobs déjà soumis continuent de fonctionner, mais une configuration enregistrée ou une relance qui cite la connexion ne la trouvera plus. Vous pouvez supprimer vos propres connexions et, en tant qu'administrateur, les connexions de votre organisation. Pour une connexion de déploiement, un administrateur peut seulement la retirer de l'usage pour l'organisation.
Bases de démonstration
Pour essayer une exécution sur base de données avant de connecter vos propres bases, cliquez sur Ajouter les connexions de démonstration dans Compte > Connexions aux bases de données. L'assistant le propose aussi dans le sélecteur Lire depuis, tant que vous n'avez encore aucune connexion. Le bouton n'apparaît que si votre installation propose les bases de démonstration. Elles sont ajoutées comme connexions Moi seul. Deux bases de démonstration sont disponibles, chacune avec une source et une cible vide :
| Base | Contenu |
|---|---|
| Northwind | une société commerciale : 13 tables, 600 000 lignes de commande |
| Chinook | un magasin de musique : 11 tables |
Les sources de démonstration sont en lecture seule et partagées par tous les utilisateurs. Chaque exécution reçoit sa propre copie vide de la cible de démonstration : deux utilisateurs peuvent donc lancer une exécution en même temps sans se gêner. Une cible de démonstration est supprimée 24 heures après sa dernière écriture, et quand le connecteur de bases de données redémarre. Une cible de démonstration possède déjà le schéma de sa source de démonstration : elle n'accepte donc qu'une copie de cette source.
Bonnes pratiques
- Donnez à la connexion source un rôle de base de données qui peut seulement lire.
- Donnez à la connexion cible un rôle qui peut écrire et supprimer des lignes. Une exécution ne crée pas de tables : le rôle de la cible n'a donc pas besoin de pouvoir le faire.
- Ne pointez jamais une cible vers une base de production. Une exécution refuse une cible qui contient des lignes, sauf si vous demandez à la vider d'abord. Elle refuse une cible qui est la même connexion que la source, mais elle ne peut pas savoir que deux connexions différentes pointent vers la même base de données : vérifiez-le vous-même.
Pour les administrateurs
Les connexions aux bases de données ont besoin du connecteur de bases de données. Sur une installation auto-hébergée, votre opérateur l'active : voir Connecteur de bases de données. Sur le SaaS d'Octopize, le connecteur ne peut atteindre que des bases de données à une adresse publique.