Skip to main content
This guide covers system requirements, building from source, and initial configuration for Metadb.

​
System Requirements

​
Hardware Requirements

Architecture

x86-64 (AMD64)

Memory

Minimum 1 GB RAM

​
Software Requirements

1

Operating System

Linux is required for running Metadb.
2

Database System

PostgreSQL 15 or later must be installed and running.
Metadb uses PostgreSQL as its backend database system.
3

Build Dependencies

To build Metadb from source, install these tools:
  • GCC C Compiler - Version 9 or later
  • Ragel - Version 6
  • Go - Version 1.21 or later
On Ubuntu/Debian:
sudo apt-get update
sudo apt-get install gcc ragel golang-go
On RHEL/CentOS:
sudo yum install gcc ragel golang

​
PostgreSQL Configuration

For optimal performance, configure PostgreSQL with these recommended settings in postgresql.conf: 
autovacuum_analyze_scale_factor = 0.01
autovacuum_max_workers = 1
autovacuum_vacuum_cost_delay = 0
autovacuum_vacuum_insert_scale_factor = 0.01
autovacuum_vacuum_scale_factor = 0.01
checkpoint_timeout = 3600
cpu_tuple_cost = 0.03
default_statistics_target = 1000
effective_io_concurrency = 1
idle_in_transaction_session_timeout = 60000
idle_session_timeout = 86400000
maintenance_work_mem = 1000000
max_wal_size = 10240
shared_buffers = 1250000
statement_timeout = 3600000
work_mem = 350000
These settings are optimized for Metadb workloads. Test them in your environment before deploying to production.

​
Building from Source

1

Create metadb user

It’s recommended to create a dedicated system user for running Metadb:
sudo useradd -m -s /bin/bash metadb
sudo su - metadb
2

Set Go environment

Configure the Go workspace path:
export GOPATH=$HOME/go
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
3

Clone repository

Download the Metadb source code:
git clone https://github.com/metadb-project/metadb.git -b v1.4.0
cd metadb
Replace v1.4.0 with the desired version tag. Check the releases page for the latest version.
4

Build the executable

Run the build script to compile Metadb:
./build
The build process creates a bin/ directory containing the metadb executable.
5

Verify installation

Test the executable:
./bin/metadb version
You should see output like:
metadb version 1.4.0

​
Configuration

​
Initialize Data Directory

Metadb uses a data directory for local storage and configuration: 
./bin/metadb init -D data
This command creates:
  • The data/ directory
  • A metadb.conf configuration file inside the data directory

​
Configure Database Connection

The metadb.conf file contains database connection parameters: 
[main]
host = a.b.c
port = 5432
database = metadb
superuser = postgres
superuser_password = your_superuser_password
systemuser = mdbadmin
systemuser_password = your_systemuser_password
sslmode = require
The database name must be metadb or begin with metadb_, otherwise Metadb will log a warning message.

​
Database Preparation

Before starting Metadb, create the required database and users in PostgreSQL: 
-- Create the database
CREATE DATABASE metadb;

-- Create the system user
CREATE USER mdbadmin WITH PASSWORD 'your_systemuser_password';

-- Grant ownership
ALTER DATABASE metadb OWNER TO mdbadmin;
Metadb requires both a superuser (for administrative operations) and a systemuser (for data operations).

​
Starting the Server

​
Basic Startup

Start the Metadb server with default settings: 
nohup ./bin/metadb start -D data -l metadb.log &
Command breakdown:
  • -D data - Specifies the data directory
  • -l metadb.log - Logs output to metadb.log
  • nohup ... & - Runs in background, continues after logout

​
Advanced Options

# Run on a different port (default: 8550)
nohup ./bin/metadb start -D data -l metadb.log --port 9000 &

​
Stopping the Server

To gracefully shut down the server: 
./bin/metadb stop -D data
Stopping or restarting the server may delay scheduled data updates or cause them to restart.

​
Running as a System Service

For production deployments, configure Metadb to run as a systemd service.
1

Create service file

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
2

Enable and start service

sudo systemctl enable metadb
sudo systemctl start metadb
3

Verify service status

sudo systemctl status metadb

​
Service Management Commands

# Start service
sudo systemctl start metadb

# Stop service
sudo systemctl stop metadb

# Restart service
sudo systemctl restart metadb

# View logs
sudo journalctl -u metadb -f

​
Connecting to Metadb

Use the PostgreSQL client psql to connect: 
psql -X -h localhost -d metadb -p 8550
Metadb implements part of the PostgreSQL wire protocol, allowing psql to be used as a client. However, it is not a full database system.

​
Test the Connection

Once connected, verify the installation: 
-- Check Metadb version
SELECT mdbversion();

-- View system log
SELECT * FROM mdblog();

-- List available commands
-- (Type \? in psql for help)

​
Upgrading Metadb

To upgrade from a previous version:
1

Stop the server

./bin/metadb stop -D data
2

Build new version

cd metadb
git fetch
git checkout v1.5.0  # or desired version
./build
3

Run upgrade process

./bin/metadb upgrade -D data
If no changes are needed, you’ll see:
metadb: "data" is up to date
4

Restart the server

nohup ./bin/metadb start -D data -l metadb.log &
The upgrade process may take significant time for large databases. The database generally remains available to users during this period.

​
Backup Strategy

It is essential to make regular backups and test them.

​
What to Back Up

PostgreSQL Database

Most persistent data are stored here. Back up frequently using pg_dump or similar tools.

Configuration File

Back up metadb.conf from your data directory.

​
Database Backup Example

# Full database backup
pg_dump -h localhost -p 5432 -U postgres metadb > metadb_backup.sql

# Compressed backup
pg_dump -h localhost -p 5432 -U postgres metadb | gzip > metadb_backup.sql.gz

# Restore from backup
psql -h localhost -p 5432 -U postgres metadb < metadb_backup.sql

​
Troubleshooting

​
Check Server Logs

# View recent log entries
tail -f metadb.log

# Query log from within Metadb
psql -h localhost -p 8550 -d metadb -c "SELECT * FROM mdblog();"

​
Common Issues

  • Verify the server is running: ps aux | grep metadb
  • Check the port is correct (default: 8550)
  • Review metadb.log for startup errors
  • Verify PostgreSQL is running
  • Check metadb.conf connection parameters
  • Ensure database and users exist
  • Test PostgreSQL connection directly with psql
  • Verify all dependencies are installed (GCC, Ragel, Go)
  • Check Go version: go version (must be 1.21+)
  • Ensure GOPATH is set correctly

​
Next Steps

Quickstart

Set up your first data source and run queries

Kafka Data Sources

Configure Kafka and streaming data sources

User Management

Create users and manage permissions

Configuration

Advanced server management and tuning

Build docs developers (and LLMs) love

Get started for freeTalk to us