Connect Your Database

You can connect one or more databases to Embeddable. We call these Connections.

• Read-only access: Embeddable only reads from your database - it never writes to it.
• Connection options: Connect directly or via SSH.
• IP whitelisting: Restrict access to your database by allowing only Embeddable’s fixed IPs (learn more).

Connections API

Use our Connections API to connect Embeddable to your database(s).

The below is a CREATE action, but all CRUD operations are available, with sample scripts in your repo (opens in a new tab).

const apiKey = '<your API Key>';
const connectionName = '<some unique name>';
const BASE_URL = 'https://api.us.embeddable.com'; // US API
// const BASE_URL = 'https://api.eu.embeddable.com'; // EU API
 
const resp = await fetch(`${BASE_URL}/api/v1/connections`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}` /* keep your API Key secure */,
    },
    body: JSON.stringify({
        name: connectionName,
        type: 'postgres', // Database type
        credentials: {
            host: '...',
            database: '...',
            user: '...',
            password: '...',
            port: ..., // optional, number
            ssl: true, // optional, boolean
        },
    }),
});

• apiKey: This is located on the homepage of your workspace.
• connectionName: Unique name for the database connection within your workspace.
• type: Which driver to use (postgres, bigquery, etc). Find your database here.
• credentials: A javascript object containing the credentials expected by the driver:
  • The necessary credentials for each database are available here.
  • Credentials are securely encrypted.
  • We strongly suggest creating a read-only database user for each connection.

CRUD Operations

Refer to the specific scripts in your repo (opens in a new tab) to easily manage connections:

• Create a connection: connection-create.cjs
• List connections: connection-list.cjs
• Read a specific connection: connection-read.cjs
• Update a connection: connection-update.cjs
• Delete a connection: connection-delete.cjs

To run any script, use the following command:

node src/embeddable.com/scripts/<script>.cjs

Or use tools like Postman (opens in a new tab).

Testing Your Connection

To confirm your connection works, use the /test endpoint, which is also available as a script (opens in a new tab) in your repo.

const apiKey = '<your API Key>';
const connectionName = '<some unique name>';
const BASE_URL = 'https://api.us.embeddable.com'; // US API
// const BASE_URL = 'https://api.eu.embeddable.com'; // EU API
 
fetch(`${BASE_URL}/api/v1/connections/${connectionName}/test`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`,
    },
});

Using Your Connection

Reference your database connection by name in your data models:

cubes:
  - name: customers
    data_source: my-postgres-db # Points to the database connection

• Omitting the data_source field defaults to a demo connection named default.

Multiple databases

Embeddable supports connecting to multiple databases out-of-the-box.

To do so, simply:

• create a separate connection for each database (see "Connections API" above)
• then point each of your models at the appropriate connection (see "Using your connection" above).

Sometimes, however, you'll want to point a model at different databases, e.g:

• to run against prod vs qa vs test databases.
• to connect to different databases depending on the customer.

In those cases you'll need use what we call Environments. Learn more here.

IP Whitelisting

You can restrict database access by allowing only Embeddable’s IPs (learn more).

SSH Connections (Bastion Host)

Embeddable also supports connecting to your database via SSH connection. The process works as follows:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMMDhwuLvNxkgh7armnFQ94MjFyA5EnAAYol9uXcj0Xi jump-server-us@embeddable.com

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJFIqQgU/5Cdbe8sTPZ9S3Zy6iTyBRNP7cjZmD5LtlX0 jump-server-eu@embeddable.com

Connect to External Data Platforms

Embeddable works seamlessly with Cube Cloud, allowing you to use your existing Cube models alongside Embeddable.

Follow the setup instructions here to connect your Cube Cloud instance and start using your data.