Quickstart: Run a server

Build kds_server from source, start it with a minimal configuration, connect, and stop it cleanly.

This page takes you from a source checkout to a running server you can query. You build kds_server with CMake, write a two-line configuration file, start the server, connect with the bundled CLI, and stop it. The one setting you must provide is buffer_pool_frames: the server refuses to start without it.

Requirements

CMake 3.20 or later and a C++20 compiler.
OpenSSL 3 or later, for the TLS channel. To build without it, add -DKDS_WITH_TLS=OFF.
GoogleTest, only for the test targets. To skip them, add -DKDS_BUILD_TESTS=OFF.
Python 3, to run the CLI client tools/ckdbs_cli.py. pandas is optional.

1. Build

Run these commands from the root of the source checkout.

Release build (use this to run or measure)

cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release
cmake --build build-release -j"$(nproc)"

scripts/build-release.sh does the same and works from any directory. The binary is build-release/kds_server.

Debug build (development and tests)

scripts/build.sh     # Debug build into ./build
scripts/test.sh      # build, then run the test suite

Debug is the default build type when none is given. Do not take performance numbers from a Debug build: it has reported the wrong direction of a change more than once.

2. Write a minimal configuration

Create a directory for the database and a file named kds.conf in it:

mkdir -p ~/kdbs-data && cd ~/kdbs-data

# kds.conf
buffer_pool_frames = 16384

buffer_pool_frames is the size of the page cache in 8 KiB pages, for the whole instance. 16,384 frames is 128 MiB. It is a hard ceiling: a statement that needs more pages than the pool can free is refused with ResourceExhausted. The value must be at least the 128 system pages plus 256 working frames (plus any pages held by assertions), or the mount is refused naming both numbers.

Every other key has a default. The main ones:

Key	Default	Meaning
`data_file`	`kds.db`	The data file, relative to the working directory. Created if absent.
`port`	`15432`	TCP port. The server listens on `127.0.0.1` only.
`cores`	`1`	Number of scheduler threads, one per CPU.
`durability`	`group`	Default durability class: `strict`, `group` or `relaxed`.
`checkpoint_interval_ms`	`5000`	How often dirty pages are written to the data file.

The source checkout has a commented template, kds.conf.sample, and Server configuration lists every key. An unknown key, a duplicate, a malformed line or an out-of-range value stops the server at startup, naming the file and line.

Note. Without a configuration file the server does not start. With no --config, it stops with:
startup failed: buffer_pool_frames is required and must be nonzero: it is the buffer pool's maximum in 8 KiB frames, and there is no unbounded pool (eviction.md section 6)
scripts/run.sh starts the server without a configuration file, so it fails the same way.

3. Start the server

From the data directory, start the server with the path to your build:

/path/to/ckdbs/build-release/kds_server --config kds.conf

It prints where its data is and the address it listens on, then runs in the foreground:

ckdbs on kds.db: 13 pages, superblock version 23
logging to kdb.log at level INFO
listening on 127.0.0.1:15432

The directory now holds the data file kds.db, the write-ahead log segments in kds.db.wal/, and the log file kdb.log.

Command-line flags override the file:

usage: kds_server [<data_file>] [--config <path>] [--port <n>]
                  [--log-file <name>] [--log-dir <dir>] [--log-level <level>]

If the port is taken, the server stops with server stopped: bind() failed: Address already in use. Choose another port.

4. Connect

In a second terminal, run the CLI from the source checkout. It connects to 127.0.0.1:15432 by default.

python3 tools/ckdbs_cli.py PING
python3 tools/ckdbs_cli.py "CREATE TABLE airlines (id int64, code char(2), name varchar, country varchar)"
python3 tools/ckdbs_cli.py "INSERT INTO airlines VALUES ('KE', 'Korean Air', 'South Korea'), ('OZ', 'Asiana Airlines', 'South Korea')"
python3 tools/ckdbs_cli.py "SELECT * FROM airlines"

PONG
CREATED oid=4000
INSERTED oid=4000 rows=2 first_id=1 last_id=2
id  code             name      country
--  ----  ---------------  -----------
 1    KE       Korean Air  South Korea
 2    OZ  Asiana Airlines  South Korea

Run python3 tools/ckdbs_cli.py with no arguments for an interactive prompt. See Connect with the CLI.

5. Stop the server

Send STOP. The server writes its dirty pages to the data file and exits:

python3 tools/ckdbs_cli.py STOP

The server’s terminal then prints:

stopped; 17 pages persisted

The server closes the connection without a reply, so the CLI reports that the connection was closed (in one-shot mode, as a Python ConnectionError traceback). The server has still stopped cleanly. scripts/stop.sh sends the same command to the default port.

Start the server again with the same command and your table is still there.

Note. Killing the process is a crash, not a stop. Recovery runs at the next start, but some state is always rebuilt rather than kept. See Known gaps.