Skip to content

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.

shell
zb instances params get inst_01jb...
zb instances params set inst_01jb... work_mem=16384 statement_timeout=30000
zb instances params set inst_01jb... --reset statement_timeout

set 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.

PUT takes the complete set: a parameter you leave out returns to the platform default.

shell
zb api GET /v1/orgs/{org}/instances/inst_01jb.../parameters
zb 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’s unit: work_mem 16384 is 16384 kB.
  • GET lists every parameter of the engine. For each one it gives its type, min and max on your size, enum values, requires_restart, security, the plans that may set it, whether your org may set it on this instance (allowed; when it may not, message says why: the plan, the size or the engine version), the value you asked for and the value the database runs with (applied_value).
  • revision is 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 (message says why).
    • default: nothing is set and nothing needs to be applied.
RequestAnswer
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 KiB422, with the field parameters.<name> (or parameters)
A parameter your plan may not set422 (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 body422 (parameters)
A body over 1 MiB413
A body that does not decode (for example parameters is not an object)400
Without instances.operate in the instance’s team403
An instance of another organization404
An instance being deleted, or a stale revision409

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.

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.

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.