> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Embedded database
> Open HelixDB directly inside your process with explicit storage and cache settings
Guide
Embedded clients execute operation-tree requests without HTTP. The process opens a
writer or read-only handle against memory, disk, or S3-compatible object storage.
## Install
Install the forthcoming v3 SDK and its embedded runtime package. These package
commands describe the upcoming release and are not expected to resolve before the
v3 SDKs are published.
```bash Rust theme={"languages":{"custom":["languages/helixql.json"]}}
cargo add helix-db@3.0.0 --features embedded
```
```bash TypeScript theme={"languages":{"custom":["languages/helixql.json"]}}
npm install @helix-db/helix-db@3.0.0 @helix-db/uniffi
```
```bash Go theme={"languages":{"custom":["languages/helixql.json"]}}
go get github.com/helixdb/helix-db/sdks/go
```
```bash Python theme={"languages":{"custom":["languages/helixql.json"]}}
python -m pip install helix-db helix-db-embedded
```
## Open a writer
```rust Rust theme={"languages":{"custom":["languages/helixql.json"]}}
use helix_db::{Client, HelixDbSource};
let client = Client::open(HelixDbSource::Disk {
root: "/data/helix".into(),
database: "app".to_string(),
})
.await?;
```
```ts TypeScript theme={"languages":{"custom":["languages/helixql.json"]}}
const client = await Client.embedded({
kind: "disk",
root: "/data/helix",
database: "app",
});
```
```go Go theme={"languages":{"custom":["languages/helixql.json"]}}
client, err := helix.NewEmbeddedClient(
helix.DiskSource{Root: "/data/helix", Database: "app"},
)
if err != nil {
return err
}
```
```python Python theme={"languages":{"custom":["languages/helixql.json"]}}
from helixdb import Client, Disk
client = Client.embedded(Disk("/data/helix", "app"))
```
## Choose a storage source
| Source | Persistence | Use |
| -------------- | -------------------------------- | ---------------------------------------------------- |
| In-memory | Process-local | Tests, scratch data, and short-lived tools |
| Disk | Filesystem path | Persistent single-host applications |
| Object storage | Bucket and logical database path | Durable shared storage with an S3-compatible service |
```ts In-memory theme={"languages":{"custom":["languages/helixql.json"]}}
const client = await Client.embedded({
kind: "inMemory",
database: "app",
});
```
```ts Disk theme={"languages":{"custom":["languages/helixql.json"]}}
const client = await Client.embedded({
kind: "disk",
root: "/data/helix",
database: "app",
});
```
```ts Object storage theme={"languages":{"custom":["languages/helixql.json"]}}
const client = await Client.embedded({
kind: "objectStorage",
database: "app",
bucket: "helix-production",
region: "eu-west-2",
});
```
## Configure caches
Cache configuration is optional and fixed when the handle opens. Omit it to use these
defaults:
| Setting | Default |
| ---------------- | --------------------------------------------------------------------- |
| Profile | Memory |
| Vector memory | 256 MiB, hydrated and refreshed in the background |
| SlateDB | Default in-memory block and metadata caches, warmed in the background |
| Full-text search | 64 MiB in-memory split cache, warmed in the background |
| Disk cache | Disabled |
Pass an explicit cache configuration to change the vector-memory budget or enable
bounded disk caches:
| Profile | Behavior |
| ------- | ------------------------------------------------------------- |
| Memory | Uses in-memory database caches |
| Hybrid | Adds bounded disk caches with explicit paths and byte budgets |
```ts Memory theme={"languages":{"custom":["languages/helixql.json"]}}
const client = await Client.embedded(
{ kind: "disk", root: "/data/helix", database: "app" },
{
vectorMemoryBytes: 512 * 1024 * 1024,
mode: { kind: "memory" },
},
);
```
```ts Hybrid theme={"languages":{"custom":["languages/helixql.json"]}}
const client = await Client.embedded(
{ kind: "disk", root: "/data/helix", database: "app" },
{
vectorMemoryBytes: 512 * 1024 * 1024,
mode: {
kind: "hybrid",
slateMemoryBytes: 256 * 1024 * 1024,
slateDiskPath: "/var/cache/helix/slate",
slateDiskBytes: 4 * 1024 * 1024 * 1024,
objectStoreDiskPath: "/var/cache/helix/objects",
objectStoreDiskBytes: 8 * 1024 * 1024 * 1024,
},
},
);
```
Cache byte budgets bound those caches. They are not a hard cap on total process RSS;
requests and index work can allocate transient memory.
## Open a read-only database
Use a read-only handle for processes that must never mutate the database. It opens an
existing disk or object-storage database, executes read requests, and rejects writes.
```rust Rust theme={"languages":{"custom":["languages/helixql.json"]}}
use helix_db::{Client, HelixDbSource};
let reader = Client::open_reader(HelixDbSource::Disk {
root: "/data/helix".into(),
database: "app".to_string(),
})
.await?;
```
```ts TypeScript theme={"languages":{"custom":["languages/helixql.json"]}}
const reader = await Client.embeddedReader({
kind: "disk",
root: "/data/helix",
database: "app",
});
```
```go Go theme={"languages":{"custom":["languages/helixql.json"]}}
reader, err := helix.NewEmbeddedReaderClient(
helix.DiskSource{Root: "/data/helix", Database: "app"},
)
if err != nil {
return err
}
```
```python Python theme={"languages":{"custom":["languages/helixql.json"]}}
from helixdb import Client, Disk
reader = Client.embedded_reader(Disk("/data/helix", "app"))
```
## Embedded request rules
* Use the same `QueryRequest` and response contract as server mode.
* Writer handles can execute read and write requests.
* Server routing options such as writer-only, warm-only, API headers, and durability
headers are rejected because there is no gateway.
* Reopen the same disk or object-storage source to retain canonical data across process
lifetimes.
## Next steps
Run the production-shaped HTTP interface on your machine.
Compare local server, embedded, and Cloud execution.