Leia antes:
../conectores.md(mapa de estados) efichas.md(índice das fichas).
O que é#
Connects to your Azure SQL Database via the SQL Server driver (encryption required) and extracts tables on a schedule. Supports incremental load by watermark.
Supported ingestion modes:
- Nós buscamos — We pull the data from your source.
Para que serve#
Bring data from Azure SQL into your datalake and make it available to the Bronze/Silver/Gold layers, BI models and the natural-language question wizard.
Quando usar / quando não usar#
Use quando você precisa consolidar esta fonte no datalake de forma agendada, com isolamento por workspace.
Evite carga completa desnecessária em tabelas grandes: prefira a carga incremental por watermark (veja Limites e o guia de incremental).
Plano e permissões#
- Plano: núcleo do produto (conectores fazem parte de todos os planos; o limite é o número de fontes do plano).
- Acesso: exige workspace ativo — com a assinatura em atraso, suspensa ou cancelada, a execução fica bloqueada.
- Desligamento: a execução de ingestão pode ser desligada temporariamente (manutenção ou incidente). Quando isso acontece, a tela informa que o recurso está indisponível no momento.
Pré-requisitos#
- Um usuário somente leitura no banco, com acesso ao schema/tabelas desejados.
- Rede: escolha como chegamos até o banco — IP público + allowlist, túnel SSH (bastion), Cloud SQL ou VPN.
- Allow two networks at the source: the application server (where Test connection runs from) and the pipeline runner (where the scheduled extraction runs from), which has a different outbound IP.
Credenciais#
Campos sensíveis. Eles são cifrados (AES-256-GCM) e nunca ficam no config da connection, na definição do pipeline, no export ou na DAG. Por padrão o valor cifrado fica no banco; mover a credencial desta connection para o cofre externo de credenciais é uma escolha explícita, feita por connection depois de salvar — ver ../../administracao/credenciais-e-rotacao.md.
- Senha (
password) — Guardada cifrada. Depois de salva, ninguém consegue vê-la de novo — nem você. - Chave privada SSH (
sshPrivateKey)
Segredos nunca são reexibidos e passam pela redação em todo erro/log (token cru, URL-encoded e em JSON).
Campos do formulário#
| Campo | Rótulo | Tipo | Obrigatório | Observação |
|---|---|---|---|---|
host | Server address | text | yes | Server name or IP. Your IT team or ERP vendor can provide this. |
port | Port | number | yes | default: 1433; Comes pre-filled with the default port (1433). Only change if your IT says it's different. |
database | Database name | text | yes | The name of the database inside the server. |
schema | Schema | text | no | Optional. Leave empty to see all tables the user can access. |
user | User | text | yes | Prefer a READ-ONLY user created for BI. |
password 🔒 | Password | password/secret | yes | secret (encrypted; external vault optional); Stored encrypted. After saving, nobody can view it again — not even you. |
encrypt | Encrypted connection (encryption) | yes/no | no | default: yes |
network | How we reach the database | select | no | default: direct; options: direct / ssh / cloudsql / vpn; In most cases it's “direct over the internet”. Use an SSH tunnel if the database only accepts internal network access. |
sshHost | Bastion host (SSH) | text | no | appears when network = ssh |
sshPort | Bastion port | number | no | default: 22; appears when network = ssh |
sshUser | Bastion user | text | no | appears when network = ssh |
sshPrivateKey 🔒 | SSH private key | password/secret | no | secret (encrypted; external vault optional); appears when network = ssh |
Passo a passo#
- No menu Dados → Conexões, use Nova conexão.
- Escolha Azure SQL no catálogo.
- Preencha os campos do formulário (veja a tabela acima).
- Use Testar conexão. The result is shown broken down into Conectividade, Autenticação and Listagem/leitura — each with OK, Failed, Not applicable or Not tested. A capability with no test of its own for this connector shows as Not applicable, and Not applicable never counts as success.
- Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
- No cartão da conexão, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a connection salva — a credencial não é copiada.
- Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.
Exemplo — teste de conexão#
Configuração de exemplo (todos os valores são fictícios; segredos aparecem mascarados):
# Exemplo sintético (valores fictícios — não são credenciais reais)
host = db.exemplo.invalid
port = 1433
database = vendas
schema = dbo
user = leitura_bi
password = •••••• (cifrado — nunca exibido)
encrypt = true
network = directResultado esperado#
Testar conexão retorna a lista de tabelas/recursos descobertos. Após a primeira carga, as linhas aparecem na camada Bronze do seu workspace, prontas para o pipeline.
Limites e custos#
- Paginação: hard cap per run (default 10.000 páginas / 5.000.000 linhas); anti-loop guard.
- Incremental por watermark: append/keyset by key-column. Not CDC — does not capture deletes or UPDATEs outside the watermark window. True CDC (WAL/redo/binlog) is on the Roadmap.
- Estimated volume: ~5 GB/month (catalog estimate, not measurement).
- Cost: the extraction itself is not charged by the platform; the Bronze load consumes datalake processing (billable).
Segurança#
- Escopo por workspace: cada cliente lê e escreve só no seu próprio datalake (
<prefixo>_bronze/_silver/_gold); nunca há vazamento entre workspaces. - Segredos cifrados: material sensível é cifrado com AES-256-GCM antes de ser gravado. O cofre externo de credenciais é opcional e ligado por connection; sem ele, o valor cifrado fica no banco. Trocar o valor aqui NÃO revoga a credencial na origem.
- Redaction: todo erro/log passa pela redação de segredos (cru, URL-encoded e em JSON).
- Produção não finge: um caminho que cairia em mock aciona a guarda de produção (falha explícita em vez de simular sucesso).
Erros comuns#
- Connection refused / timeout — incorrect host, port or network rule (allowlist/SSH/VPN). Check the network mode chosen in How we reach the database. Remember there are two networks: the application server (where Test connection runs from) and the pipeline runner (where the scheduled extraction runs from), with different outbound IPs.
- Autenticação falhou — usuário/senha inválidos ou usuário sem permissão de leitura no schema.
- SSL/handshake — turn Encrypted connection (encryption) (
encrypt) on or off according to the server's requirements. - Tabela/consulta grande — a extração respeita o teto de páginas/linhas; use carga incremental por watermark para reduzir o volume.
Troubleshooting#
- Use Testar conexão para isolar problemas de credencial/rede antes de agendar.
- Acompanhe as runs na observabilidade por conector (taxa de erro, p50/p95, freshness).
- Uma mudança de esquema na origem é sinalizada pelo schema drift (coluna nova = info; coluna removida/tipo mudado = atenção).
Relacionados#
../conectores.md— catálogo de conectores por estado../ingestao-incremental-backfill.md— full, incremental por watermark, backfill e checkpoint../pipeline-medalhao.md— camadas Bronze/Silver/Gold e qualidade../agendamento-retry-dlq.md— agendamento, retry/backoff e DLQ../custo-limites-seguranca.md— custo, tetos e segurança por workspace
Last review: 2026-10-04. Sheet automatically generated from the product's connector catalog.