Conexões com Dados Externos

As Conexões com Dados Externos permitem consultar bancos de dados diretamente pelo ModelMonkey. Em vez de exportar dados manualmente ou escrever scripts de importação complexos, você pode pedir ao ModelMonkey que busque dados dos seus bancos de dados PostgreSQL ou BigQuery e os combine com os dados das suas planilhas.

Uma vez conectado, você pode fazer perguntas como "Compare os dados de vendas do Google Sheets com os dados demográficos de clientes do PostgreSQL" ou "Encontre todos os pedidos do mês passado e cruze-os com os perfis de usuários do nosso banco de dados."

O ModelMonkey atualmente suporta duas fontes de dados externas:

PostgreSQL
Conecte-se a qualquer banco de dados PostgreSQL acessível pela internet. Isso inclui PostgreSQL auto-hospedado, Amazon RDS, Google Cloud SQL, Azure Database for PostgreSQL e outros serviços gerenciados de PostgreSQL.

Google BigQuery
Conecte-se a conjuntos de dados do Google BigQuery usando uma conta de serviço. Ideal para cargas de trabalho de análise em larga escala e consultas a data warehouses.

Ambos os tipos de conexão suportam apenas consultas de leitura, protegendo seus dados de produção contra modificações acidentais.

Para criar uma nova conexão com dados externos:

1. Abra o painel de Conexões com Dados Externos na barra lateral do ModelMonkey
2. Clique no botão "New Connection"
3. Selecione o tipo de fonte de dados (PostgreSQL ou BigQuery)
4. Insira os detalhes da conexão
5. Teste a conexão para verificar se está funcionando
6. Salve a conexão

O assistente de configuração guia você em cada etapa e valida suas configurações antes de salvar.

Para conectar-se a um banco de dados PostgreSQL, você precisará das seguintes informações:

Campos Obrigatórios

• Connection Name: Um nome amigável para identificar esta conexão (ex.: "BD de Analytics de Produção")
• Host: O hostname ou endereço IP do servidor de banco de dados
• Port: A porta do PostgreSQL (padrão: 5432)
• Database: O nome do banco de dados ao qual se conectar
• Username: Seu nome de usuário do banco de dados
• Password: Sua senha do banco de dados

Campos Opcionais

• Schema: O schema padrão a utilizar (padrão: "public")
• SSL Mode: Como tratar as conexões SSL
  • Disable: Sem SSL (não recomendado para produção)
  • Allow: Usar SSL se disponível
  • Prefer: Tentar SSL primeiro, com fallback para não-SSL (padrão)
  • Require: Sempre usar SSL

Connection Name: Production Analytics
Host: analytics-db.example.com
Port: 5432
Database: analytics
Schema: public
SSL Mode: Require
Username: readonly_user

Para conectar-se ao Google BigQuery, você precisará de uma conta de serviço com as permissões adequadas:

Campos Obrigatórios

• Connection Name: Um nome amigável para identificar esta conexão
• Project ID: O ID do seu projeto no Google Cloud (encontrado no Google Cloud Console)
• Service Account JSON: Um arquivo de chave JSON de uma conta de serviço com acesso ao BigQuery

Campos Opcionais

• Dataset ID: Um dataset padrão para consultar
• Location: A localização dos dados (US, EU ou uma região específica)

Papéis IAM Necessários
Sua conta de serviço precisa das seguintes permissões:

• BigQuery Data Viewer: Ler metadados e dados de tabelas
• BigQuery Job User: Criar e executar consultas
• BigQuery Read Session User: Ler dados via Storage API

Para criar uma conta de serviço com acesso ao BigQuery:

1. Acesse o Google Cloud Console (console.cloud.google.com)
2. Navegue até IAM & Admin → Service Accounts
3. Clique em "Create Service Account"
4. Insira um nome como "modelmonkey-readonly"
5. Conceda os seguintes papéis:
   • BigQuery Data Viewer
   • BigQuery Job User
   • BigQuery Read Session User
6. Clique em "Done" para criar a conta
7. Clique na nova conta de serviço e acesse a aba "Keys"
8. Clique em "Add Key" → "Create new key" → "JSON"
9. Baixe o arquivo JSON e faça o upload no ModelMonkey

Mantenha este arquivo JSON em segurança. Ele fornece acesso aos seus dados do BigQuery.

Antes de salvar uma conexão, o ModelMonkey valida se consegue alcançar seu banco de dados:

O Que o Teste Verifica

• Conectividade de rede com o host
• Autenticação com suas credenciais
• Permissão para consultar o banco de dados

Resultados do Teste
Um teste bem-sucedido exibe:

• Informações sobre a versão do servidor
• Schemas disponíveis (PostgreSQL)
• Número de tabelas acessíveis

Se o teste falhar, você verá uma mensagem de erro específica explicando o que ocorreu. Problemas comuns incluem:

• Hostname ou porta incorretos
• Nome de usuário ou senha errados
• Firewall bloqueando a conexão
• Permissões ausentes no banco de dados

O ModelMonkey utiliza segurança de nível empresarial para proteger as credenciais do seu banco de dados:

Criptografia Envelope
Suas credenciais são criptografadas com uma Chave de Criptografia de Dados (DEK) exclusiva, gerada para cada conexão. A própria DEK é criptografada pelo Google Cloud KMS antes do armazenamento. Essa abordagem em duas camadas garante que suas credenciais nunca sejam armazenadas em texto simples.

Proteção contra SSRF
O ModelMonkey bloqueia conexões a faixas de IP privadas, localhost e endpoints de metadados de nuvem. Isso previne potenciais vulnerabilidades de segurança mesmo que entradas maliciosas sejam fornecidas.

Manipulação Segura de Memória
As credenciais descriptografadas são mantidas em buffers de memória segura e automaticamente limpas quando não são mais necessárias.

Acesso Somente Leitura
As conexões com o BigQuery são explicitamente configuradas como somente leitura. Para o PostgreSQL, recomendamos utilizar usuários de banco de dados com permissões apenas de SELECT.

Quando uma conexão estiver ativa, você pode consultá-la simplesmente pedindo ao ModelMonkey em linguagem natural:

Exemplos de Solicitações

• "Mostre os 10 principais clientes por receita do nosso banco de dados PostgreSQL"
• "Compare os dados de vendas do Google Sheets com os dados demográficos de clientes do banco de dados externo"
• "Encontre todos os pedidos do mês passado e cruze-os com os perfis de usuários"
• "Analise tendências nos dados de analytics do nosso BigQuery"

O ModelMonkey automaticamente:

1. Conecta-se ao seu banco de dados externo de forma segura
2. Traduz sua solicitação para SQL
3. Executa a consulta
4. Retorna os resultados, que podem ser gravados na sua planilha

Você pode combinar dados de múltiplas fontes em uma única solicitação, permitindo cruzar dados de planilhas com registros de bancos de dados externos.

Visualizando Conexões
Todas as suas conexões aparecem no painel de Conexões com Dados Externos. Cada conexão exibe:

• Nome da conexão
• Tipo de provedor (PostgreSQL ou BigQuery)
• Informações de host ou projeto
• Status Ativo/Inativo
• Data de criação

Status da Conexão

• Active: A conexão está disponível para consultas
• Inactive: A conexão existe, mas está desativada

Excluindo Conexões
Para remover uma conexão:

1. Clique no ícone de menu (três pontos) no cartão da conexão
2. Selecione "Delete"
3. Confirme a exclusão

Excluir uma conexão remove permanentemente ela e suas credenciais criptografadas. Esta ação não pode ser desfeita.

Falha no Teste de Conexão

• Verifique se o hostname está correto e é acessível publicamente
• Confirme se a porta do banco de dados está aberta no seu firewall
• Confira se o nome de usuário e a senha estão corretos
• Para o BigQuery, verifique se sua conta de serviço possui os papéis necessários

Consultas Retornam Erros

• Verifique se o usuário do banco de dados tem permissão SELECT nas tabelas que você está consultando
• Confirme se os nomes das tabelas e dos schemas estão corretos
• Para o BigQuery, verifique se sua conta de serviço pode acessar o dataset especificado

Timeout de Conexão

• Seu banco de dados pode estar atrás de um firewall que bloqueia os servidores do ModelMonkey
• Verifique se seu provedor de nuvem exige o cadastro de IPs autorizados (allowlisting)
• Considere usar um proxy de banco de dados ou VPN se o acesso direto não for possível

Erro "SSRF Attempt Detected"

• Não é possível conectar-se a endereços IP privados ou localhost
• Utilize um hostname publicamente acessível para seu banco de dados
• Bancos de dados hospedados em nuvem (RDS, Cloud SQL, etc.) geralmente disponibilizam endpoints públicos

Use Usuários Dedicados Somente Leitura
Crie um usuário de banco de dados exclusivamente para o ModelMonkey, com apenas permissões de SELECT. Isso limita o impacto caso as credenciais sejam comprometidas.

Habilite SSL/TLS
Sempre use o modo SSL "Require" para conexões PostgreSQL em produção. As conexões com o BigQuery são sempre criptografadas.

Limite o Acesso a Tabelas
Conceda acesso apenas às tabelas e schemas que o ModelMonkey precisa consultar. Evite usar contas de superusuário ou administrador.

Use Nomes de Conexão Descritivos
Nomeie suas conexões de forma clara (ex.: "Analytics de Produção", "BD de Pedidos de Homologação") para referenciá-las facilmente nas solicitações.

Revise as Conexões Regularmente
Faça auditorias periódicas nas suas conexões e remova as que não são mais necessárias. Menos conexões ativas significa uma superfície de segurança menor.