Connect a data warehouse (ODBC)
Five warehouses on five tabs. The ODBC flow is the same on every one — install the driver, create a DSN, create the App in DashboardFox — only the specifics change.
By the end of this lesson
- A working ODBC connection to your warehouse
- An app users can query live
You'll need
- Warehouse credentials (and any service-account or key file) from your data team
- Ability to install an ODBC driver on the DashboardFox server
- Admin role in DashboardFox
Background
Google BigQuery is a serverless cloud data warehouse — you store and query data in Google Cloud, and Google bills you per byte scanned. DashboardFox connects to it via Simba's ODBC driver, which auto-installs from the DashboardFox UI.
BigQuery's auth model is unusual: instead of a username and password, you authenticate with a service account (a non-human GCP identity) and a JSON key file downloaded from the GCP console. You'll upload that key file into DashboardFox during setup.
The whole flow is three stages, and all three happen inside Settings → Integrations:
- Install the BigQuery ODBC driver. One click in DashboardFox.
- Create a DSN (a named connection profile) with your project ID, dataset, and service account email. Upload the JSON key.
- Create the App in DashboardFox that points at the DSN.
Then grant yourself access (covered in Step 5 below — the step that catches almost everyone).
DashboardFox supports more ODBC drivers than the five tabs cover here. Auto-install drivers also available: Amazon Athena, Starburst Trino, Vertica. Customer-upload drivers (vendor login required): Databricks, Oracle Instant Client, SAP HANA, Teradata. The flow is the same — install or upload, create the DSN, create the App. If yours is in this list and you'd like a hand, email team@dashboardfox.com.
Stuck on any step? Email team@dashboardfox.com with the error message and what step you're on. Same business day reply.
Do it
-
Install the BigQuery ODBC driver
In DashboardFox, go to Settings → Integrations → ODBC Driver. You'll see a list of drivers. Find Google BigQuery and click Install.
Installation takes 10–15 seconds. When it finishes, a green Installed badge appears next to the driver. If it takes longer than ~30 seconds, refresh the page — something probably went wrong (most often the server lost network briefly during the download).
-
Create the DSN (the named connection)
Still in Settings → Integrations, switch to the ODBC Connections sub-tab and click New Connection. Pick Google BigQuery from the driver dropdown.
Fill in the form:
- Connection name — your DSN name. Use lowercase letters and digits only — no spaces, no underscores, no hyphens. Example:
mybigquery. You'll reference this name later when creating the App. - Service Account Email — the email you copied in Block 2.
- GCP Project ID (Catalog) — your project ID.
- Default Dataset — your dataset name.
- OAuth Mechanism — choose 0 - Service Account.
Click Create. The DSN appears in the list with an Untested status. That's expected — the key file goes up next.
- Connection name — your DSN name. Use lowercase letters and digits only — no spaces, no underscores, no hyphens. Example:
-
Upload the JSON service account key
Click the chevron next to your new DSN to expand it. You'll see a Credential Files section.
Click Upload Credential. Give it a name (e.g.,
bigquery key), pick JSON Service Account as the type, confirm the Linked Connection is your new DSN (auto-selected if you only have one), choose your downloaded JSON file, and click Upload.Now click Test on the DSN. You should see Connection Successful in green. If you see an error, jump to Block 5 — most BigQuery test failures are one of three causes.
-
Create the App in DashboardFox
Switch to the Active Integrations sub-tab. Click Create App.
- App Type — Database
- App Name — anything friendly. Example:
BigQuery Sales. Doesn't have to match the DSN name. - Database Driver — ODBC
- Database Platform — MySQL (yes, MySQL — DashboardFox's MySQL dialect handles BigQuery's SQL well)
- ODBC Dataset Name — type the DSN connection name from Step 2 exactly (
mybigqueryin the example)
Click Test Connection. Green check means DashboardFox successfully reached BigQuery through the driver. Click Save & Apply.
-
Grant yourself access — the step that catches everyone
Saving the app doesn't grant access to it — not even to you. Connecting and granting access are deliberately separate steps; that's what stops a new data source from being accidentally exposed before you've decided who should see it.
Go to Settings → Security → Apps, find your new app, click Edit, and assign yourself the App Builder role. Click Save & Apply.
Refresh the page; the app appears in App Builder, ready for the semantic-layer work in Module 3. To grant other users: Composer for people who'll build reports on this data, Agent for people who'll just run them. The Roles & permissions lesson covers the model in depth.
You have a working connection. Below is what to tighten before real users see it. Skip if you're just testing.
Make it real
Cap your BigQuery spend before you connect a dashboard
BigQuery charges per byte scanned. A single unfiltered SELECT * across a partitioned multi-TB table can cost real money. Before letting users build dashboards: in the GCP console, go to Billing → Budgets & alerts and set a project-level budget alert. Then on each large table, enable partition filter required so unfiltered scans error out instead of scanning everything.
Scope the service account narrowly
Don't grant the DBF service account roles at the project level — grant them at the dataset level. In the GCP console, open the dataset, click Sharing → Permissions, and add the service account with BigQuery Data Viewer on this specific dataset only. Add BigQuery Job User at the project level (it's the minimum scope for that role). If DBF is later compromised, blast radius is one dataset, not the whole warehouse.
Plan key rotation
JSON service account keys don't expire by default. Rotate them: GCP IAM → service account → Keys → Add Key, download the new JSON, then in DashboardFox expand the DSN, delete the old credential, upload the new one. Test, then go back to GCP and delete the old key. Quarterly rotation is a reasonable starting cadence.
Use Cloud Logging to track DBF usage
Every BigQuery query through ODBC is logged in Cloud Logging under the service account's identity. Filter on the service account email to see exactly what DashboardFox is running. Useful for cost attribution, security review, and debugging slow reports.
If you're stuck
Almost every BigQuery test failure is one of these.
Test fails: "403 Permission denied" or "User does not have bigquery.jobs.create permission"
The service account is missing required roles. Grant it both BigQuery Data Viewer (on the dataset) and BigQuery Job User (at the project level). Both are required — Data Viewer alone lets you see metadata but not run queries.
Test passed, but no tables visible in App Builder
The DSN connected, but pointed at the wrong dataset. Dataset names are case-sensitive. Check the spelling and casing in your DSN's Default Dataset field, save, and re-test. If the dataset is correct but still empty, confirm the service account has Data Viewer on that specific dataset.
I uploaded the wrong key file — how do I replace it?
Expand the DSN, click the credential file's delete icon, then upload the correct one. The DSN keeps its other settings — only the credential changes.
Test fails: "Driver not installed" or "Could not load driver"
The driver install didn't finish cleanly. Go back to Settings → Integrations → ODBC Driver. If Google BigQuery shows anything other than Installed, click Install again. If it shows Installed but the test still fails, contact us — the install file may be corrupt and need a fresh download.
My app is set up but I can't see it in App Builder
You skipped Step 5 — granting yourself the App Builder role on the new app. Go to Settings → Security → Apps, edit your app, assign yourself App Builder, save. Creating an app and being granted access to it are deliberately separate steps. The Roles & permissions lesson covers why.
None of these match my situation
Email team@dashboardfox.com with the error message and which step you're on. Real human, same business day.
Background
Snowflake is a multi-cloud data warehouse — your data lives in AWS, Azure, or GCP regions and Snowflake handles the compute. DashboardFox connects to it via Simba's Snowflake ODBC driver, which auto-installs from the DashboardFox UI.
Auth is straightforward: a Snowflake user with a password, plus the database, the compute warehouse, and (optionally) a schema and role. The compute warehouse is the part that catches new users — Snowflake separates storage (databases) from compute (warehouses), and you have to specify which warehouse runs your queries.
The flow is the same three stages as every ODBC connection in DashboardFox:
- Install the Snowflake ODBC driver (one click).
- Create a DSN with your account URL, database, warehouse, and credentials.
- Create the App in DashboardFox pointing at the DSN.
Then grant yourself access on the app (Step 4 below).
DashboardFox supports more ODBC drivers than the five tabs cover here. Auto-install drivers also available: Amazon Athena, Starburst Trino, Vertica. Customer-upload drivers (vendor login required): Databricks, Oracle Instant Client, SAP HANA, Teradata. The flow is the same — install or upload, create the DSN, create the App. If yours is in this list and you'd like a hand, email team@dashboardfox.com.
Stuck on any step? Email team@dashboardfox.com with the error message and what step you're on. Same business day reply.
Do it
-
Install the Snowflake ODBC driver
In DashboardFox, go to Settings → Integrations → ODBC Driver. Find Snowflake in the driver list and click Install. About 15–20 seconds — wait for the green Installed badge.
-
Create the DSN
Switch to the ODBC Connections sub-tab and click New Connection. Pick Snowflake from the driver dropdown.
- Connection name — DSN name. Lowercase letters and digits, no spaces, no underscores, no hyphens. Example:
snowflakeprod. - Server — your Account URL (e.g.,
acmeco-prod123.snowflakecomputing.com). - Database — the database name.
- Warehouse — the compute warehouse name.
- Schema — optional, leave blank for
PUBLIC. - Role — optional, leave blank to use the user's default.
- UID — the Snowflake username.
- PWD — the password.
Click Create, then Test. Green Connection Successful means you're in.
- Connection name — DSN name. Lowercase letters and digits, no spaces, no underscores, no hyphens. Example:
-
Create the App in DashboardFox
Switch to Active Integrations and click Create App.
- App Type — Database
- App Name — anything friendly (e.g.,
Snowflake Sales). - Database Driver — ODBC
- Database Platform — MySQL
- ODBC Dataset Name — type the DSN connection name from Step 2 exactly
Click Test Connection, then Save & Apply.
-
Grant yourself access — the step that catches everyone
Saving the app doesn't grant access to it — not even to you. Connecting and granting access are deliberately separate steps; that's what stops a new data source from being accidentally exposed before you've decided who should see it.
Go to Settings → Security → Apps, find your new app, click Edit, and assign yourself the App Builder role. Click Save & Apply.
Refresh the page; the app appears in App Builder, ready for the semantic-layer work in Module 3. To grant other users: Composer for people who'll build reports on this data, Agent for people who'll just run them. The Roles & permissions lesson covers the model in depth.
You have a working connection. Below is what to tighten before real users see it. Skip if you're just testing.
Make it real
Use a dedicated DBF user, role, and warehouse
In Snowflake, create three things: a role DBF_READER, a user dashboardfox with that role as default, and (optionally) a warehouse DBF_WH sized X-Small with auto-suspend at 60 seconds and auto-resume on. Then GRANT USAGE on the database/schema and SELECT on tables to the role. Easy to audit, easy to revoke if needed.
Right-size the warehouse for dashboard latency
Start with X-Small. If reports lag, scale to Small or Medium. Auto-suspend after 60 seconds keeps idle cost near zero — the warehouse only runs while DBF is querying. Don't oversize for "just in case" — a Medium warehouse running 24/7 dwarfs the cost of a right-sized one that wakes up for queries.
Lock down with Network Policies
If your Snowflake account is exposed to the internet, set a Network Policy that allows only DashboardFox's outbound IPs and your team's office IPs. Account → Security → Network Policies. Apply it at account level or just to the DBF user.
Track DBF cost with QUERY_HISTORY
Snowflake's SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY view records every query with the user and warehouse. Filter on the DBF user to see what DashboardFox is running and what it costs in credits. Useful for capacity planning and tracking down expensive reports.
If you're stuck
Most Snowflake test failures are one of these.
Test fails: "250001 (08001): Failed to connect"
Account URL format is wrong. The Server field needs <org>-<account>.snowflakecomputing.com — no https://, no trailing slash, no path. If you copied from your browser bar, strip everything except the hostname.
Test passes but reports time out or run very slowly
Two likely causes. The warehouse is sized too small for the query volume — try scaling up one tier in Snowflake. Or the warehouse is auto-suspended and slow to wake up — the first query after a pause adds the resume time (usually a few seconds). Subsequent queries hit a warm warehouse and run fast.
User authenticates but no tables are visible in App Builder
Role permissions are the usual cause. The role needs USAGE on the database, USAGE on the schema, and SELECT on the specific tables. Run SHOW GRANTS TO ROLE <your-role> in Snowflake to see exactly what it has.
Test fails: "Incorrect username or password"
Verify the user can sign in to Snowflake's web UI with the same credentials. If MFA is enforced on the user, the ODBC connection won't be able to satisfy the prompt — disable MFA on the DBF user (a dedicated DBF user behind Network Policies + a strong password is the recommended pattern).
My app is set up but I can't see it in App Builder
You skipped Step 4 — granting yourself the App Builder role. Go to Settings → Security → Apps, edit your app, assign yourself App Builder, save.
None of these match my situation
Email team@dashboardfox.com with the error and step. Real human, same business day.
Background
Amazon Redshift is AWS's data warehouse. Even though it's PostgreSQL-derived, when you create the App in DashboardFox you'll pick MySQL as the Database Platform — that's the dialect setting DashboardFox uses for Redshift via ODBC.
DashboardFox connects via Amazon's official Redshift ODBC driver (auto-installs). Auth is a standard Redshift user with username and password.
The big difference from BigQuery and Snowflake: Redshift lives inside a VPC, so the network setup is real work. Your VPC security group needs an inbound rule allowing DashboardFox's outbound IPs on Redshift's port (5439 by default).
The flow is the same three stages:
- Install the Redshift ODBC driver.
- Create a DSN with your cluster endpoint and credentials.
- Create the App in DashboardFox pointing at the DSN.
Then grant yourself access (Step 4).
DashboardFox supports more ODBC drivers than the five tabs cover here. Auto-install drivers also available: Amazon Athena, Starburst Trino, Vertica. Customer-upload drivers (vendor login required): Databricks, Oracle Instant Client, SAP HANA, Teradata. The flow is the same — install or upload, create the DSN, create the App. If yours is in this list and you'd like a hand, email team@dashboardfox.com.
Stuck on any step? Email team@dashboardfox.com with the error message and what step you're on. Same business day reply.
Do it
-
Install the Redshift ODBC driver
In DashboardFox, Settings → Integrations → ODBC Driver. Find Amazon Redshift, click Install. Wait for the green Installed badge.
-
Create the DSN
ODBC Connections sub-tab → New Connection → driver: Amazon Redshift.
- Connection name — DSN name. Lowercase letters and digits, no spaces, no underscores, no hyphens. Example:
redshiftprod. - Host — the cluster endpoint hostname.
- Port —
5439(or your cluster's port). - Database — the database name.
- UID — Redshift username.
- PWD — password.
Click Create, then Test. Green = the VPC rule is open and credentials are valid.
- Connection name — DSN name. Lowercase letters and digits, no spaces, no underscores, no hyphens. Example:
-
Create the App in DashboardFox
Active Integrations → Create App.
- App Type — Database
- App Name — anything friendly (e.g.,
Redshift Analytics). - Database Driver — ODBC
- Database Platform — MySQL (yes, MySQL — even though Redshift is Postgres-derived, DashboardFox's MySQL dialect is what works here)
- ODBC Dataset Name — the DSN connection name from Step 2
Test Connection → Save & Apply.
-
Grant yourself access
Saving the app doesn't grant access to it — not even to you. Connecting and granting access are deliberately separate steps; that's what stops a new data source from being accidentally exposed before you've decided who should see it.
Go to Settings → Security → Apps, find your new app, click Edit, and assign yourself the App Builder role. Click Save & Apply.
Refresh the page; the app appears in App Builder, ready for the semantic-layer work in Module 3. To grant other users: Composer for people who'll build reports on this data, Agent for people who'll just run them. The Roles & permissions lesson covers the model in depth.
You have a working connection. Below is what to tighten before real users see it. Skip if you're just testing.
Make it real
Read-only Redshift user with explicit GRANTs
Don't connect DBF as the master user. Create a dedicated user, then GRANT USAGE ON SCHEMA <schema> TO <dbf_user> and GRANT SELECT ON ALL TABLES IN SCHEMA <schema> TO <dbf_user>. For new tables added later, add ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT SELECT ON TABLES TO <dbf_user> so they're picked up automatically.
Use WLM queues to isolate dashboard load
Redshift's Workload Management lets you assign users to query queues with concurrency limits. Put the DBF user in a dedicated queue with a sensible concurrency cap so a runaway dashboard doesn't crowd out ETL jobs. Configure in the AWS console under your cluster's Workload management parameter group.
Materialize big aggregations
Reports that aggregate over multi-billion-row fact tables run faster against a materialized view than the raw table. CREATE MATERIALIZED VIEW dashboard_summary AS SELECT ..., refresh on a schedule, and point DBF reports at the view. Same SQL surface, much faster response.
VACUUM and ANALYZE on cadence
If you load data with INSERT rather than COPY, run VACUUM regularly to reclaim space and keep sort keys effective. ANALYZE keeps the query planner's stats fresh — stale stats produce bad query plans, which produces slow dashboards.
If you're stuck
Most Redshift test failures are network-related — that VPC rule.
Test fails: "Could not connect" or hangs and times out
The VPC security group is blocking DashboardFox. In AWS, find the cluster's security group, edit inbound rules, and confirm there's a rule allowing each of DBF's outbound IPs on port 5439 (or your cluster's port). The cluster also needs to be publicly accessible (or DBF needs to be in a peered VPC — uncommon).
First query is slow, subsequent ones are fast
Redshift compiles and caches query plans the first time it sees a query. The first run pays the compile cost; subsequent runs of the same shape hit the cache and are fast. Not a bug — it's how Redshift works.
Connection succeeds but no schemas or tables visible
The DBF user can sign in but lacks USAGE on the schema or SELECT on the tables. Run GRANT USAGE ON SCHEMA <schema> TO <dbf_user> and GRANT SELECT ON ALL TABLES IN SCHEMA <schema> TO <dbf_user> as a privileged user.
"Password authentication failed for user"
Verify the user can run psql against the cluster from somewhere with network access using the same credentials. If yes, the credentials are right and the issue is elsewhere — usually MFA or temporary credentials. Use a permanent password user for the DBF connection.
My app is set up but I can't see it in App Builder
Step 4 wasn't done. Settings → Security → Apps → edit → assign yourself App Builder.
None of these match my situation
Email team@dashboardfox.com with the error and step. Same business day reply.
Background
Dremio is a data lakehouse query engine — it queries data directly from S3, ADLS, GCS, or other lake storage without moving the data first. DashboardFox connects via the Arrow Flight SQL ODBC driver (auto-installs).
Important — and different from the other tabs: when you create the App in DashboardFox, pick Dremio from the Database Platform dropdown, not MySQL. DashboardFox has a dedicated Dremio dialect that handles Dremio's SQL flavor correctly. Pick MySQL and your reports will throw syntax errors.
Auth: a Dremio username plus a Personal Access Token (PAT). Use the token as the password.
The flow is the same three stages, with the dialect switch at the App-creation step:
- Install the Dremio ODBC driver.
- Create a DSN with your Dremio host, port, and credentials.
- Create the App in DashboardFox — Database Platform: Dremio.
Then grant yourself access (Step 4).
DashboardFox supports more ODBC drivers than the five tabs cover here. Auto-install drivers also available: Amazon Athena, Starburst Trino, Vertica. Customer-upload drivers (vendor login required): Databricks, Oracle Instant Client, SAP HANA, Teradata. The flow is the same — install or upload, create the DSN, create the App. If yours is in this list and you'd like a hand, email team@dashboardfox.com.
Stuck on any step? Email team@dashboardfox.com with the error message and what step you're on. Same business day reply.
Do it
-
Install the Dremio ODBC driver
In DashboardFox, Settings → Integrations → ODBC Driver. Find Dremio (Arrow Flight SQL), click Install. Wait for the green Installed badge.
-
Create the DSN
ODBC Connections → New Connection → driver: Dremio.
- Connection name — DSN name. Lowercase letters and digits, no spaces, no underscores, no hyphens. Example:
dremiocloud. - HOST — Dremio host (e.g.,
data.dremio.cloud). - PORT —
443for cloud or TLS-enabled self-hosted. - UseEncryption —
truefor cloud. - Schema — optional default path.
- UID — Dremio username.
- PWD — your PAT.
Click Create, then Test.
- Connection name — DSN name. Lowercase letters and digits, no spaces, no underscores, no hyphens. Example:
-
Create the App — pick Dremio as the platform
Active Integrations → Create App.
- App Type — Database
- App Name — anything friendly (e.g.,
Dremio Lake). - Database Driver — ODBC
- Database Platform — Dremio ← not MySQL. DashboardFox has a dedicated Dremio dialect; using MySQL here will produce SQL errors when reports run.
- ODBC Dataset Name — the DSN connection name from Step 2
Test Connection → Save & Apply.
-
Grant yourself access
Saving the app doesn't grant access to it — not even to you. Connecting and granting access are deliberately separate steps; that's what stops a new data source from being accidentally exposed before you've decided who should see it.
Go to Settings → Security → Apps, find your new app, click Edit, and assign yourself the App Builder role. Click Save & Apply.
Refresh the page; the app appears in App Builder, ready for the semantic-layer work in Module 3. To grant other users: Composer for people who'll build reports on this data, Agent for people who'll just run them. The Roles & permissions lesson covers the model in depth.
You have a working connection. Below is what to tighten before real users see it. Skip if you're just testing.
Make it real
Build reflections for the tables your dashboards hit
Reflections are Dremio's accelerated query layer — pre-computed views that queries auto-route to. Without them, dashboards may scan the underlying lake every time and feel slow. In Dremio, identify the tables and queries DBF hits most, build raw or aggregation reflections on those, and Dremio's query planner takes care of the rest. Reports that took 30 seconds drop to under 2 seconds.
Dedicated read-only Dremio user
Create a Dremio user with read-only access to the spaces and sources DBF needs. Generate the PAT from that user's account, not your admin account. Easy to revoke later, easy to audit jobs by user in Dremio's Jobs view.
PAT lifetime and rotation
Dremio PATs have a configurable lifetime. Set a calendar reminder for 30 days before expiration to generate a replacement. Workflow: generate new PAT in Dremio → in DashboardFox edit the DSN → paste new token in PWD → test → save. Then revoke the old PAT in Dremio.
Set the Schema field for cleaner App Builder
If you leave Schema blank, App Builder shows every Dremio space and source the user can see — overwhelming for users who only need one. Set it to your most-used path (e.g., analytics.gold) to scope what's visible.
If you're stuck
The dialect choice trips up almost everyone first time.
Reports throw SQL syntax errors after I added the app
Database Platform was set to MySQL instead of Dremio. Edit the app, change Database Platform to Dremio, save. The error goes away immediately — no rebuild needed.
Connection works but no schemas or sources appear
Either the Schema field on the DSN points to a path the user can't see, or it's pointing at something that doesn't exist. Check the path is exactly correct (case-sensitive) and that the Dremio user has read access. Or leave Schema blank to see everything.
Test fails: "PAT expired" or "Authentication failed"
The token rolled over. Generate a new PAT in Dremio (Account Settings → Personal Access Tokens), edit the DSN in DashboardFox, paste the new token into PWD, save, test.
Reports are slow even though the app connects fine
The queries are scanning the raw data lake. Build reflections in Dremio for the tables and aggregates DBF hits — see Block 4 above.
My app is set up but I can't see it in App Builder
Step 4 — assign yourself App Builder at Settings → Security → Apps.
None of these match my situation
Email team@dashboardfox.com with the error and step. Real human, same business day.
Background
MongoDB Atlas SQL Interface lets DashboardFox query MongoDB collections via SQL — the driver translates SQL to MongoDB's native query language behind the scenes. The driver auto-installs from DashboardFox.
Important constraints:
- Atlas only. This driver is for MongoDB Atlas (cloud-hosted). Self-hosted MongoDB needs a different approach — email team@dashboardfox.com if that's your case.
- Atlas SQL schema must exist first. SQL queries need typed columns; MongoDB documents don't have a fixed schema. Atlas SQL generates one for you — but you have to enable it on each database before connecting from DashboardFox.
The flow is the same three stages:
- Install the MongoDB ODBC driver.
- Create a DSN with your Atlas cluster host, database, and credentials.
- Create the App in DashboardFox.
Then grant yourself access (Step 4).
DashboardFox supports more ODBC drivers than the five tabs cover here. Auto-install drivers also available: Amazon Athena, Starburst Trino, Vertica. Customer-upload drivers (vendor login required): Databricks, Oracle Instant Client, SAP HANA, Teradata. The flow is the same — install or upload, create the DSN, create the App. If yours is in this list and you'd like a hand, email team@dashboardfox.com.
Stuck on any step? Email team@dashboardfox.com with the error message and what step you're on. Same business day reply.
Do it
-
Install the MongoDB ODBC driver
In DashboardFox, Settings → Integrations → ODBC Driver. Find MongoDB Atlas SQL, click Install. Largest driver in the catalog (~220MB) — install can take 30–60 seconds. Wait for the green Installed badge.
-
Create the DSN
ODBC Connections → New Connection → driver: MongoDB.
- Connection name — DSN name. Lowercase letters and digits, no spaces, no underscores, no hyphens. Example:
mongoatlas. - Server — your Atlas cluster hostname.
- Database — the database name.
- SSL — Enabled (Atlas requires it).
- UID — Atlas database username.
- PWD — Atlas database password.
Click Create, then Test.
- Connection name — DSN name. Lowercase letters and digits, no spaces, no underscores, no hyphens. Example:
-
Create the App in DashboardFox
Active Integrations → Create App.
- App Type — Database
- App Name — anything friendly (e.g.,
Mongo Orders). - Database Driver — ODBC
- Database Platform — MySQL
- ODBC Dataset Name — the DSN connection name from Step 2
Test Connection → Save & Apply.
-
Grant yourself access
Saving the app doesn't grant access to it — not even to you. Connecting and granting access are deliberately separate steps; that's what stops a new data source from being accidentally exposed before you've decided who should see it.
Go to Settings → Security → Apps, find your new app, click Edit, and assign yourself the App Builder role. Click Save & Apply.
Refresh the page; the app appears in App Builder, ready for the semantic-layer work in Module 3. To grant other users: Composer for people who'll build reports on this data, Agent for people who'll just run them. The Roles & permissions lesson covers the model in depth.
You have a working connection. Below is what to tighten before real users see it. Skip if you're just testing.
Make it real
Re-generate the Atlas SQL schema after collection changes
Atlas SQL's schema is a snapshot of what your documents looked like when you generated it. Add new fields to your documents, change types, introduce new collections — none of that flows through to DashboardFox until you re-generate the schema in Atlas. For active development databases, set a recurring reminder. For stable production data, generate once and you're set.
Dedicated read-only Atlas user behind a Network Access list
The DBF Atlas user should have read access only — built-in readAnyDatabase on the relevant database, no write or admin permissions. Network Access list should contain only DBF's IPs and your team's office IPs. Avoid the 0.0.0.0/0 shortcut in production — it's the single biggest Atlas exposure mistake.
Embedded documents flatten — review the generated schema
Atlas SQL flattens nested documents into joined virtual tables. If your data has deeply nested structures, the auto-generated schema may produce table and column names that are confusing for end users. Review the schema after generation; you can override names and types in the Atlas SQL schema editor before connecting from DashboardFox.
Watch query patterns for cost surprises
Atlas pricing is largely about cluster compute, not per-query. But if your reports trigger full collection scans (especially on multi-million-document collections), they'll add CPU pressure. Monitor in Atlas → Metrics after connecting DBF; consider indexes on the fields your dashboards filter on most.
If you're stuck
MongoDB-specific stumbles, in order of how often they come up.
Connection works, but App Builder shows no tables
The Atlas SQL schema hasn't been generated. In Atlas, open the database, go to Atlas SQL → Schema, click Generate Schema, wait for it to finish, then refresh App Builder. Atlas SQL needs a typed schema to expose collections as SQL tables.
Test fails: "Connection refused" or hangs and times out
DashboardFox's IPs aren't in the Atlas Network Access list. In Atlas, Security → Network Access, add each of the IPs from Settings → Integrations → Firewall Allow List in DashboardFox.
Test fails: "Authentication failed"
Atlas database user credentials don't match. Verify the user exists in Security → Database Access and that the password is current. Atlas database users are separate from your Atlas account login — easy to confuse.
Nested fields show as JSON strings instead of columns
Atlas SQL didn't fully flatten the structure on schema generation. Open the schema in Atlas, find the field, and adjust its type/representation. Re-generate or update the affected collection's schema entry.
New collections aren't appearing
Re-generate the Atlas SQL schema. New collections after the last generation aren't visible until you do.
My app is set up but I can't see it in App Builder
Step 4 — assign yourself App Builder at Settings → Security → Apps.
None of these match my situation
Email team@dashboardfox.com with the error and step. Same business day reply.
