How to connect a SQL database to Hubviz

Connect your company database and build a cube from a SQL query. The steps are the same for every database. Only the type and the port change.

When to use it

• Your data already lives in a system with a SQL database, such as an ERP, an in-house CRM or a BI database.
• You want the cube to refresh by itself, without exporting spreadsheets.
• You need to join tables, filter the period or compute columns before the data reaches Hubviz.

If your data is in a spreadsheet, use Excel and CSV or Google Sheets.

Before you start

• Have the server address (host), the port, the database name, a user and the password at hand.
• Prefer a read-only user. Hubviz only queries the data.
• In the installed Hubviz Studio, the connection leaves from your computer. If you reach the database through the company network or the VPN, Hubviz reaches it too.
• In the browser, the connection leaves from the Hubviz servers. The database must accept connections from the internet.

Create the connection

Connection fields

Field	Required	What it does
Connection Name	Yes	Nickname of the connection. Shown in the connection list and in the cubes.
Database Type	Yes	The database: SQL Server, PostgreSQL, MySQL, OracleDB, Firebird or SAP HANA. ODBC shows up only when it is turned on (see ODBC).
Database Name	No	The database inside the server, such as erp_aurora. Left blank, the user’s default database is used.
Host	Yes	Server name or IP, without http://. Examples: sql.aurora.local, 10.0.0.15.
Port	Yes	Filled in with the default port of the database. If you change the database and did not touch the port, it changes too.
Username	Yes	Database user.
Password	Yes	The user’s password. The eye icon shows what you typed. Once saved, the password is stored encrypted.
Encrypt Connection	No	SQL Server only. Checked by default. Uncheck it only if the server does not accept encrypted connections.

Default ports

Database	Default port	Note
SQL Server	1433	Has the Encrypt Connection option, on by default
PostgreSQL	5432
MySQL	3306
OracleDB	1521
Firebird	3050
SAP HANA	30015	Needs the SAP HANA Client installed. Hubviz warns you in the window itself
ODBC	Set in the DSN	See ODBC

Local or Cloud

At the top of the window, Storage sets where the connection is kept.

Option	Where it lives	When to use it
Local	On this computer only. Default for new connections.	A database on the internal network that only this computer reaches.
Cloud	In your Hubviz account.	So other people on the team can use the same connection, and to refresh the cube from the cloud.

With Cloud selected, a button with a people icon shows up. It opens Profile access, where you choose in Users with access who can see and use the connection. You are always included.

Create the cube

The cube opens on the Query Editor tab, with the database tables next to the editor.

• To run the query, click the lightning button (Execute Query) or press F5.
• Don’t know SQL? Click the stars button (Generate SQL with AI), pick the tables and describe what you need. See SQL with AI.

After the first run that returns rows, the Field Mapping tab becomes available to review the fields. See Cube fields.

Example: Aurora’s ERP sales

Aurora keeps its sales in a SQL Server on the internal network. The connection uses these (fictional) values:

Field	Value
Connection Name	Aurora ERP (SQL Server)
Database Type	SQL Server
Host	sql.aurora.local
Port	1433
Database Name	erp_aurora
Username	bi_readonly
Storage	Local, because the server only exists on the company network

The query of the Sales cube returns one row per date and business unit, with the column names the charts will use:

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

Then, in the cube, the calculated field lucro_bruto = receita - custo completes the model. See Calculated fields.

ODBC

ODBC covers databases that are not on the list, as long as there is an ODBC driver and a configured DSN.

Where	Field	What to enter
Installed Hubviz Studio	Select ODBC DSN	Pick a DSN from the list. It shows the DSNs on this computer with their architecture (32 or 64 bit). If the list is empty, you see No ODBC DSN found.
Browser	ODBC DSN name	The name of the DSN configured on the server that runs the Hubviz API, not on your computer.
Browser	ODBC connection string (optional)	Optional. When filled in, it replaces the DSN name and the user fields.

A database whose ODBC driver exists only on your computer works through the installed Hubviz Studio.

Common errors

Message	What to do
Verify if all required information has been filled in.	When testing: the connection name, host, port or user is missing.
Please fill in all fields before submitting the form.	When saving: the database type, host, port or user is missing. For ODBC, the DSN is missing.
Select an ODBC DSN	When testing an ODBC connection without a DSN. Pick a DSN.
A message from the database itself, such as a login failure or server not found	Hubviz shows the error the database returned. Check user, password, host and port, and whether the database accepts connections from the right origin (your computer or the internet).

Good to know

• Changed the database password? Edit the connection once. Every cube that uses it switches to the new password.
• Columns with the same name in the query cause an error. Use aliases, such as SELECT c.name AS customer, s.name AS seller.
• For the cube to refresh by itself, see Automatic refresh. A database that only exists on the internal network refreshes through the schedule on this computer, not through the cloud.