---
description: >-
  In Epsilla, the data are organized as databases. A database is consisted of
  multiple tables.
---

# Connect to a database

{% hint style="info" %}
There is a slightly difference between Docker and Epsilla Cloud when connecting to a database.
{% endhint %}

## Connect to a database using Epsilla Docker

### Step 0. Download docker image and start

Epsilla vector database docker images can be found at [docker hub](https://hub.docker.com/r/epsilla/vectordb).

Use the command below to pull the latest version of Epsilla vector DB:

```sh
docker pull epsilla/vectordb
```

You can also specify the version to pull:

```bash
docker pull epsilla/vectordb:0.3.1
```

Start the docker as the backend service

```sh
docker run --pull=always -d -p 8888:8888 epsilla/vectordb
```

Use the EMBEDDING\_MODELS environment variable to enable more built-in embedding models (learn more about [embeddings](../advanced-topics/embeddings)):

```bash
docker run --pull=always -d -p 8888:8888 -e EMBEDDING_MODELS="BAAI/bge-small-zh-v1.5,BAAI/bge-base-en" epsilla/vectordb
```

### Step 1. Initialize Client

{% tabs %}
{% tab title="Python" %}
```python
### client connect to localhost
from pyepsilla import vectordb
db = vectordb.Client()


### client connect to remote server
from pyepsilla import vectordb
db = vectordb.Client(
    protocol='http',      # http or https. Default is http
    host='3.100.100.100', # The host machine for the vector db. Default localhost
    port='8888'           # The port for the vector db, default 8888
)
```
{% endtab %}

{% tab title="JavaScript" %}
```javascript
// client connect to localhost
const epsillajs = require('epsillajs');
const db = new epsillajs.EpsillaDB();

// client connect to remote server
const epsillajs = require('epsillajs');
const db = new epsillajs.EpsillaDB({
    protocol: 'http',      // http or https. Default is http
    host: '3.100.100.100', // The host machine for the vector db. Default localhost
    port: '8888'           // The port for the vector db, default 8888
});
```
{% endtab %}
{% endtabs %}

In order to use OpenAI for embedding, pass in X-OpenAI-API-Key header:

{% tabs %}
{% tab title="Python" %}
```python
db = vectordb.Client(
    ...
    headers={
        "X-OpenAI-API-Key": <Your OpenAI API key here>
    }
)
```
{% endtab %}

{% tab title="JavaScript" %}
```javascript
const db = new epsillajs.EpsillaDB({
    ...
    headers: {
        "X-OpenAI-API-Key": <Your OpenAI API key here>
    }
});
```
{% endtab %}
{% endtabs %}

### Step 2. Load database

Use the command to load a database into memory. Epsilla can hold multiple databases in memory at the same time.

{% tabs %}
{% tab title="Python" %}
```python
status_code, response = db.load_db(
    db_name="myDB",         # The name of the DB. Can give any valid
                            # name when loading a DB from disk.
    db_path="/tmp/epsilla", # The path on the disk where the DB is persisted. 
                            # If the path doesn't exist, will create
                            # a new DB at this path.
    vector_scale=1000000,   # (Optional) the limit of the number of records in
                            # the table. Can provide any positive number at
                            # load_db time. If not specified, the default value
                            # is 150000.
    wal_enabled=True        # (Optional) Enable write ahead log or not. Default 
                            # is True. For high throughput low consistency case,
                            # can disable it to save disk IO.
)
```
{% endtab %}

{% tab title="JavaScript" %}
```javascript
const load = await db.loadDB(
    "/tmp/epsilla", // The path on the disk where the DB is persisted. 
                    // If the path doesn't exist, will create
                    // a new DB at this path.
    "MyDB",         // The name of the DB. Can give any valid
                    // name when loading a DB from disk.
    1000000,        // (Optional) the limit of the number of records in
                    // the table. Can provide any positive number at
                    // loadDB time. If not specified, the default value
                    // is 150000.
    true            // (Optional) Enable write ahead log or not. Default 
                    // is True. For high throughput low consistency case,
                    // can disable it to save disk IO.
);
```
{% endtab %}
{% endtabs %}

### Step 3. Use database

You can use the command to switch between multiple databases that are already loaded in memory. Then the following interactions will be towards this database.

{% tabs %}
{% tab title="Python" %}
```python
db.use_db(db_name="myDB")
```
{% endtab %}

{% tab title="JavaScript" %}
```javascript
db.useDB("MyDB");
```
{% endtab %}
{% endtabs %}

## Connect to a vector database on Epsilla Cloud

First, create a vector database on Cloud GUI.

<figure><img src="https://2532879721-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM0ZX7fId7ifK45ldHWEp%2Fuploads%2FUFRqXRndutxPHCRKtWyi%2FScreenshot%202023-11-21%20at%209.42.30%20PM.png?alt=media&#x26;token=9da1358c-883d-46f4-bdc6-411d0da2da27" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
We will support creating vector databases via Python/JavaScript client in the near future.
{% endhint %}

Then connect to the created database. Replace the Project ID, Database ID and API Key.

{% tabs %}
{% tab title="Python" %}
```python
from pyepsilla import cloud
client = cloud.Client(
  project_id="PROJECT-ID",     # Copied from the GUI code snippet
  api_key="YOUR-API-KEY"       # Replace with your API Key
)
db = client.vectordb(db_id="DB-ID") # Copied from the GUI code snippet
```
{% endtab %}

{% tab title="JavaScript" %}
```javascript
const epsillajs = require('epsillajs');
const client = new epsillajs.EpsillaCloud({
  projectID: 'PROJECT-ID',  // Copied from the GUI code snippet
  apiKey: 'YOUR-API-KEY'    // Replace with your API Key
});
const db = new epsillajs.VectorDB(
  'DB-ID',                  // Copied from the GUI code snippet
   client
 ); 
await db.connect();
```
{% endtab %}
{% endtabs %}

The Project ID and Database ID can be copied from the database card under project resources:

<figure><img src="https://2532879721-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM0ZX7fId7ifK45ldHWEp%2Fuploads%2F2PpQm1MFRvws1eQ3cq7x%2FScreenshot%202023-11-22%20at%2010.28.27%20AM.png?alt=media&#x26;token=1240e534-4c9f-4923-99a5-9821975d2696" alt=""><figcaption></figcaption></figure>

The API Key can be created under project configurations:

<figure><img src="https://2532879721-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM0ZX7fId7ifK45ldHWEp%2Fuploads%2FRFhBiLUoRS4LWaNBU2SG%2FScreenshot%202023-11-21%20at%209.19.00%20PM.png?alt=media&#x26;token=3e360af0-99cc-4c69-89fe-508d4c64c1ce" alt=""><figcaption></figcaption></figure>
