Bancos de dados

Tipo

Referência

Para

Engenharia de dados, Desenvolvedor

Na tela

HorusETL › Dataflows › editor do Dataflow

Para ler de um banco que o Agente ETL enxerga, o nó roda um SELECT e entrega o resultado ao próximo nó. São nove bancos, e todos funcionam igual: uma conexão e uma consulta SQL. O que muda de um para outro está nas tabelas desta página.

A conexão é cadastrada antes, em Gerenciar Conexões, e pertence a um Agente ETL. O passo a passo está em cadastrar uma credencial.

Os nove bancos

Banco (na tela)	kind no YAML	Porta padrão	Driver no Agente ETL
PostgreSQL	ExtractPostgreSQL	5432	Npgsql
MySQL	ExtractMySQL	3306	MySqlConnector (também conecta em MariaDB)
SQL Server	ExtractSQLServer	1433	Microsoft.Data.SqlClient
OracleDB	ExtractOracleDB	a do data source	Oracle.ManagedDataAccess, sem Oracle Client instalado
Firebird	ExtractFirebird	3050	FirebirdSql.Data.FirebirdClient
IBM Informix	ExtractInformix	9088	JDBC da IBM, embutido no Agente ETL
InterSystems IRIS	ExtractInterSystemsIRIS	a da connection string	InterSystems.Data.IRISClient
ODBC	ExtractODBC	a do driver	o driver ODBC instalado na máquina do Agente ETL
Google BigQuery	ExtractBigQuery	não se aplica	Google.Cloud.BigQuery

No editor, os bancos aparecem no grupo Bancos de Dados da biblioteca de nós, uma entrada por conexão cadastrada, com o nome da conexão. Escolher uma delas cria o nó já apontando para ela.

Campos da conexão

Os campos abaixo são os do formulário de Gerenciar Conexões para cada tipo. Os que têm Connection string como alternativa mostram duas formas no topo do formulário: Campos ou Connection string.

Banco	Campos	Alternativa
PostgreSQL	Endereço, Porta, Banco, Usuário, Senha. Em Opções avançadas: Parâmetros extras, que entram no fim da connection string separados por ponto e vírgula (Encoding=LATIN1;Timeout=30)	nenhuma
MySQL	Endereço, Porta, Banco, Usuário, Senha. Em Segurança: Conectar com SSL, Modo SSL (Preferred, Required, VerifyCA, VerifyFull, None; padrão Required), Certificado do cliente, Certificado da autoridade (CA), Senha do certificado	Connection string
SQL Server	Endereço (10.0.0.5 ou SERVIDOR\INSTANCIA), Porta, Banco, Autenticação (SQL Server, com usuário e senha do banco, ou Windows, com a conta do serviço do Agente ETL). Em Segurança: Criptografar a conexão (Padrão do driver, Sim, Não) e Confiar no certificado do servidor	Connection string
OracleDB	Data source (host:porta/serviço ou o descritor TNS completo), Usuário, Senha	nenhuma
Firebird	Endereço (vazio para banco no mesmo computador do Agente ETL), Porta, Arquivo do banco (C:\dados\ERP.FDB ou um alias), Usuário, Senha. Em Opções avançadas: Charset (padrão UTF8), Dialeto (3 ou 1, padrão 3), Tipo de servidor (Servidor ou Embarcado), Role	Connection string
IBM Informix	Endereço, Porta, Banco, Informix Server (o INFORMIXSERVER da instância), Usuário, Senha. Em Opções avançadas: Client locale, DB locale, Parâmetros extras	URL JDBC (jdbc:informix-sqli://10.0.0.5:9088/erp:INFORMIXSERVER=ol_informix1410), com usuário e senha à parte
InterSystems IRIS e ODBC	Pares Chave e Valor. Cada par vira CHAVE=valor na connection string, e o par marcado como Segredo não volta para a tela. É preciso ao menos uma chave DSN, Driver ou Server	Connection string (DSN=NOMEODBC;UID=usuario;PWD=senha)
Google BigQuery	Project ID e Chave JSON da service account (botão Colar chave)	nenhuma

O Endereço é visto do computador onde o Agente ETL roda. No SQL Server, informe a porta em um lugar só: no Endereço depois da vírgula ou no campo Porta. Com os dois, o formulário recusa com "A porta está no servidor (depois da vírgula) e no campo Porta. Deixe em um só."

Campos do nó

Na tela	No YAML (options)	Tipo	Padrão	Regra
Fonte de dados	Credential	texto	nenhum	A conexão que o nó usa. No YAML vai a chave da conexão, não o id (descubra com lumo list credential)
Conexão por variável e Variável a usar	Credential: var-NOME	texto	desligado	A conexão sai de uma variável na hora da execução. Veja Conexão por variável
Editar Consulta SQL (aba Padrão)	SQL	texto	nenhum	O SELECT que roda quando não há SQL próprio para o banco da conexão
SQL para outro banco	SQLByKind	objeto { <kind>: SQL }	nenhum	SQL próprio de um tipo de banco. Veja SQL por tipo de banco
Só no YAML, BigQuery	UseStorageApi	booleano	true	Lê o resultado pela Storage Read API do BigQuery, mais rápida para volume grande
Só no YAML, BigQuery	MaxStreamCount	inteiro	4	Leituras paralelas da Storage Read API

O que sai do nó

• Nome das colunas: em MAIÚSCULAS, do jeito que o banco devolveu o nome ou o alias. Nome repetido ganha sufixo: ID, ID_1, ID_2. No BigQuery, o nome é cortado em 30 caracteres.
• Tipos: três. Texto, número e data. Coluna de texto vira texto e coluna de data, com ou sem hora, vira data. Quase todo o resto é tratado como número, inclusive booleano. No BigQuery é o contrário: o que não é número nem data vira texto. Converta para texto, no próprio SELECT, a coluna que não é número de verdade (hora sem data, UUID).
• Tempo de consulta: a consulta da carga não tem tempo limite no Agente ETL. Quem corta é o banco, se tiver limite próprio.

Os nós seguintes enxergam as colunas pelo nome em maiúsculas. Dê alias a toda coluna calculada (SUM(valor) AS VALOR_TOTAL), senão o nome vem do banco e muda de um banco para outro. Liste as colunas em vez de SELECT *: uma coluna nova na origem muda a saída do nó sem aviso.

Variáveis no SQL

Escreva {NOME} ou {NOME:formato} no texto da consulta. O Agente ETL troca pelo valor antes de mandar ao banco. As variáveis da carga são {StartDate} e {EndDate} na Extração Janela e {LastDataPoint} na Incremental; a lista completa e os formatos estão em variáveis.

SELECT p.id           AS PEDIDO_ID,
       p.data_emissao AS DATA_EMISSAO,
       p.valor_total  AS VALOR_TOTAL
FROM pedidos p
WHERE p.data_emissao BETWEEN '{StartDate:yyyy-MM-dd}' AND '{EndDate:yyyy-MM-dd}'

{StartDate} e {EndDate} existem em toda Extração: fora da Janela valem 01/01/1910 e 01/01/2100, e o filtro por data deixa passar a tabela inteira. {LastDataPoint} vale 0 fora da Incremental. Uma variável que não existe na execução fica no texto como foi escrita e chega assim ao banco. O que cada Extração pede à origem está em tipos de carga.

Conexão por variável

Com Conexão por variável ligada, o nó lê a conexão de uma variável do Tenant em vez de uma conexão cadastrada. No YAML, isso é Credential: var-NOME. Serve para o mesmo Dataflow rodar contra bancos diferentes.

• A variável guarda a connection string do banco, no formato do driver.
• Várias connection strings separadas por vírgula viram vários bancos lidos pelo mesmo nó, um depois do outro, e as linhas saem juntas. Para uma vírgula que faz parte da connection string, escreva \,.
• No BigQuery, a variável guarda um JSON com projectId e key (a chave da service account) e aceita um projeto só.

Um nó com conexão por variável não muda quando você move os Dataflows de uma conexão para outra: para trocar o banco, altere o valor da variável.

SQL por tipo de banco

O tipo do nó acompanha a conexão. Trocar a conexão do nó, mover os Dataflows para outra conexão ou instalar um template com mapa de conexões faz o nó virar o tipo do banco novo. O SQL não é traduzido, por isso o nó pode guardar um SQL próprio por banco.

1. Abra o nó e clique em Editar Consulta SQL.
2. Clique em SQL para outro banco e escolha o banco. A aba nova nasce com uma cópia do Padrão.
3. Ajuste o que muda e clique em Salvar.

Na execução, o Agente ETL roda o SQL do banco da conexão do nó quando ele existe; os outros bancos rodam o Padrão. A aba que roda com a conexão atual leva a marca roda aqui, e o painel do nó mostra "SQL de Firebird · +1 banco". As variáveis valem nas duas abas.

options:
  Credential: erp-producao
  SQL: |
    SELECT nome + ' - ' + codigo AS DESCRICAO FROM produtos
  SQLByKind:
    ExtractFirebird: |
      SELECT nome || ' - ' || codigo AS DESCRICAO FROM produtos

NOTE

Quem escolhe o SQL é o Agente ETL, a partir da versão 1.29.11. Um Agente ETL anterior ignora as abas extras e roda sempre o Padrão.

Mover Dataflows entre conexões é tarefa de credencial; o mapa de conexões do template fica em templates.

Várias consultas no mesmo nó

Dois marcadores dividem o SQL de um nó em partes que rodam separadas e saem juntas. Valem em todos os bancos, menos no BigQuery.

Marcador	O que faz
{UNION-id}	Começa uma consulta nova, com identificador id. Cada parte roda sozinha, uma depois da outra, e as linhas saem empilhadas. Serve para driver que trava com um UNION ALL grande
<CONNECTION-n>...</CONNECTION-n>	SQL só da conexão de posição n (a primeira é 0) quando a conexão é por variável com várias connection strings. As conexões sem bloco próprio rodam o SQL fora dos blocos

SELECT ID, VALOR FROM VENDAS_2025
{UNION-2026}
SELECT ID, VALOR FROM VENDAS_2026

Toda parte precisa devolver o mesmo número de colunas, com os mesmos tipos, na mesma ordem da primeira. Se não, o nó falha com "Número de colunas diferente. Esperado: 2, Encontrado: 3" ou "Tipo da coluna ... incompatível". O identificador não pode ser vazio nem repetido.

Particularidades por banco

Banco	O que observar
PostgreSQL	Concatenação com ||. Nome sem aspas é lido em minúsculas pelo banco; as colunas saem em maiúsculas do mesmo jeito
MySQL	Nome com crase (`pedido`) quando é palavra reservada
SQL Server	Concatenação com +, nome com colchetes ([Valor Total]). Na autenticação Windows, quem acessa o banco é a conta do serviço do Agente ETL
OracleDB	Prefixe o schema (HR.FUNCIONARIOS) quando o usuário da conexão não é o dono da tabela. O nó roda SELECT, não bloco PL/SQL
Firebird	Concatenação com ||. Tabela criada com aspas ("Tabela") só é achada com aspas. Banco antigo costuma usar charset WIN1252 ou ISO8859_1: acento quebrado na saída é charset errado na conexão
IBM Informix	A conexão precisa do Informix Server certo, além do banco
InterSystems IRIS	A connection string é montada pelos pares chave e valor da conexão
ODBC	Serve para banco sem nó próprio, como DB2 ou Access. Instale o driver ODBC na máquina do Agente ETL. A sintaxe do SQL é a do banco por trás do driver
Google BigQuery	Tabela com o caminho completo, projeto.dataset.tabela. Não aceita {UNION-id} nem várias connection strings

Relacionado

• Índice dos nós
• Tipos de carga
• Variáveis

Pelo Lumo CLI

O nó também pode ser escrito e versionado em YAML. Veja a referência de flow.