Integrações

O que uma conexão guarda

Uma conexão tem duas metades. As configurações — host, porta, banco, bucket, região, endereço base — ficam na conexão, e quem tem acesso à página consegue ler. As credenciais — uma senha, uma access key, uma chave de API — não ficam guardadas na conexão: salvar transforma cada uma numa variável secreta do projeto, e a conexão lê dali toda vez que é usada.

As conexões pertencem a um projeto. A página lista os cards, com busca e filtros por Bancos de dados, Armazenamento e Serviços; o Abrir de um card leva um banco ao workbench SQL, o Navegar Arquivos leva um bucket ao navegador de arquivos, e o menu ⋯ tem Testar conexão, Editar e Excluir.

Os tipos de conexão

Os tipos Provedor de IA e API (HTTP) têm páginas próprias: Conecte um provedor de IA e Conexões de API (HTTP). O Email é um serviço que você liga aqui e configura na página dele — veja Email.

Adicione uma conexão

1. 1
   Abra o diálogo

   Em Integrações, clique em Adicionar integração (ou clique com o botão direito numa área vazia da página). O diálogo Conectar uma fonte de dados lista todos os tipos à esquerda, agrupados e com busca em Buscar integrações…; o Sobre à direita diz para que serve cada um.

   Adicionar integração
2. 2
   Dê um nome e preencha as configurações

   O Nome importa duas vezes: é por ele que scripts e passos escolhem a conexão, e é ele que dá nome às variáveis. Um banco pede Host, Porta (5432 ou 3306 já preenchida), Usuário, Banco, Senha e Modo SSL; ou passe para a aba Connection string, cole postgresql://user:password@host:5432/dbname e clique em Apply para preencher tudo.

3. 3
   Escolha como chegar ao banco

   Em Como chegar ao banco, mantenha Direto quando ele tem endereço público, ou escolha Túnel SSH ou Tailscale (próxima seção).

4. 4
   Confirme as variáveis

   Salvar conexão abre antes Variáveis que essa conexão cria, com os nomes exatos. Clique em Confirmar e salvar. Um nome que já existe aparece marcado como já existe — mude o nome da conexão, e o salvamento espera até você renomear a conexão.

Credenciais são variáveis secretas

Os nomes das variáveis vêm do nome da conexão, nunca são digitados: o prefixo do tipo, depois o nome em maiúsculas com qualquer outro caractere trocado por _, depois o campo. Uma conexão PostgreSQL chamada Main DB guarda a senha como PG_MAIN_DB_PASSWORD; uma conexão S3 chamada S3 Data gera S3_DATA_ACCESS_KEY_ID e S3_DATA_SECRET_ACCESS_KEY (o prefixo não se repete). Só as credenciais viram variáveis — host, usuário e bucket continuam configurações.

• Ao editar a conexão, cada credencial aparece como um chip com o nome da variável — Guardada no segredo … Clique pra editar o valor. — no lugar de uma caixa de senha. Mudar o valor ali ou na página Variáveis é a mesma coisa: troca a chave da conexão.
• Renomear a conexão renomeia as variáveis dela; a confirmação lista os nomes que saem. Os valores são mantidos.
• Renomear a variável você mesmo não quebra nada: a conexão encontra a credencial pelo que ela é, não pelo nome.
• Excluir a variável deixa a conexão sem credencial. O card mostra Credencial faltando: … — abra a conexão e informe de novo., as execuções que usam a conexão falham com credential_missing, e digitar o valor na conexão cria a variável de novo.
• Excluir a conexão exclui as variáveis que ela criou. Uma conexão que scripts ainda usam não pode ser excluída: o diálogo lista quais são (Usada por …).

Os valores secretos ficam criptografados com AES-256-GCM e nunca voltam em nenhuma lista ou resposta. Como toda variável, eles também chegam aos seus scripts como variáveis de ambiente — veja Variáveis e segredos.

Bancos numa rede privada

As execuções só alcançam endereços públicos. Um host numa rede privada — 10.x, 192.168.x, 172.16–31.x, localhost, faixas link-local ou CGNAT — é recusado, e o teste avisa: Este host está numa rede privada (um endereço interno). As execuções não conseguem chegar até ele — use o endereço público do banco. Para chegar mesmo assim, escolha um túnel:

Com um túnel, o Host é o endereço do banco visto de dentro da rede privada. O primeiro teste de um túnel SSH mostra a impressão digital do bastion — Confirme a identidade do bastion, confira com quem administra o servidor e clique em Confiar e testar. Se essa identidade mudar depois, as conexões param até você confiar na nova chave. Os segredos do túnel ficam guardados como variáveis secretas, como qualquer outra credencial.

Teste uma conexão

Testar conexão faz o teste de verdade: o de um banco abre uma conexão e roda uma query, o de S3 confere o bucket com as suas chaves, o de IA envia uma requisição mínima. O card passa a mostrar Conectou ou Falhou com o horário, e uma falha vem com o motivo em palavras simples — o túnel não abriu, o banco recusou as credenciais, o host não respondeu. Bancos e buckets são testados de novo sozinhos quando você abre a página e o último teste tem mais de cinco minutos; provedores de IA só são testados quando você clica, porque o teste gasta a sua própria cota.

Códigos que você pode encontrar

• credential_missing — a variável secreta da conexão foi excluída. Abra a conexão e informe o valor de novo.
• host_not_allowed — um endereço de saída que o worker recusou por ser privado: um host SMTP próprio, um arquivo enviado a partir de uma URL interna.
• variable_name_taken — já existe uma variável com um dos nomes derivados. Renomeie a conexão.

Limites e regras

• O tipo de uma conexão não muda depois de criada (O tipo da integração não muda depois de criada).
• Uma conexão S3 por projeto: os uploads do SDK sempre vão para o bucket do projeto.
• Na nuvem, conexões SQL e S3 são contadas por plano — Free 1, Pro 3, Team 10, Business ilimitado. O diálogo mostra quantas você usa antes de você tentar.
• O código do seu script nunca abre um socket: o código do usuário roda sem rede. Queries e transferências de arquivo são feitas pelo worker em nome do script, pela conexão.