Integrazioni database

Guida può collegarsi direttamente dagli script a database esterni, cluster di ricerca e archiviazione di oggetti. Le credenziali di connessione vengono salvate come credenziali di accesso cifrati: passi il nome della credenziale di accesso come parametro conn e Guida risolve la stringa di connessione durante l’esecuzione. Tutte le integrazioni database sono bloccate per gli script di origine MCP, con lo stesso modello di sicurezza di g.secrets.getSecret().

Schema di connessione

Ogni metodo database accetta un parametro conn: il nome di una credenziale di accesso che contiene la stringa di connessione. Questo mantiene le credenziali fuori dagli script:

// La credenziale di accesso "my-pg" contiene: Host=localhost;Database=mydb;Username=user;Password=pass
const rows = await g.postgres.query("my-pg",
  "SELECT * FROM products WHERE price < $1", [20.00]
);

Le connessioni vengono messe automaticamente in pool e riutilizzate tra le chiamate dentro uno script.

Passaggi di configurazione:

1. Apri il pannello Credenziali di accesso (Secrets)
2. Fai clic sul pulsante dedicato (Aggiungi connessione S3 (Add S3 Connection), Aggiungi MongoDB (Add MongoDB) o Aggiungi PostgreSQL (Add PostgreSQL)): ciascuno apre una finestra di dialogo dedicata con i campi corretti
3. Usa il nome della credenziale di accesso nei tuoi script

I dialoghi di connessione database salvano stringhe di connessione come credenziali di accesso cifrate che gli script usano per nome.

---

Archiviazione di oggetti compatibile con S3

g.s3.* si collega a qualsiasi servizio compatibile con S3: AWS S3, MinIO, DigitalOcean Spaces, Backblaze B2, ecc.

Formato della stringa di connessione:

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

Per MinIO in esecuzione in locale:

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

Casi d’uso:

• Eseguire backup dei dati estratti verso archiviazione cloud
• Salvare screenshot e acquisizioni a pagina intera
• Generare link di download prefirmati per condividere risultati
• Spostare file tra bucket come parte di un flusso

Esempio

async function main() {
  // Carica i dati estratti come 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"
  );

  // Genera un link di download condivisibile (24 ore)
  const url = await g.s3.getPresignedUrl("my-s3", "scraping-results", "exports/products.json", {
    expiry: 86400
  });
  g.log("Download: " + url);
}

12 metodi in totale: vedi il Riferimento API per l’elenco completo.

---

MongoDB

g.mongodb.* si collega a MongoDB per archiviazione di documenti, query e aggregazioni.

Formato della stringa di connessione (URI MongoDB standard):

mongodb://user:password@localhost:27017

Per MongoDB Atlas:

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

Casi d’uso:

• Salvare documenti estratti con schemi flessibili
• Eseguire pipeline di aggregazione per l’analisi
• Inserimenti/aggiornamenti in blocco con insertMany e bulkWrite
• Indicizzare campi per ricerche rapide

Esempio

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

  // Inserisci prodotti estratti
  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("Inseriti " + result.insertedCount + " documenti");

  // Query con filtro e ordinamento
  const docs = await g.mongodb.find(conn, "scraping", "products",
    { price: { $lt: 20 } },
    { sort: { price: 1 } }
  );
  g.log("Prodotti economici: " + docs.length);

  // Aggrega per categoria
  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 + " elementi, media $" + s.avgPrice.toFixed(2));
  }
}

17 metodi in totale: vedi il Riferimento API per l’elenco completo.

---

PostgreSQL

g.postgres.* si collega a PostgreSQL per query relazionali, transazioni e operazioni in blocco.

Formato della stringa di connessione (Npgsql standard):

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

Tutte le query usano parametri posizionali ($1, $2, …): Guida non interpola mai valori dentro stringhe SQL, prevenendo SQL injection.

Casi d’uso:

• Salvare dati strutturati con integrità relazionale
• Racchiudere operazioni in più passaggi dentro transazioni
• Importare dati in blocco con copyFrom (protocollo COPY: molto più veloce di INSERT riga per riga)
• Ispezionare schemi, tabelle, indici e vincoli

Esempio

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

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

    // Transazione: inserisci ordine + aggiorna magazzino in modo atomico
    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("Ordini totali: " + result);

    // Importazione in blocco via COPY (veloce)
    const copyResult = await g.postgres.copyFrom(conn, "products", [
      ["Widget A", 9.99, 100],
      ["Widget B", 14.99, 50]
    ], { columns: ["name", "price", "stock"] });
    g.log("Importate " + copyResult.rowsCopied + " righe");
  } catch (e) {
    g.log("Errore: " + e.message);
  }
}

14 metodi in totale: vedi il Riferimento API per l’elenco completo.

---

Sicurezza

Tutte le integrazioni database seguono lo stesso modello di sicurezza delle credenziali di accesso:

• Gli script di origine MCP sono bloccati. Quando un agente IA esegue uno script tramite MCP, tutte le chiamate g.s3.*, g.mongodb.* e g.postgres.* restituiscono un errore. Questo impedisce all’IA di accedere a database esterni tramite automazione scriptata.
• I processi di lavoro ereditano l’origine del loro avviatore. Se MCP avvia un pool di processi di lavoro, anche quei processi sono bloccati dall’accesso ai database.
• Gli script avviati dall’utente hanno accesso completo. Gli script eseguiti tramite F5, generazione di eventi e processori di coda possono usare tutti i metodi database.

Le stringhe di connessione non vengono mai esposte tramite strumenti MCP: l’IA vede solo il nome della credenziale di accesso, non le credenziali.

Passi successivi

• Riferimento API — firme complete dei metodi e interfacce per archiviazione compatibile con S3, MongoDB e PostgreSQL
• Credenziali di accesso — gestione delle credenziali di connessione cifrate
• Spazi di lavoro — archiviazione e configurazione legate allo spazio di lavoro
• Estrarre e salvare dati da una pagina — inizia dall’archiviazione locale allo spazio di lavoro prima di aggiungere database esterni