Connect Your Database

You can connect one or multipe 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.

Connections API

Use our Connections API to connect your database.

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: '...',
        },
    }),
});

• API Key: This is located on the homepage of your workspace.
• name: Unique name for the database connection.
• type: Which driver to use (Postgres, BigQuery, MongoDB, etc). See full list of support databases here (opens in a new tab).
• 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.

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.
• To use different databases for environments (e.g., production, QA, test) or customers, configure connections with the Environments API.

IP Whitelisting

You can restrict database access by allowing only Embeddable’s IPs:

• US: see here.
• EU: see here.

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