Skip to main content

​
metadb start

Starts the Metadb server to begin processing streaming data and serving client connections.

​
Syntax

metadb start [options]

​
Options

​
-D, --dir
string
required
Path to the Metadb data directory. Must already exist and contain a valid metadb.conf file.
metadb start -D /home/metadb/data
​
-l, --log
string
File path for server log output. If not specified, logs are written to stderr.
metadb start -D data -l metadb.log
​
-p, --port
string
default:"8550"
Port number for the server to listen on.
metadb start -D data -p 8550
​
--debug
boolean
Enable detailed logging for troubleshooting.
metadb start -D data --debug
​
--trace
boolean
Enable extremely detailed logging (requires METADB_DEV=on).
​
--uuopt
boolean
Enable “unnecessary update” optimization to improve performance by skipping redundant updates.
metadb start -D data --uuopt
​
--memlimit
float
default:"1.0"
Approximate memory usage limit in GiB. Helps prevent excessive memory consumption.
metadb start -D data --memlimit 2.5
​
--nokcommit
boolean
Do not commit Kafka offsets (development mode only).
​
--logsource
string
Log source messages to specified file (development mode only).

​
Examples

metadb start -D data

​
Server Behavior

  • The server listens on 127.0.0.1 (localhost) by default
  • Default port is 8550
  • Processes streaming data from configured Kafka sources
  • Accepts client connections via PostgreSQL protocol
The data directory must be specified and must already exist. Run metadb init first if you haven’t created a data directory.

​
metadb stop

Gracefully shuts down the running Metadb server.

​
Syntax

metadb stop [options]

​
Options

​
-D, --dir
string
required
Path to the Metadb data directory of the running server.
metadb stop -D /home/metadb/data
​
-v, --verbose
boolean
Enable verbose output during shutdown.
metadb stop -D data --verbose
​
--trace
boolean
Enable extremely verbose output (requires METADB_DEV=on).

​
Examples

metadb stop -D data

​
Important Notes

Stopping or restarting the server may delay scheduled data updates or cause them to restart. Plan maintenance windows accordingly.

​
Running with systemd

For production deployments, configure Metadb as a systemd service:

​
Service Configuration

Create /etc/systemd/system/metadb.service: 
[Unit]
Description=Metadb
After=network.target remote-fs.target

[Service]
Type=simple
User=metadb
ExecStart=/bin/bash -ce "exec /home/metadb/bin/metadb start -D /home/metadb/data -l /home/metadb/metadb.log"
Restart=on-abort

[Install]
WantedBy=multi-user.target

​
systemd Commands

systemctl enable metadb

​
Connecting to the Server

Once the server is running, connect using psql: 
psql -X -h localhost -d metadb -p 8550
Metadb implements part of the PostgreSQL protocol to allow psql as a client. It is not a full database system.

Build docs developers (and LLMs) love

Get started for freeTalk to us