Como conectar um banco de dados SQL ao Hubviz

Conecte o banco de dados da empresa e crie um cubo a partir de uma consulta SQL. O passo a passo é o mesmo para todos os bancos. Muda só o tipo e a porta.

Quando usar

• Os dados já estão num sistema com banco SQL, como um ERP, um CRM próprio ou um banco de BI.
• Você quer que o cubo atualize sozinho, sem exportar planilhas.
• Você precisa juntar tabelas, filtrar o período ou calcular colunas antes de os dados chegarem ao Hubviz.

Se os dados estão numa planilha, use Excel e CSV ou Google Sheets.

Antes de começar

• Tenha em mãos o endereço do servidor (host), a porta, o nome do banco, um usuário e a senha.
• Prefira um usuário só de leitura. O Hubviz apenas consulta os dados.
• No Hubviz Studio instalado, a conexão sai do seu computador. Se você alcança o banco pela rede da empresa ou pela VPN, o Hubviz também alcança.
• No navegador, a conexão sai dos servidores do Hubviz. O banco precisa aceitar conexões vindas da internet.

Criar a conexão

Campos da conexão

Campo	Obrigatório	O que faz
Nome da conexão	Sim	Apelido da conexão. Aparece na lista de conexões e nos cubos.
Tipo de Banco de Dados	Sim	O banco: SQL Server, PostgreSQL, MySQL, OracleDB, Firebird ou SAP HANA. ODBC aparece só se estiver ligado (veja ODBC).
Nome do banco de dados	Não	O banco dentro do servidor, como erp_aurora. Em branco, vale o banco padrão do usuário.
Host	Sim	Nome ou IP do servidor, sem http://. Exemplos: sql.aurora.local, 10.0.0.15.
Porta	Sim	Preenchida com a porta padrão do banco. Se você trocar o banco e não tiver mexido na porta, ela muda junto.
Usuário	Sim	Usuário do banco.
Senha	Sim	Senha do usuário. O olho ao lado mostra o que você digitou. Depois de salva, a senha fica guardada criptografada.
Criptografar Conexão	Não	Só no SQL Server. Vem marcado. Desmarque apenas se o servidor não aceita conexão criptografada.

Portas padrão

Banco	Porta padrão	Observação
SQL Server	1433	Tem a opção Criptografar Conexão, ligada por padrão
PostgreSQL	5432
MySQL	3306
OracleDB	1521
Firebird	3050
SAP HANA	30015	Precisa do SAP HANA Client instalado. O Hubviz avisa na própria janela
ODBC	Definida no DSN	Veja ODBC

Local ou Nuvem

No topo da janela, Armazenamento define onde a conexão fica guardada.

Opção	Onde fica	Quando usar
Local	Só neste computador. Padrão das conexões novas.	Banco da rede interna, que só este computador alcança.
Nuvem	Na sua conta Hubviz.	Para outras pessoas da equipe usarem a mesma conexão e para atualizar o cubo pela nuvem.

Com Nuvem escolhido, aparece o botão com o ícone de pessoas. Ele abre Acesso ao perfil, onde você escolhe em Usuários com acesso quem pode ver e usar a conexão. Você sempre fica incluído.

Criar o cubo

O cubo abre na aba Editor de Consulta, com as tabelas do banco ao lado do editor.

• Para rodar a consulta, clique no botão com o raio (Executar Consulta) ou aperte F5.
• Não sabe SQL? Clique no botão com as estrelas (Gerar SQL com IA), escolha as tabelas e descreva o que precisa. Veja SQL com IA.

Depois da primeira execução com linhas, a aba Mapeamento de Campos fica disponível para conferir os campos. Veja Campos do cubo.

Exemplo: vendas do ERP da Aurora

A Aurora guarda as vendas num SQL Server da rede interna. A conexão usa estes valores (fictícios):

Campo	Valor
Nome da conexão	ERP Aurora (SQL Server)
Tipo de Banco de Dados	SQL Server
Host	sql.aurora.local
Porta	1433
Nome do banco de dados	erp_aurora
Usuário	bi_leitura
Armazenamento	Local, porque o servidor só existe na rede da empresa

A consulta do cubo Vendas traz uma linha por mês e unidade, com os nomes de coluna que os gráficos vão usar:

SELECT
    CAST(v.data_venda AS date) AS data,
    u.nome                     AS unidade,
    SUM(v.valor_total)         AS receita,
    SUM(v.custo_total)         AS custo,
    MAX(m.valor_meta)          AS meta
FROM vendas v
JOIN unidades u ON u.id = v.unidade_id
LEFT JOIN metas m ON m.unidade_id = u.id AND m.mes = DATEFROMPARTS(YEAR(v.data_venda), MONTH(v.data_venda), 1)
WHERE v.data_venda >= '2026-01-01'
GROUP BY CAST(v.data_venda AS date), u.nome

Depois, no cubo, o campo calculado lucro_bruto = receita - custo completa o modelo. Veja Campos calculados.

ODBC

O ODBC serve para bancos que não estão na lista, desde que exista um driver ODBC e um DSN configurado.

Onde	Campo	O que informar
Hubviz Studio instalado	Selecione o DSN ODBC	Escolha um DSN da lista. Ela mostra os DSNs deste computador com a arquitetura (32 ou 64 bits). Se a lista vier vazia, aparece Nenhum DSN ODBC encontrado.
Navegador	Nome do DSN ODBC	O nome do DSN configurado no servidor que executa a API do Hubviz, não no seu computador.
Navegador	Connection string ODBC (opcional)	Opcional. Se preenchida, substitui o nome do DSN e os campos de usuário.

Banco com driver ODBC só no seu computador funciona pelo Hubviz Studio instalado.

Erros comuns

Mensagem	O que fazer
Verifique se todas as informações obrigatórias foram preenchidas.	Ao testar: falta nome da conexão, host, porta ou usuário.
Por favor, preencha todos os campos antes de enviar o formulário.	Ao salvar: falta o tipo do banco, o host, a porta ou o usuário. No ODBC, falta o DSN.
Selecione um DSN ODBC	Ao testar uma conexão ODBC sem DSN. Escolha um DSN.
Mensagem do próprio banco, como falha de login ou servidor não encontrado	O Hubviz mostra o erro que o banco devolveu. Confira usuário, senha, host e porta, e se o banco aceita conexões da origem certa (seu computador ou a internet).

Cuidados

• Mudou a senha do banco? Edite a conexão uma vez. Todos os cubos que usam essa conexão passam a usar a senha nova.
• Colunas com o mesmo nome na consulta geram erro. Use apelidos, como SELECT c.nome AS cliente, v.nome AS vendedor.
• Para o cubo atualizar sozinho, veja Atualização automática. Banco que só existe na rede interna atualiza pelo agendamento neste computador, não pela nuvem.