Settings page (data folder, old log, capacity, program files and users)

Where the server keeps its data, how to point it at another folder, and who may log in - all from the console.

• Category: Web console
• Keywords: settings, settings page, data folder, move data, change data folder, kdb.conf, config file, --config, restart, restart server, add user, change password, remove user, grants, roles, free space, disk space, wal_archive, wal_archive_mb, KDB_WAL_ARCHIVE_MB, old log, cache_mb, KDB_CACHE_MB, result cache size, program files, web_dir, help_dir, skill_dir, KDB_WEB_DIR, KDB_HELP_DIR, KDB_SKILL_DIR, command line, Docker, KDB_DATA_DIR, capacity, http_threads, max_connections, lock_timeout_ms, idle_in_transaction_timeout_ms, rate_limit_ip, rate_limit_user, timer_workers, http_functions, KDB_HTTP_FUNCTIONS
• See also: Web console, Monitor panel (memory, processor, caches), View data page (browse and edit rows), Users and roles, kdb user, kdb serve, Databases and the data folder, Keeping kdb serve safe, Install packages and the Claude skill, Health, info, check and backup over HTTP

The Settings page of the web console has these parts: Storage (where the databases live), Old log kept per database (the wal_archive size), Result cache (cache_mb), Backups, Calls from SQL (http_functions), Capacity and waits (HTTP threads, PostgreSQL connections, the lock timeout, the drain time), Program files (the folders of the console, the help and the Claude skill) and Users (who may log in). Only a user whose own ROLE is admin may open it; everybody else sees a line saying so.

Storage

The top of the page shows the data folder in use, and a badge saying where that choice came from. Under it: how many databases are in it, how much they use, and how much room is left on that disk.

Where the data folder comes from, strongest first:

A flag always wins. When the server was started with --data-dir, the page says so in a yellow banner: a folder saved here will only be used once the server is started without that flag. This is worth reading before pressing anything - it is the difference between a setting that works and one that quietly does nothing.

How this server was started folds open to show the settings file (config_path) and the whole command line (command_line), as GET /api/settings gives them.

In Docker the image passes the data folder as the environment variable KDB_DATA_DIR=/data, not as --data-dir, on purpose: a flag would always win, and this page could then never change the folder. The image also keeps kdb.conf in the volume (--config /data/kdb.conf), so a setting saved here survives a new image and a new container. A folder you choose here must be under a mounted volume too; anywhere else is inside the container and is lost with it (Docker).

Changing the folder

Type a folder and press Save. Before anything is written, the server:

1. makes the folder if it is not there,
2. writes a small file in it and removes it again, to be sure it can write there,
3. refuses a folder that is itself one database (it holds a _manifest.a) - the data folder is the one above those, the one with a folder per database.

Only then is the folder written to kdb.conf. A folder that fails any of those checks is refused with the reason, and the file is not touched.

{"data_dir":"E:/kdb-data"}

Nothing is copied. The databases in the old folder stay exactly where they are; the server simply looks somewhere else from the next start. To take them along:

1. Save the new folder here.
2. Stop the server.
3. Move the database folders yourself.
4. Start it again.

Restart

Restart the server closes every database cleanly and starts again in the same process. No service manager, Docker restart policy or supervisor is needed, and the server keeps the same port, so the console reconnects by itself after a few seconds.

• Statements that are running are stopped and open transactions are rolled back, exactly as at a normal shutdown.
• The server prints restarting..., then databases closed cleanly (N ms), then its usual banner.
• Restarting is written to the audit log.

If the saved folder cannot be used when the server starts again - an unplugged disk, a renamed share - the server does not refuse to boot. It prints a warning and starts on the usual folder instead, so there is always a console to fix the setting in:

warning: the data folder saved in 'C:/kdb/kdb.conf' cannot be used: cannot make the folder 'Z:/gone'
         starting with the usual folder instead. Fix it on the Settings page.

When it cannot be changed here

The page shows the folder without a Save button when the settings file cannot be written - a read-only program folder, for instance, as in some container images. It then says why, and the folder is set with --data-dir or KDB_DATA_DIR as before. --config <file> puts the settings file somewhere writable:

kdb serve --config /var/lib/kdb/kdb.conf

A server started on one database folder (kdb serve D:\kdb\market) has no data folder to change, so Storage is read-only there too.

Old log kept per database

Each database keeps old log files in its wal_archive folder. They are only used to repair a damaged file and by backups; the data does not need them. This part of the page sets how much each database keeps: a size in MB, or Off.

• Save works at once, with no restart. A smaller size removes the oldest files of every open database now.
• Off keeps no old log. A damaged file can then only be repaired from a backup.
• A database with its own setting keeps it: ALTER DATABASE ... SET WAL_ARCHIVE, or Old log in the console's Databases panel. There you can also pick Server default again.

{"data_dir":"E:/kdb-data","wal_archive_mb":100}

Result cache

The result cache keeps the results of repeated SELECTs in memory. This part of the page sets its size for all databases together, in MB; 0 turns it off.

• Save works at once, with no restart. A smaller size drops the oldest results now.
• One result may use a quarter of the space, a pinned one three quarters.
• A database with a space of its own keeps it: ALTER DATABASE ... SET RESULT_CACHE.

Backups

The backup folder, the schedule, how many backups are kept, and the command that copies each backup off the server. Each line says where its value came from: a flag, this page (kdb.conf), the environment or the default (where the settings come from).

• Save writes the schedule and the two counts to kdb.conf. They are used from the next start: use Restart under Storage.
• The folder and the copy command are shown, not edited. A command runs programs on the server, so it is set in kdb.conf by hand, with --backup-command or KDB_BACKUP_COMMAND.
• Keep enough old log (above) to cover the time between two backups, or a restore to a moment in between is not possible (the window).

{"data_dir":"/data","backup_schedule":"daily 02:00","backup_keep_daily":14,"backup_command":"aws s3 cp --recursive {dir} s3://my-bucket/kdb/{database}/{name}"}

Calls from SQL

Which hosts http_get and http_post may call, and how long one call may take.

• Type the hosts separated by commas (api.example.com, 10.0.0.5:8080), or off.
• Save writes http_functions and http_timeout_ms to kdb.conf. They apply at once, no restart.
• Set by says where the list came from: this page (kdb.conf), KDB_HTTP_FUNCTIONS, or the default (off).

Capacity and waits

What the server was started with, and where each value came from. It is read-only: the server reads these when it starts, so a change needs a restart.

To change one, write its key into kdb.conf by hand and press Restart under Storage; a flag or an environment variable changes only when the server is started again. Every option of the server, with its flag, variable and key, is in every option.

{"data_dir":"E:/kdb-data","http_threads":32,"max_connections":300,"lock_timeout_ms":20000}

Program files

The web console, the help pages and the Claude skill are folders of plain files next to the kdb program, not part of it. This part shows which folder the server uses for each, and what chose it. It is read-only.

• After each folder the page says where it came from: from kdb.conf, from KDB_WEB_DIR, next to the program, in share/kdb beside the program folder or from the source checkout. not found means none of the places had the files.
• To use other folders, write them into kdb.conf by hand, or set the environment variables, and restart the server. More: where kdb finds the console, the help and the skill.

{"data_dir":"E:/kdb-data","web_dir":"E:/kdb/web","help_dir":"E:/kdb/help","skill_dir":"E:/kdb/skill"}

Users

The same users as CREATE USER and kdb user - this page just sends that SQL for you.

On a server with no users yet, the page says so and offers Add the first user. That first user must have ROLE admin, so the role box is fixed. As soon as that user exists, every request needs a login - the console notices at once and shows its login form, so have the password ready.

The rules the server enforces, which the page simply reports:

• A password must be at least 12 characters and must not be the user name.
• Bob and bob are the same user.
• The last user with ROLE admin cannot be removed or made weaker while other users exist.
• A new password ends that user's open logins at once.

Roles, and what each one may do, are in users and roles. Keeping a server reachable from outside safe is in server security.