Limits and defaults

The sizes and limits an operator needs to know: key and value sizes, queue lengths, time limits, default ports and default paths. By default LuraDB listens on port 3000 for HTTP, 3443 for HTTPS and 3100 for MCP.

A limit that a setting controls is listed with its setting and its default; the setting’s entry in the configuration reference says more. A limit marked fixed is part of the server and cannot be changed. Several fixed limits were settings until 0.5.1 and are listed with the setting they used to be; a luradb.toml that still sets one starts normally and the value is ignored.

Ports and addresses

Listener	Default	Settings
HTTP	Port 3000 on 127.0.0.1.	server.port, server.bind_address, server.http_enabled
HTTPS	Port 3443, off.	server.tls_enabled, server.tls_port
MCP	Port 3100 on the bind address, off.	mcp.enabled, mcp.port
Unix socket	Off. The packaged file sets /run/luradb/luradb.sock. The socket mode is fixed at 0660 (was server.unix_socket_moderemoved).	server.unix_socket_path
Shared-memory registration socket	/run/luradb/{instance_id}.sock with the instance id 0, while shared memory is off.	shm.registration_socket_path, shm.instance_id

All TCP listeners bind to one address. With authentication off, only a loopback address is accepted. The HTTPS port must differ from the HTTP port, and the MCP port from both of them.

Paths

Relative paths resolve against the working directory of the server, which is /var/lib/luradb under the package. Without --config, the server reads ./luradb.toml, else /etc/luradb/luradb.toml, else it runs with the built-in defaults.

What	Built-in default	Packaged file
Configuration	./luradb.toml, then /etc/luradb/luradb.toml	/etc/luradb/luradb.toml
storage.db_path	luradb.db	/var/lib/luradb/luradb.db
storage.wal_path (a directory of segments)	luradb.wal	/var/lib/luradb/luradb.wal
storage.vlog_path	luradb.vlog	/var/lib/luradb/luradb.vlog
storage.sstable_dir	luradb_sstables	/var/lib/luradb/sstables
storage.system_dir	luradb_sys	/var/lib/luradb/luradb_sys
JSON engine: json.wal_path, json.vlog_path, json.sstable_dir	luradb_json.wal, luradb_json.vlog, luradb_json_sstables	the same, relative
Relational engine: rel.wal_path, rel.vlog_path, rel.sstable_dir	luradb_rel.wal, luradb_rel.vlog, luradb_rel_sstables	the same, relative
backup.dir	luradb_backups	the same, relative
log.path	not set: the log goes to standard output	not set: journald
server.tls_cert_path, server.tls_key_path	/etc/luradb/tls/server.crt, /etc/luradb/tls/server.key	the same

Beside each configured data path, the files of data shard k live in a directory shard_<k>/; the write-ahead logs stay at their configured paths. No two data paths may resolve to the same location, symbolic links included.

Request and response sizes

Limit	Value
Request body of most endpoints: a key value, a document, a SQL request, a user or permission call	2 MiB, fixed. A larger body answers 413 with Failed to buffer the request body: length limit exceeded. A body of exactly 2 MiB is accepted.
Body of a JSON bulk load	json.bulk_body_limit_bytes, 64 MiB. The whole body is held in memory.
Body of a table import	rel.import_body_limit_bytes, 64 MiB.
Body of a backup upload	Not limited by the 2 MiB rule; the archive is streamed to disk. An archive of 12 MB was accepted.
Response of a relational query	32 MiB, fixed (was rel.max_response_bytesremoved). A larger answer is 413.
One line of a backup archive	64 MiB, fixed.
Largest single field the recovery of the write-ahead log reads	96 MiB, fixed. The size limits of the engines must not exceed it, or the start is refused.
Log API	100 lines by default, 1000 at most; the server reads at most 4 MiB of a file per call.
MCP	A request of up to 4 MiB; an answer of up to 1 MiB.

Keys, names and values

Limit	Value
Key-value key	domains.max_user_key_length, 256 bytes. The engine stores it with a prefix of 19 bytes and has its own limit, lsm.max_key_length (256), which the two entries explain together.
Key-value value	lsm.max_value_size is 512 KiB by default. In v0.5.1 a single PUT is limited by the 2 MiB request body instead, see the entry.
JSON document key	At most 256 bytes, fixed (was json.max_document_key_lengthremoved), and json.lsm.max_key_length leaves 21 bytes less: 235 with its default.
JSON document	json.lsm.max_value_size, 512 KiB.
JSON index field path	128 characters, fixed.
Relational row	rel.max_row_size, 512 KiB.
Relational primary-key and index values	rel.lsm.max_key_length, 256 bytes.
Relational text, KVREF and JSONREF value	64 KiB, fixed (was rel.max_text_lenremoved).
Domain name	50 characters of a-z, A-Z, 0-9, _ and -. Fixed for JSON and relational domains; for key-value domains it is domains.max_name_length, 50.
User name, backup schedule name	1 to 50 characters of the same set.
Table, column, view and index name	1 to 50 characters.
Value-log threshold	lsm.vlog_inline_threshold: from 1024 bytes a value goes to the value log.

Listings, searches and statements

Limit	Value
Key listing (GET …/keys)	limit 1000 by default, 10000 at most; a larger value is reduced to 10000.
JSON search	limit 50 by default, 1000 at most; a larger value is reduced to 1000.
Bulk delete by prefix	domains.max_bulk_delete_keys, 10000 keys. More answers 413 and nothing is deleted.
Rows of a relational query	1000 without a LIMIT (fixed, was rel.default_limitremoved); no more than rel.max_limit (10000) with one.
Rows an ORDER BY sorts or an unindexed join scans	rel.max_sort_rows, 100000.
SQL statement	64 KiB, fixed (was rel.max_statement_lenremoved). A longer one answers 400: statement length 65549 exceeds maximum of 65536 bytes.
Columns per table	128, fixed (was rel.max_columnsremoved). The 129th answers 400: limit exceeded: max_columns (max 128).
Indexes per table	16, fixed (was rel.max_indexes_per_tableremoved).
Tables per relational domain	rel.max_tables_per_domain, 256.
LEFT JOIN stages plus expand columns in one statement	8, fixed (was rel.max_join_depthremoved).
Nesting of views	3 levels, fixed.
Nesting of an expression	100 levels, fixed.
Documents per atomic step of a JSON bulk load	100, fixed (was json.bulk_batch_sizeremoved).
Documents per step of a re-index	500, with a pause of 10 ms between steps, fixed (was json.reindex_batch_sizeremoved).

Queues, concurrency and budgets

Limit	Value
Writes waiting for the storage thread	storage.wal_queue_capacity, 1024; 1 to 65536.
Requests one data shard takes at once	multicore.shard_queue_capacity, 1024. The next one answers 503.
Read requests waiting for a reader thread	multicore.reader_queue_capacity, 4096.
Requests per connection	One at a time, HTTP/2 included. Open several connections for parallelism.
Open files of the service	65536 (LimitNOFILE of the unit).
Reads and writes per second of a key-value or relational domain	rate_limit.default_read_iops 1000, rate_limit.default_write_iops 500. More answers 429.
Backup or restore jobs	One at a time.
Restore statuses kept	The last 20 finished ones, in memory.
Errors listed in one restore status	100.
Events buffered per consumer of the event stream	events.channel_capacity, 256; the replay ring holds events.replay_buffer_size, 1024.
Change events buffered per watch stream of a key-value domain	lsm.wal_event_channel_capacity, 256; the replay ring holds lsm.watch_replay_buffer_size, 1024.
Size of a write-ahead log segment	64 MiB, fixed. The cap on all segments of an engine is storage.wal_max_size, 256 MiB.
Metrics window	60 seconds, fixed.

Time limits

Limit	Value
A data shard that does not answer a health ping	timeout after 250 ms, and /health answers 503.
Retry-After	1 second for 429 and a full queue; 5 seconds for 507.
Disk and memory watch	Once a second. A write is accepted again after two readings in a row.
TLS handshake	10 seconds, then the connection is dropped.
Stopping	Open connections get 5 seconds to finish.
Segment of the write-ahead log with records in it	Closed after 5 minutes, even if it is not full.
Backup scheduler	Looks at the clock at every full minute; cron time is UTC; a schedule must fire within 4 years.
Wait for the purge of a domain during mode: replace	10 minutes.
Sweep that clears links to a deleted domain	Every 10 seconds, 100 cells per column (was rel.cross_engine_sweep_interval_secsremoved and rel.cross_engine_sweep_batch_sizeremoved).
Cleanup of old log files	Once for every 24 hours of uptime.
MCP sign-in	An authorization code lives 60 seconds, an access token 1 hour, a refresh token 30 days; a client registration that was never used to sign in, 24 hours. Five failed sign-ins from one address within 15 minutes (an IPv6 /64 counts as one address) block further sign-ins from it; ten registrations per address and hour.

Smallest and largest values of settings

Setting	Bounds
storage.wal_max_size	At least 128 MiB.
storage.wal_queue_capacity	1 to 65536.
resources.memory_budget	At least 256 MiB.
resources.disk_free_block	At least 64 MiB on each volume, and block ≤ resume ≤ warn.
Memory thresholds	Warning from 80 %, writes refused from 95 %, accepted again below 90 % of the budget; fixed.
lsm.max_key_length, lsm.max_value_size and their JSON and relational counterparts	At most 96 MiB.
json.lsm.max_value_size	At least 4096 bytes.
shm.data_buffer_size	At least 4096 bytes.
multicore.frontend_workers, multicore.reader_threads, multicore.cpu_offload_threads	0 (automatic) or 1 up to the number of cores.

Related settings server.port · server.tls_port · mcp.port · storage.wal_path · storage.sstable_dir · domains.max_user_key_length · lsm.max_value_size · json.bulk_body_limit_bytes · rel.max_limit · storage.wal_queue_capacity · multicore.shard_queue_capacity · multicore.reader_queue_capacity · rate_limit.default_read_iops ·

rate_limit.default_write_iops