This page lists the options you pass when you open a database, and the keys each Barrel application reads from its environment (sys.config), with their defaults. Use it as a lookup; the guides explain when you would change each one.
Open a database
barrel:open/2 takes one map, with a sub-map per layer:
{ok, Db} = barrel:open(<<"notes">>, #{
docdb => #{retention_period => 2592000},
vectordb => #{db_path => "/var/lib/app/vec/notes",
dimensions => 768,
bm25_backend => disk},
encryption => default
}).
| Key | Default | Meaning |
|---|
docdb | #{} | Options for the document store, below |
vectordb | #{} | The vector store config, below, or none for documents only |
embedding | none | An embedding policy: the database runs in record mode. stored reopens with the policy the database saved. |
encryption | disabled | default (key from BARREL_ENCRYPTION_KEY) or #{provider => Mod}. Pass it on every open. See Encryption. |
read_only | false | Open both stores read only |
store_supervised | false | Supervise the vector store instead of linking it to the caller |
Document store (docdb)
These are the options of barrel_docdb:create_db/2. encryption, read_only, channels, conflict_resolver and the retention settings are not stored: pass them again on every open.
| Key | Default | Meaning |
|---|
data_dir | the app env data_dir | Parent folder of the database |
att_opts | blob in RocksDB | Attachment backend: #{backend => none}, or #{backend => s3, s3 => #{bucket => ...}} with barrel_att_s3 |
retention_period | 2592000 (30 days, in seconds) | History kept for audit and point-in-time branches; 0 keeps all and turns the sweeper off |
retention_check_interval | 600000 ms | How often the retention sweep runs |
ttl_sweep_interval | 0 (off) | How often expired documents are removed |
ttl_sweep_batch | 512 | Documents removed per sweep step |
tombstone_purge_after | 0 (keep) | Purge delete stubs after this many seconds |
channels | none | #{Name => [Pattern]}, fixed at creation |
conflict_resolver | none | A resolver for concurrent versions |
max_conflict_versions | 8 | Concurrent versions kept per document |
max_group, write_chunk | 256, 16 | Group commit sizes |
stats_interval | 60000 ms | How often the size and compaction gauges refresh; 0 turns it off |
att_upload_timeout | 3600 s | Longest an attachment upload may stay open |
store_opts | #{} | RocksDB options, see below |
The main store_opts keys. Each applies to every column family of the document store, so memtable memory per database can reach write_buffer_size × max_write_buffer_number × 4.
| Key | Default | Meaning |
|---|
compression, bottommost_compression | zstd | rocksdb always builds zstd. snappy and lz4 work only if rocksdb was built with the system library. |
bloom_bits | 10 | Bloom filter bits per key: a read of a missing key skips the files that cannot hold it |
block_size | 4096 | Table block size, in bytes |
write_buffer_size | 64 MiB | Memtable size before a flush |
max_write_buffer_number | 2 | Memtables per column family before writes wait for a flush |
min_tombstones_for_range_conversion | 64 | A run of this many deletes becomes one range delete at flush, so reads skip it at once. 0 turns it off. |
use_direct_io_for_compaction_reads | false | Compactions read with direct I/O and leave the page cache to your reads. Also accepted in att_opts. Needs a file system with direct I/O (not tmpfs). |
prune_depth, compaction_interval and compaction_size_threshold have no effect since 2.2.0; a database given them logs a warning.
Vector store (vectordb)
| Key | Default | Meaning |
|---|
db_path (or path) | <data_dir>/<name>.vectordb, next to the documents | Where the store lives. A store created before barrel 1.13.0 in priv/barrel_vectordb_<name> under the working directory keeps being used there. |
dimensions (or dimension) | 768 | Vector size |
embedder | none | A barrel_embed provider, such as {ollama, #{model => <<"nomic-embed-text">>}}. Without one, text calls return embedder_not_configured. |
backend | hnsw | hnsw, diskann, or faiss (needs barrel_faiss) |
hnsw | #{m => 16, ef_construction => 200} | Also distance_fn (cosine or euclidean) and quantization (scalar by default, turboquant, subspace_turboquant, none) |
diskann | | #{r, l, base_path} |
faiss | #{index_type => <<"HNSW32">>} | Also nprobe |
bm25_backend | none; disk in record mode | memory or disk turns keyword search on |
read_only | false | Refuse writes |
Embedding policy (embedding)
| Key | Default | Meaning |
|---|
fields | the whole document | Paths whose text is embedded |
join | <<"\n">> | Separator between fields |
mode | async | sync embeds before the write returns |
embedder | | The barrel_embed provider |
dimensions | 768 | Must match the model |
metadata_fields | the document minus id and _ keys | Fields returned as search metadata |
Other keys are refused with {error, {unknown_options, Keys}}.
Application environment
Set these in sys.config. Paths are relative to the working directory of the node unless you give absolute ones.
barrel_server
| Key | Default | Meaning |
|---|
http_port | 8080 | Port of the cleartext HTTP listener, when listeners is not set |
listeners | one HTTP/1.1 listener | #{http => ..., https => ..., http3 => ...} |
tls | none | #{certfile, keyfile, cacertfile, verify, ssl_opts} |
data_dir | barrel_docdb's | Copied into the barrel_docdb data_dir at start. Vector stores follow it, as <data_dir>/<name>.vectordb. |
open_opts | #{} | barrel:open/2 options for every database the server opens |
auth | none (open server) | #{tokens => [...]}, or #{accept => [bearer, signed, mtls], signers => ..., skew_ms => 300000, require_nonce => ...}. See Authentication. |
cors | none | #{origins, expose, max_age}; needed by barrel-lite |
mcp | #{} | #{enabled => true, allowed_origins, allow_missing_origin, resources => full | live_only, live}. See the MCP guide. |
max_body | 1 GiB | Largest request body |
sig_replay_sweep_ms | 60000 | How often seen signature nonces are swept |
[{barrel_server, [
{http_port, 8080},
{data_dir, "/var/lib/barrel"},
{auth, #{tokens => [<<"change-me">>]}},
{cors, #{origins => [<<"https://app.example">>]}}
]}].
The server also sets barrel_docdb's task_db_opener, so replication tasks restored after a restart open their databases the way the server does.
barrel_docdb
| Key | Default | Meaning |
|---|
data_dir | "data/barrel_docdb" | Where databases live |
default_store | barrel_store_rocksdb | Storage module |
block_cache_size | 512 MiB | RocksDB block cache shared by every database |
block_cache_type | clock | Cache kind |
query_timeout_ms | 30000 | Query deadline |
hlc_max_offset | 0 (off) | Largest clock offset accepted from a peer, in ms |
body_async_io | false | Experimental |
metrics | [] | [{exporter, none | console | otlp | {Mod, Map}}, {otlp_endpoint, Url}, {otlp_headers, #{}}, {otlp_compression, none | gzip}] |
tracing | [] | [{enabled, true}, {exporter, ...}, {otlp_endpoint, Url}] |
logging | [] | [{exporter, none | console | file | otlp | {Mod, Map}}, {file_path, ...}, {file_format, text | json}, ...] |
sync_auth, sync_signing, sync_ssl | #{} | Credentials for HTTP replication, keyed by origin or database URL |
task_db_opener | none | {Mod, Fun} that opens a database for a restored task |
See Monitoring for the exporters.
barrel
| Key | Default | Meaning |
|---|
dbs_idle_timeout | 300000 ms | barrel_dbs closes an unused database after this; 0 never |
dbs_max_open | 0 (no limit) | Most databases barrel_dbs keeps open |
dbs_evict_guard | 5000 ms | At the dbs_max_open cap, only a database idle this long is evicted; otherwise the open fails with too_many_open_dbs |
ctx_max_contexts | 8 | Contexts per query |
ctx_deadline_ms | 5000 (at most 60000) | Context query deadline |
ctx_member_timeout_ms | 4000 | Time per member |
ctx_max_parallel | 8 (at most 16) | Members queried at once |
ctx_offline | false | Start in offline mode |
ctx_catalog_db | _barrel_catalog | Database holding the context cards |
ctx_dir | <docdb data_dir>/_ctx | Slices and imports |
ctx_credentials | #{} | Credentials for remote contexts |
barrel_embed
| Key | Default | Meaning |
|---|
managed_venv | true | Create a Python venv and install provider packages on first use; false uses your own python |
venv_dir | <priv>/.venv | Where the managed venv lives |
barrel_crypto
| Key | Default | Meaning |
|---|
encryption_key | none | Master secret when BARREL_ENCRYPTION_KEY is not set: 32 bytes, 64 hex characters or a passphrase |
encryption_salt | barrel_default_salt_v1 | Salt when BARREL_ENCRYPTION_SALT is not set |
barrel_spaces
| Key | Default | Meaning |
|---|
registry_db | _barrel_spaces | The registry database |
embedder | none | Embedder used to reopen record-mode spaces |
janitor_interval | 300000 ms | How often leftovers of expired sessions are removed |
barrel_ngram
| Key | Default | Meaning |
|---|
data_dir | "data/barrel_ngram" | Where indexes live; everything else is per corpus |
barrel_att_s3
| Key | Default | Meaning |
|---|
multipart_gc_interval | 1 hour, in ms; 0 off | Sweep of abandoned multipart uploads |
multipart_gc_max_age | 24 hours, in seconds | Age after which an upload is abandoned |
barrel_rerank
| Key | Default | Meaning |
|---|
venv_path | undefined, which means priv/.venv of the app | Where the virtualenv lives. Set it after application:load/1 and before the app starts. |
barrel_vectordb
Its .app.src declares default_dimensions, default_embedder, hnsw_m, hnsw_ef_construction, hnsw_ef_search and embed_cache_size, but none is read. Set these per store in vectordb.