Database tools
Engine parameters
Tested with:Databasezy API v1 · zb CLI · ZB-572 (written; live check pending)
Engine parameters are the server settings you may change on an instance: work_mem on PostgreSQL, sql_mode on
MySQL, maxmemory-policy on Valkey, and so on. Open the instance’s Parameters page, or use the API or CLI below.
Each engine has a reviewed allow-list. Every value is checked
against it before it reaches your database: its name, its type, its range on your instance’s size, and whether
your plan may set it.
Settings the platform owns are never on a list. These include listening addresses, TLS, authentication,
preloaded libraries, WAL and binlog archiving, replication, durability switches, data paths, Valkey’s
requirepass, protected-mode and maxmemory, and MySQL’s local_infile and secure_file_priv.
With the CLI
Section titled “With the CLI”zb instances params get inst_01jb...zb instances params set inst_01jb... work_mem=16384 statement_timeout=30000zb instances params set inst_01jb... --reset statement_timeoutset keeps every parameter you do not name. It sends the revision it read, so if someone else changed the
parameters in the meantime, the API answers 409 and nothing is overwritten.
With the API
Section titled “With the API”PUT takes the complete set: a parameter you leave out returns to the platform default.
zb api GET /v1/orgs/{org}/instances/inst_01jb.../parameterszb api PUT /v1/orgs/{org}/instances/inst_01jb.../parameters -d '{ "parameters": { "work_mem": 16384, "statement_timeout": 30000, "timezone": "Europe/Berlin" }, "revision": 3}'- Numbers and booleans are sent as JSON numbers and booleans. Enum, set (
sql_mode) and flags (notify-keyspace-events) values are strings. A number is read in the parameter’sunit:work_mem16384 is 16384 kB. GETlists every parameter of the engine. For each one it gives its type,minandmaxon your size,enumvalues,requires_restart,security, theplansthat may set it, whether your org may set it on this instance (allowed; when it may not,messagesays why: the plan, the size or the engine version), the value you asked for and the value the database runs with (applied_value).revisionis optional. When you send it and the stored revision differs, the request is refused with 409.- The answer is
202 Accepted. Each parameter then moves through these states:pending: the cell has not applied the change yet.restart_pending: the change needs a database restart that has not finished.applied: the database runs with the value.refused: the cell does not render the value (messagesays why).default: nothing is set and nothing needs to be applied.
| Request | Answer |
|---|---|
| A name not on the engine’s list, a value of the wrong type, out of range for the size, more than 64 parameters, more than 8 KiB | 422, with the field parameters.<name> (or parameters) |
| A parameter your plan may not set | 422 (available on the solo, team, enterprise plans) |
A parameter your instance’s size or engine version may not turn on (false stays possible) | 422 (available on size s1 and larger, available on version 3.5; upgrade the instance first) |
No parameters object in the body | 422 (parameters) |
| A body over 1 MiB | 413 |
A body that does not decode (for example parameters is not an object) | 400 |
Without instances.operate in the instance’s team | 403 |
| An instance of another organization | 404 |
An instance being deleted, or a stale revision | 409 |
Each accepted change is written to your audit log as instance.parameters.update. It is also published as the
event instance.parameters_changed.v1 in the same transaction. A change to a parameter marked security is
also recorded as the security event authz.instance_parameters_changed. These parameters control what statement
text reaches the logs, or how much data a crash can lose.
Restarts
Section titled “Restarts”On PostgreSQL and TimescaleDB, most parameters apply with a configuration reload, without a restart.
max_connections restarts the database. On MySQL, MariaDB, MongoDB, Valkey, Redis and DuckDB, every change restarts
the database: the engine operator rolls the pod with the new configuration. Data is kept, but connections drop once.
On InfluxDB, processing-engine restarts the database and plugin-egress applies without a restart. On CouchDB,
nouveau.enable restarts the database.
Parameters per engine
Section titled “Parameters per engine”Use GET .../parameters for the exact limits on your size. Memory parameters are capped at a share of the size’s
memory. max_connections is capped at the size’s connection limit.
PostgreSQL and TimescaleDB: work_mem, maintenance_work_mem, statement_timeout (Solo, Team and
Enterprise), lock_timeout, idle_in_transaction_session_timeout, idle_session_timeout,
log_min_duration_statement (security), log_statement (none, ddl or mod; security), log_lock_waits,
log_temp_files, max_parallel_workers_per_gather (Solo, Team and Enterprise), random_page_cost,
effective_io_concurrency, default_statistics_target, jit, track_io_timing,
default_transaction_isolation, timezone (a list of common zones) and max_connections (restart).
MySQL: sql_mode, long_query_time (security), slow_query_log (security), wait_timeout,
interactive_timeout, max_allowed_packet, transaction_isolation, innodb_lock_wait_timeout,
innodb_print_all_deadlocks, net_read_timeout, net_write_timeout, group_concat_max_len,
max_execution_time (Solo, Team and Enterprise) and max_connections.
MariaDB: the same as MySQL, with max_statement_time (seconds; Solo, Team and Enterprise) in place of
max_execution_time. Its sql_mode list has MariaDB’s modes. It also offers performance_schema (off by default;
restart), which uses extra memory and must be enabled for MariaDB’s Query insights.
Valkey and Redis: maxmemory-policy, notify-keyspace-events, appendfsync (everysec or no; security)
and timeout.
MongoDB: operationProfiling.mode (off or slowOp), operationProfiling.slowOpThresholdMs (security) and
operationProfiling.slowOpSampleRate.
DuckDB: enable_external_access (Solo, Team and Enterprise; security; restart): lets SQL read remote files over
HTTPS (https://, s3://, r2://, gcs://, gs://, hf://) on public addresses, port 443 only. Local files stay
confined to /data/files/. See Reading remote files.
InfluxDB: processing-engine (security; restart): runs your Python plugins on WAL, schedule and HTTP request
triggers, with the pre-installed packages and no pip; plugin-egress (none or https; security): lets plugins
call HTTPS services on public addresses. See Processing Engine.
CouchDB: nouveau.enable (restart; sizes s1 and larger, CouchDB 3.5): runs the Nouveau full-text search server
beside the database, for _nouveau indexes and ranked queries. It takes a quarter of the instance’s CPU and memory.
See Full-text search.
Other engines: no configurable parameters yet. GET returns an empty list, and PUT accepts only an empty
set. These engines are libSQL, FerretDB, TypeDB, Meilisearch, Qdrant, Weaviate, QuestDB and ClickHouse.
On the free tier, PostgreSQL keeps a 60-second statement_timeout and MySQL and MariaDB keep their 60-second
execution limits. A value may lower these limits but not raise them.