Configuration

Configure storage paths and optional OpenAI embedding behavior for a ToriiDB process.

Configuration Sources

ToriiDB has two configuration surfaces:

Surface	How it is set	Scope
Storage directory	Optional argument to `store.New`	One `Store` instance
Embedding settings	Process environment or OS keychain	Shared OpenAI client initialization

Core key-value, JSON, query, TTL, and persistence features do not require an OpenAI credential.

Storage Directory

Create a store with the default directory:

db, err := store.New()

The default is ./temp, resolved from the process working directory. To choose another location, pass one path:

db, err := store.New("/var/lib/toriidb")

store.New rejects more than one path. It creates the root directory when needed, while individual db_0 through db_15 directories and AOF files are initialized lazily.

The process must be able to create directories, write files, rename temporary files, and synchronize the AOF in this location.

Environment Variables

Variable	Required	Default	Purpose
`OPENAI_API_KEY`	No	—	Enables embedding generation and semantic vector search
`TORIIDB_EMBED_DIM`	No	`256`	Requests an embedding with the specified positive dimension

Example shell setup:

export OPENAI_API_KEY="your-api-key"
export TORIIDB_EMBED_DIM="256"

If TORIIDB_EMBED_DIM is missing or not positive, ToriiDB uses 256.

API Key Lookup

The OpenAI client resolves OPENAI_API_KEY in this order:

Process environment.
OS keychain through service name ToriiDB.
If neither source provides a value, vector operations remain disabled.

The keychain implementation uses the platform's credential facility where available. Do not commit credentials to source control or documentation.

Embedding Model

ToriiDB currently uses fixed model text-embedding-3-small. The model is not configurable through the public API. TORIIDB_EMBED_DIM controls the requested dimensions and is also included in internal embedding-cache keys.

A cached vector is reused only when its stored dimension matches the current client dimension.

Network Behavior

Embedding requests use:

Setting	Value
Endpoint	`https://api.openai.com/v1/embeddings`
Request timeout	30 seconds
Encoding	Floating-point array
Background attachment timeout	35 seconds

Plain storage operations do not make network requests. SET ... VECTOR stores the text first, then attaches its vector asynchronously. VSEARCH may perform a synchronous embedding request when its query is not already cached.

Operational Recommendations

Use a dedicated writable directory instead of relying on the current working directory in production.
Call Close during graceful shutdown so pending vector work finishes and AOF logs compact.
Back up the full storage root, including every db_N directory.
Keep the embedding dimension stable for a deployed dataset; entries with a different vector length are skipped by search.
Restrict file permissions and credential access according to the host environment.