Integrações com bancos de dados

O Guida pode conectar-se a bancos externos, clusters de pesquisa e armazenamento de objetos diretamente de scripts. Credenciais de conexão são armazenadas como credenciais criptografadas: você passa o nome da credencial como parâmetro conn, e o Guida resolve a string de conexão em tempo de execução. Todas as integrações com bancos são bloqueadas para scripts originados por MCP, seguindo o mesmo modelo de segurança de g.secrets.getSecret().

Padrão de conexão

Todo método de banco recebe um parâmetro conn: o nome de uma credencial que contém a string de conexão. Isso mantém credenciais fora dos seus scripts:

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

Conexões são agrupadas e reutilizadas automaticamente entre chamadas dentro de um script.

Etapas de configuração:

Abra o painel Secrets
Clique no botão dedicado (Add S3 Connection, Add MongoDB ou Add PostgreSQL); cada um abre um diálogo tipado com os campos corretos
Use o nome da credencial nos scripts

Diálogo Add PostgreSQL Connection no painel Secrets, mostrando campos Name, Connection String com placeholder de exemplo e Description

Diálogos de conexão com banco armazenam strings de conexão como credenciais criptografadas que scripts usam por nome.

Armazenamento de objetos compatível com S3

g.s3.* conecta-se a qualquer serviço compatível com S3: AWS S3, MinIO, DigitalOcean Spaces, Backblaze B2 etc.

Formato da string de conexão:

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

Para MinIO local:

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

Casos de uso:

Criar cópia de segurança de dados extraídos em armazenamento em nuvem
Armazenar capturas de tela e capturas de página inteira
Gerar links de download pré-assinados para compartilhar resultados
Mover arquivos entre buckets como parte de um fluxo

Exemplo

async function main() {
  // Enviar dados extraídos como JSON
  const data = { products: [{ name: "Widget", price: 9.99 }] };
  await g.s3.putObjectText(
    "my-s3", "resultados-extracao", "exports/products.json",
    JSON.stringify(data, null, 2),
    "application/json"
  );

  // Gerar um link de download compartilhável (24 horas)
  const url = await g.s3.getPresignedUrl("my-s3", "resultados-extracao", "exports/products.json", {
    expiry: 86400
  });
  g.log("Download: " + url);
}

12 métodos no total — veja a Referência da API para a lista completa.

MongoDB

g.mongodb.* conecta-se ao MongoDB para armazenamento de documentos, consultas e agregação.

Formato da string de conexão (URI MongoDB padrão):

mongodb://user:password@localhost:27017

Para MongoDB Atlas:

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

Casos de uso:

Armazenar documentos extraídos com esquemas flexíveis
Executar fluxos de agregação para análise
Inserir/atualizar em lote com insertMany e bulkWrite
Indexar campos para buscas rápidas

Exemplo

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

  // Inserir produtos extraídos
  const result = await g.mongodb.insertMany(conn, "extracao", "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("Inseridos " + result.insertedCount + " documentos");

  // Consultar com filtro e ordenação
  const docs = await g.mongodb.find(conn, "extracao", "products",
    { price: { $lt: 20 } },
    { sort: { price: 1 } }
  );
  g.log("Produtos baratos: " + docs.length);

  // Agregar por categoria
  const stats = await g.mongodb.aggregate(conn, "extracao", "products", [
    { $group: { _id: "$category", count: { $sum: 1 }, avgPrice: { $avg: "$price" } } }
  ]);
  for (const s of stats) {
    g.log(s._id + ": " + s.count + " itens, média $" + s.avgPrice.toFixed(2));
  }
}

17 métodos no total — veja a Referência da API para a lista completa.

PostgreSQL

g.postgres.* conecta-se ao PostgreSQL para consultas relacionais, transações e operações em lote.

Formato da string de conexão (Npgsql padrão):

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

Todas as consultas usam parâmetros posicionais ($1, $2, …). O Guida nunca interpola valores em strings SQL, evitando SQL injection.

Casos de uso:

Armazenar dados estruturados com integridade relacional
Envolver operações multi-etapas em transações
Importar dados em lote com copyFrom (protocolo COPY, muito mais rápido que INSERT linha a linha)
Inspecionar esquemas, tabelas, índices e restrições

Exemplo

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

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

    // Transação: inserir pedido + atualizar estoque atomicamente
    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 de pedidos: " + result);

    // Importação em lote via COPY (rápida)
    const copyResult = await g.postgres.copyFrom(conn, "products", [
      ["Widget A", 9.99, 100],
      ["Widget B", 14.99, 50]
    ], { columns: ["name", "price", "stock"] });
    g.log("Importadas " + copyResult.rowsCopied + " linhas");
  } catch (e) {
    g.log("Erro: " + e.message);
  }
}

14 métodos no total — veja a Referência da API para a lista completa.

Segurança

Todas as integrações com bancos seguem o mesmo modelo de segurança das credenciais:

Scripts originados por MCP são bloqueados. Quando um agente de IA executa um script via MCP, todas as chamadas g.s3.*, g.mongodb.* e g.postgres.* retornam erro. Isso impede a IA de acessar bancos externos por automação com scripts.
Processos de trabalho herdam a origem de quem os iniciou. Se o MCP inicia um grupo de processos, esses processos também são bloqueados de acessar bancos.
Scripts iniciados pelo usuário têm acesso completo. Scripts executados por F5, gatilhos de eventos e processadores de fila podem usar todos os métodos de banco.

Strings de conexão nunca são expostas por ferramentas MCP: a IA vê apenas o nome da credencial, não os dados de autenticação.

Próximos passos

Referência da API — assinaturas e interfaces completas para armazenamento compatível com S3, MongoDB e PostgreSQL
Credenciais — gerenciamento de credenciais de conexão criptografadas
Espaços de trabalho — armazenamento e configuração com escopo de espaço de trabalho
Extrair e armazenar dados de página — comece com armazenamento local ao espaço de trabalho antes de adicionar bancos externos