Data connections introduction
Data connections are secure integrations between your database and your Hex workspace.
- Users need the Admin workspace role to create workspace data connections.
- Users need Can Edit or higher project permissions to create project data connections.
Hex makes it easy to securely connect to your database. Once you establish a data connection, you can query, transform, visualize, writeback, and use AI agents to analyze your data.
Supported databases
Data connection support tiers
To improve reliability, maintainability, and to bring clarity to users, Hex classifies all data connections into three tiers. These tiers help set expectations around support levels, stability, and feature completeness for each integration.
Tier 1
Tier 1 data connectors are fully supported and actively maintained by Hex. They are tightly integrated into the Hex platform and are suitable for all production workflows. We prioritize improvements and bug fixes for Tier 1 data connectors.
Tier 2
Tier 2 data connectors are stable, reliable, and fully supported by Hex, but they may not receive new features at the same time as Tier 1 data connectors. Feature support for these integrations can land after general availability (GA), based on feasibility and demand.
Tier 3
Tier 3 data connectors are officially supported by Hex and usable in production, but we do not guarantee support of all platform features, like chart cells. There will be reduced coverage if any bugs or issues arise.
Workspace and project data connections
Hex data connections can be created at the workspace level, or the project level.
- Workspace data connections can be used across multiple projects and are shared with all workspace members by default. Only Admins can create workspace-level data connections.
- Project data connections can be used only on the project from which they are created. Admins, Managers and Editors can create project-level data connections.
In general, we recommend using workspace data connections over project data connections. Workspace data connections can be re-used across projects and are centrally managed by Admins, removing the need for non-Admins to have database credentials. Workspace data connections also support automated schema refreshes and data connection permissions.
Admins on the Enterprise plan can disable project-level data connections.
Create a data connection
Start a new data connection
Admins can create a workspace data connection from Settings → Data sources → + Connection.
Alternatively, create a data connection from within your project by navigating to the Data browser sidebar → Warehouse tab in the Notebook view, and selecting Add a data connection.
Admins creating a data connection from a project will see the Share with workspace setting enabled by default, creating a workspace-level data connection. Non-Admins can create only project-level data connections.
Enter database credentials
To create your Hex data connection you will need database credentials. If you don't have credentials, ask your database administrator for assistance.
- Choose your database from the menu.
- Fill in the required fields (Find your database setup guide here).
- Click Create connection.
- If you use a firewall to restrict database access, you'll also need to add Hex's IP addresses to your allowlist.
Admins can save in-progress workspace data connections as a draft. Draft data connections can be accessed from Settings → Data sources.
Configure schema browsing settings
We recommend configuring Schema browsing settings to ensure the best performance and data discoverability for your workspace users and for AI.
Schema refresh schedules
- Scheduled refreshes are available only for workspace data connections.
- Schemas can also be refreshed manually by any user with permissions to do so.
Toggling on Refresh data schema on a schedule sets up a recurring refresh of the database, schema, table, and column metadata that will be visible in the Data browser to users and discoverable by AI agents. On refresh, Hex adds any new schema data available, and removes anything that was deleted. This helps ensure your workspaces users and AI agents have access to up-to-date metadata.
Automated refreshes query your data connection's entire schema. Consider query costs and your data warehouse load when deciding on a cadence schedule.
Schema filtering
Schema filtering limits the databases, schemas, and/or tables that are madee visible to users and to AI agents in the Data browser. This helps focus your workspace users on the relevant data assets, and helps improve AI agent accuracy. Filtering your schema also reduces the time required for schema refreshes, since schema refreshes will only sync non-filtered data objects.
Filtering your connection does not affect the underlying permissions set in your data connection. Even if a database, schema, and/or table is hidden from the Data browser, it can still be queried from if the user has proper permissions to do so.
Use data connections to query your database
Once your data connection is configured, you can query it using a SQL cell, explore your data with AI threads, or analyze it with AI using the notebook agent. Note that new data connections will automatically kick off a schema refresh, which much complete before Hex agents can analyze it.
Some Hex-native functionality, including Query Mode, Pivot cells, and Table display cells, rely on modern CTE functionality when operating on data directly in your warehouse.
If you are using an older version of some data sources (such as PostgreSQL<8.4, MySQL<8.0, or MS Sql Server<2005), you will need to query your data into Hex and utilize these features locally, rather than pointing them directly to your warehouse.
Workspace data connection permissions
Workspace data connections offer additional permissions that can be used to restrict access to sensitive information.
Can query
This permission determines who can use the connection to author queries. By default, all members of a workspace are granted Can query access to a data connection.
This permission can be set to a list of groups to explicitly define which users can use this connection to author queries.
If this connection is imported in a project where a user with Can edit project access does not have Can query access to the data connection, the user will be prevented from authoring queries by being downgraded to Can explore project access.
Admins always have Can query access to data connections.
Can view results
Can view results data permissions are only available on the Enterprise plan.
This permission determines who can view the results of projects where this connection is imported, and can effectively be used to lock users out from projects.
By default, all users are granted Can view results access to a data connection, including any anonymous users if the project is shared with the web.
This permission can be set to a list of groups to explicitly define which users can view results when this data connection is used. Limiting Can view results access to any groups prevents users from attaching screenshots or CSVs to notifications.
If this connection is imported in a project where a user with access to the project does not have Can view results access to the data connection, the user will be prevented from accessing the project.
Admins, and any groups that are granted Can query access always have Can view results access to a data connection.
Can refresh schema
By default, all users that have can query access can manually refresh the data connection schema via the Refresh button in the data browser. To restrict this ability and only allow Admins to manually refresh the data browser, update the "Can refresh schema" setting in your data connection configuration to "Admins only".
Database security
For each data connection, it's possible to configure SSH or SSL/TLS for a more secure connection and encryption in transit. For some data connection types, SSL/TLS is required.
Using Secure Socket Layer (SSL) or Transport Layer Security (TLS) provides an additional layer of security by encrypting data in transit that moves from Hex to your database instance. Some data connection types have SSL/TLS configured by default.
In the table below, Enabled by default indicates that creating a data connection with that database will have encryption in transit enabled by default, and no further action is required. If Configurable, please reference the documentation linked in the first column for instructions on how to configure SSL/TLS for that specific database.
Required means that Hex only supports connecting to an instance of the connection type if it has SSL enabled.
| Data Connection | SSL/TLS |
|---|---|
| Postgres | Required |
| Athena | Enabled by default |
| BigQuery | Enabled by default |
| Databricks | Enabled by default |
| Materialize | Enabled by default |
| Presto | Enabled by default |
| Redshift | Enabled by default |
| Snowflake | Enabled by default |
| MotherDuck | Enabled by default |
| AlloyDB | Configurable |
| Clickhouse | Configurable |
| Cloud SQL (MySQL) | Configurable |
| Cloud SQL (PostgreSQL) | Configurable |
| Cloud SQL (SQL Server) | Configurable |
| DB2 | Configurable |
| Dremio | Configurable |
| MariaDB | Configurable |
| MS SQL Server | Configurable |
| MySQL | Configurable |
| Trino | Configurable |
| Starburst | Configurable |