Environments are a powerful feature of Embeddable that map data models onto database connections.

Relationship between securityContext, Environments API, Connections API, data models and databases.

This mapping is powerful because it allows you to achieve things like:

• different database connections for prod, qa, testing, etc.
  • how: simply create one environment per database
• single-tenancy (AKA database-level security) for the case where each of your customers have their data in a different database
  • how: simply create one environment per customer
• micro service architecture, where your data is spread across multiple databases
  • how: simply map each data model to a different database
• etc.

The way it works is that each data model in your Embeddable deployment defines a data_source like so:

cubes:
  - name: orders
    sql_table: public.orders
		data_source: primary_db # <-- defaults to "default" if not specified

...

If the data_source parameter is not supplied, it defaults its value to “default”.

You then define an environment by mapping the data_source names from your models onto database connections (defined here). Like so:

// for security reasons, this must *never* be called from your client-side
fetch('<https://api.embeddable.com/api/v1/environments>', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${apiKey}` /* keep your API Key secure */
    },
    body: JSON.stringify({
				name: 'prod',
				datasources: [
					{ data_source: 'primary_db', connection: 'prod-postgres'},	
					{ data_source: 'warehouse', connection: 'prod-bigquery'}
				]
    })
});

Response:
Status 201 { errorMessage: null }

The above represents a CREATE action, but all CRUD operations are available.

The name is a unique name to identify this environment.

The datasources is a mapping from data_source names to connection names. It tells Embeddable that when this environment is used, use this set of database connections.

And then when calling the Token API (described here) you simply supply the environment name to tell Embeddable which database to connect to for each of your data models used by your Embeddable dashboard.

• Note: data sources are not something you need to define elsewhere. The above environment definition is all that is needed to tell Embeddable that: when using the “prod” environment, any data models that specify “primary_db” as their data_source should use the credentials from the “prod-postgres” connection to query data from.