You must connect at least one database to Embeddable so that Embeddable knows where to run the SQL generated by your data models. We call these connections. You add a connection like so:

// for security reasons, this must *never* be called from your client-side
fetch('<https://api.embeddable.com/api/v1/connections>', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${apiKey}` /* keep your API Key secure */
    },
    body: JSON.stringify({
				name: 'my-postgres-db',
				type: 'postgres',
				credentials: {
					host: '...',
					port: '...',
					// ... see db-specific "Example Requests" below
				}
    })
});

Response:
Status 201 { errorMessage: null }

The above represents a CREATE action, but all CRUD operations are available (see Example requests section below).

The apiKey can be found by clicking “Publish” on one of your Embeddable dashboards.

The name is a unique name to identify this connection.

• By default your data models will look for a connection called “default”, but you can supply your models with different data_source names to support connecting different data models to different connections (simply specify the data_source name in the model)

The type tells us which driver to use (postgres, bigquery, mongodb, etc.)

• We currently support all of these databases (but please let us know if your database isn’t in the list). There are “Example requests” for different database types below.

The credentials is a javascript object containing the necessary credentials expected by the driver (see Example requests section below).

• These are securely encrypted and only used to retrieve exactly the data you have described in your data models.
• We strongly encourage you to create a read-only database user for each connection (Embeddable will only ever read from your database, not write).

In order to support connecting to different databases for prod, qa, test, etc (or to support different databases for different customers) you can assign each connection to an environment (see Environments API).

Testing your connection

To test whether Embeddable is able to connect to your database, you can use the /test endpoint (example), like so:

const apiKey = '<your API Key>';
const connectionName = 'my-postgres-db';

fetch(`https://api.embeddable.com/api/v1/connections/${connectionName}/test`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${apiKey}` /* keep your API Key secure */
    },
});

Response:
Status 201 { errorMessage: null }

Using your connection

To use your connection, simply refer to it by name in your models:

cubes:
  - name: customers
    data_source: my-postgres-db # <---- tells Embeddable which db connection to use

...