Connecting to multiple data sources

A Cube Cloud deployment always has a single default data source plus, optionally, one or more named data sources. Cubes reference whichever source they need via the data_source property.

Manage data sources from your deployment's Settings → Data Sources page.

Adding a data source

Click + Add data source, pick the driver, give the source a short name (see Source name rules), and fill in the connection form — the same form the deployment wizard uses.

Cube Cloud tests the connection before saving; on success it persists the env vars and restarts the development environment, on failure it surfaces the driver's error and saves nothing.

Editing and deleting

Use the Edit action on a row to update credentials, or the Delete action to remove a named source. The default source can be edited but not deleted — to remove it, clear the bare CUBEJS_DB_* variables from Settings → Environment Variables by hand.

Source name rules

• Letters, digits, and underscores; must start with a letter.
• default is reserved; use the Use as default button on the naming step instead.
• Flat names (analytics, warehouse) are safer than names with underscores, which can collide with the env-var parser when they end in _db, _aws, or _jdbc.

Using a data source from a cube

Reference a source from the data_source property using the name you gave it when you created it:

cubes:
  - name: orders_from_other_data_source
    # ...
    data_source: analytics

cube(`orders_from_other_data_source`, {
  // ...
  data_source: `analytics`
})

Cubes that don't set data_source use the default source — there's no need to write data_source: default explicitly, though you can if you prefer to be explicit.

A single query can also span sources: see querying across data sources for appending rows from cubes in different databases into one result set.

For multitenancy scenarios where the data source is selected dynamically per request, see driver_factory and the multitenancy guide.

Workbooks

Sources show up immediately in Workbooks — open a Source SQL tab and they appear in the data sources sidebar without needing a cube to reference them first.

Under the hood

The UI is a friendlier surface over the deployment's environment variables — inspect or hand-edit them from Settings → Environment Variables at any time.

The default source uses bare CUBEJS_DB_* variables; each named source uses a CUBEJS_DS_<NAME>_* prefix. CUBEJS_DATASOURCES is auto-maintained whenever at least one named source exists, with default first and named entries lowercased:

CUBEJS_DATASOURCES=default,analytics
CUBEJS_DB_TYPE=postgres
CUBEJS_DB_HOST=localhost
CUBEJS_DS_ANALYTICS_DB_TYPE=postgres
CUBEJS_DS_ANALYTICS_DB_HOST=remotehost

For the full list of variables that support decoration, see the environment variables reference.

Each source can also build and store its pre-aggregations on a dedicated connection using the CUBEJS_DS_<NAME>_PRE_AGGREGATIONS_DB_* variables. See pre-aggregation data source for details.