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, via SSH, or via Amazon PrivateLink.
• 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).

• You can call the API directly using tools like Postman (opens in a new tab) or Bruno (link below)

• Or you can use the handy sample javascript scripts in your repo (opens in a new tab).

The below is a CREATE action, but all CRUD operations are available.

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) or Bruno (link below).

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

Note: SSH tunnels are set up per database server. If you need to connect to two different database servers, you’ll need two separate SSH tunnels. However, the same SSH user can be reused if both databases are accessible through the same bastion host.

Amazon PrivateLink

Embeddable supports connecting to your database via Amazon PrivateLink. This allows you to connect to your database without exposing it to the public internet. Your database must be in the same region as Embeddable's deployment (US or EU).

This is an alternative to SSH connections. It is more secure and easier to set up, but it is only available for databases hosted on AWS.

What it means

• No public internet exposure — traffic stays entirely within AWS’s private network
• Available in eu-central-1 and us-east-1 - database must be in the same region as Embeddable's deployment
• Works with any database that supports PrivateLink (e.g. RDS, Redshift, etc)

How it works

• You set up a VPC Endpoint Service (NLB → your DB). For more information, see the AWS Documentation (opens in a new tab)
• You whitelist our Principal ARN in your Endpoint Service
• You share the service name with us
• We connect to your service
• You accept the connection
• You can now make connections via the Connections API using the provided hostname and port

Whitelisting Embeddable's Principal ARN

In order to work with Amazon PrivateLink, you need to whitelist our Principal ARN in your VPC Endpoint Service. This allows us to connect to your database securely without exposing it to the public internet.

For EU and US, the ARN is the same: arn:aws:iam::891377273898:role/EmbeddablePrivateLinkConsumer.

Connect to External Data Platforms

Embeddable works seamlessly with Cube Cloud (opens in a new tab), 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.