Intégrations de bases de données

Guida peut se connecter directement depuis les scripts à des bases de données externes, clusters de recherche et stockages d’objets. Les identifiants de connexion sont stockés comme entrées chiffrées : vous passez leur nom dans le paramètre conn, et Guida résout la chaîne de connexion à l’exécution. Toutes les intégrations de bases de données sont bloquées pour les scripts d’origine MCP, selon le même modèle de sécurité que g.secrets.getSecret().

Modèle de connexion

Chaque méthode de base de données prend un paramètre conn : le nom d’une entrée contenant la chaîne de connexion. Les identifiants restent hors de vos scripts :

// L'entrée "my-pg" contient : Host=localhost;Database=mydb;Username=user;Password=pass
const rows = await g.postgres.query("my-pg",
  "SELECT * FROM products WHERE price < $1", [20.00]
);

Les connexions sont automatiquement mises en pool et réutilisées entre les appels dans un script.

Étapes de configuration :

Ouvrez le panneau Secrets.
Cliquez sur le bouton dédié : Add S3 Connection, Add MongoDB ou Add PostgreSQL. Chacun ouvre un dialogue typé avec les bons champs.
Utilisez le nom de l’entrée dans vos scripts.

Dialogue Add PostgreSQL Connection dans le panneau Secrets, montrant les champs Name, Connection String avec exemple et Description

Les dialogues de connexion stockent les chaînes de connexion comme identifiants chiffrés que les scripts utilisent par nom.

Stockage d’objets compatible S3

g.s3.* se connecte à n’importe quel service compatible S3 : AWS S3, MinIO, DigitalOcean Spaces, Backblaze B2, etc.

Format de chaîne de connexion :

endpoint=s3.amazonaws.com;accessKey=AKIA...;secretKey=...;region=us-east-1;secure=true

Pour MinIO en local :

endpoint=127.0.0.1:9000;accessKey=minioadmin;secretKey=minioadmin;secure=false

Cas d’usage :

Sauvegarder des données scrapées dans un stockage cloud.
Stocker captures d’écran et captures pleine page.
Générer des liens de téléchargement présignés pour partager des résultats.
Déplacer des fichiers entre buckets dans un pipeline.

Exemple

async function main() {
  // Upload scraped data as JSON
  const data = { products: [{ name: "Widget", price: 9.99 }] };
  await g.s3.putObjectText(
    "my-s3", "scraping-results", "exports/products.json",
    JSON.stringify(data, null, 2),
    "application/json"
  );

  // Generate a shareable download link (24 hours)
  const url = await g.s3.getPresignedUrl("my-s3", "scraping-results", "exports/products.json", {
    expiry: 86400
  });
  g.log("Download: " + url);
}

12 méthodes au total — voir la référence API pour la liste complète.

MongoDB

g.mongodb.* se connecte à MongoDB pour le stockage de documents, les requêtes et les agrégations.

Format de chaîne de connexion (URI MongoDB standard) :

mongodb://user:password@localhost:27017

Pour MongoDB Atlas :

mongodb+srv://user:[email protected]

Cas d’usage :

Stocker des documents scrapés avec des schémas flexibles.
Exécuter des pipelines d’agrégation pour analyse.
Insérer ou mettre à jour en masse avec insertMany et bulkWrite.
Indexer des champs pour des recherches rapides.

Exemple

async function main() {
  const conn = "my-mongo";

  // Insert scraped products
  const result = await g.mongodb.insertMany(conn, "scraping", "products", [
    { name: "Widget A", price: 9.99, category: "tools" },
    { name: "Widget B", price: 14.99, category: "tools" },
    { name: "Gadget C", price: 29.99, category: "electronics" }
  ]);
  g.log("Inserted " + result.insertedCount + " documents");

  // Query with filter and sort
  const docs = await g.mongodb.find(conn, "scraping", "products",
    { price: { $lt: 20 } },
    { sort: { price: 1 } }
  );
  g.log("Cheap products: " + docs.length);

  // Aggregate by category
  const stats = await g.mongodb.aggregate(conn, "scraping", "products", [
    { $group: { _id: "$category", count: { $sum: 1 }, avgPrice: { $avg: "$price" } } }
  ]);
  for (const s of stats) {
    g.log(s._id + ": " + s.count + " items, avg $" + s.avgPrice.toFixed(2));
  }
}

17 méthodes au total — voir la référence API pour la liste complète.

PostgreSQL

g.postgres.* se connecte à PostgreSQL pour requêtes relationnelles, transactions et opérations en masse.

Format de chaîne de connexion (Npgsql standard) :

Host=localhost;Database=mydb;Username=user;Password=pass

Toutes les requêtes utilisent des paramètres positionnels ($1, $2, etc.) : Guida n’interpole jamais les valeurs dans les chaînes SQL, ce qui empêche les injections SQL.

Cas d’usage :

Stocker des données structurées avec intégrité relationnelle.
Encapsuler des opérations multi-étapes dans des transactions.
Importer en masse avec copyFrom, via le protocole COPY, beaucoup plus rapide que des INSERT ligne par ligne.
Inspecter schémas, tables, index et contraintes.

Exemple

async function main() {
  const conn = "my-pg";

  // Query with parameters
  try {
    const rows = await g.postgres.query(conn,
      "SELECT id, name, price FROM products WHERE category = $1 ORDER BY price",
      ["electronics"]
    );

    // Transaction: insert order + update stock atomically
    const result = await g.postgres.transaction(conn, async (tx) => {
      await tx.execute(
        "INSERT INTO orders (product_id, qty) VALUES ($1, $2)", [42, 3]
      );
      await tx.execute(
        "UPDATE products SET stock = stock - $1 WHERE id = $2", [3, 42]
      );
      return await tx.scalar("SELECT count(*) FROM orders");
    });
    g.log("Total orders: " + result);

    // Bulk import via COPY (fast)
    const copyResult = await g.postgres.copyFrom(conn, "products", [
      ["Widget A", 9.99, 100],
      ["Widget B", 14.99, 50]
    ], { columns: ["name", "price", "stock"] });
    g.log("Imported " + copyResult.rowsCopied + " rows");
  } catch (e) {
    g.log("Error: " + e.message);
  }
}

14 méthodes au total — voir la référence API pour la liste complète.

Sécurité

Toutes les intégrations de bases de données suivent le même modèle de sécurité que les identifiants d’accès :

Les scripts d’origine MCP sont bloqués. Lorsqu’un agent IA exécute un script via MCP, tous les appels g.s3.*, g.mongodb.* et g.postgres.* renvoient une erreur. Cela empêche l’IA d’accéder à des bases externes par automatisation scriptée.
Les processus héritent de l’origine de leur lanceur. Si MCP démarre un pool de processus, ces processus sont eux aussi bloqués pour l’accès aux bases de données.
Les scripts lancés par l’utilisateur ont un accès complet. Les scripts exécutés via F5, déclencheurs d’événements et processeurs de file peuvent utiliser toutes les méthodes de base de données.

Les chaînes de connexion ne sont jamais exposées par les outils MCP : l’IA ne voit que le nom de l’entrée, pas les identifiants.

Étapes suivantes

Référence API — signatures complètes et interfaces pour stockage compatible S3, MongoDB et PostgreSQL
Identifiants d’accès — gestion des identifiants de connexion chiffrés
Espaces de travail — stockage et configuration limités à l’espace de travail
Scraper et stocker les données d’une page — commencer par le stockage local à l’espace de travail avant d’ajouter des bases externes