skilldb (sdb) self hostable PostgreSQL-like Database Engine

A self-contained database engine with REST API, API key auth, rate limiting, admin dashboard, and terminal UI. Runs as a single binary — no dependencies, no runtime, no Docker required.

Build

Windows (MSYS2 / MinGW):

build.bat

Or manually:

set PATH=C:\msys64\ucrt64\bin;%PATH%
g++ -std=c++17 -O2 -o skilldb.exe main.cpp -lws2_32 -lcrypt32

Linux / macOS:

g++ -std=c++17 -O2 -o skilldb main.cpp -lpthread

Requires GCC 9+ or Clang 10+ with C++17 support.

Run

skilldb.exe

Starts the HTTP server on http://0.0.0.0:8080 and opens the terminal UI.

Server-only mode (no interactive UI — ideal for VPS / headless):

./skilldb --server

Environment Variables

Variable	Default	Description
`PORT`	`8080`	HTTP port to listen on
`DATA_DIR`	`data`	Directory for `data.json` and `users.json`

# Example
PORT=3000 DATA_DIR=/var/lib/skilldb ./skilldb --server

Terminal UI Menu

Option	Action
1	Create a new database
2	Create user + generate API key & URL
3	List all users and their keys
4	Revoke an API key
5	Show all databases
6	Show tables in current database
7	Interactive SQL shell
8	Server status & endpoints
9	Export database to `.sql` file

SQL Shell (Option 7)

CREATE DATABASE myapp
USE myapp
CREATE TABLE users (name TEXT, email TEXT, age INT)
INSERT INTO users (name, email, age) VALUES ('Alice', 'alice@example.com', 30)
SELECT * FROM users
SELECT name, email FROM users WHERE age > 25
UPDATE users SET age = 31 WHERE name = 'Alice'
DELETE FROM users WHERE name = 'Alice'
DESCRIBE users
SHOW TABLES
SHOW DATABASES

REST API

Authentication

Pass your API key via header or query param:

X-API-Key: sdb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or
?apiKey=sdb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

Health check

GET /health

Register a new user

POST /register
Content-Type: application/json

{"username": "alice", "dbName": "myapp"}

Returns apiKey, dbName, connectionUrl.

Validate an API key

GET /validate
X-API-Key: YOUR_KEY

Connection info

GET /db/:dbname?apiKey=YOUR_KEY

Execute SQL

POST /db/:dbname/query
Content-Type: application/json
X-API-Key: YOUR_KEY

{"sql": "SELECT * FROM users"}

List tables

GET /db/:dbname/tables
X-API-Key: YOUR_KEY

Describe a table

GET /db/:dbname/tables/:table
X-API-Key: YOUR_KEY

Get all rows

GET /db/:dbname/tables/:table/rows
X-API-Key: YOUR_KEY

Export database as SQL

GET /db/:dbname/export/sql
X-API-Key: YOUR_KEY

Change the default credentials in server.hpp before deploying:

static const std::string ADMIN_EMAIL    = "your@email.com";
static const std::string ADMIN_PASSWORD = "your_password";
static const std::string ADMIN_TOKEN    = "your_secret_token";

Connect from Your Project

JavaScript / Node.js

const API_KEY = "sdb_your_key_here";
const BASE    = "http://localhost:8080/db/myapp";

async function query(sql) {
  const res = await fetch(`${BASE}/query`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": API_KEY },
    body: JSON.stringify({ sql })
  });
  return res.json();
}

const rows = await query("SELECT * FROM users");
console.log(rows);

Python

import requests

API_KEY = "sdb_your_key_here"
BASE    = "http://localhost:8080/db/myapp"

def query(sql):
    r = requests.post(f"{BASE}/query",
        json={"sql": sql},
        headers={"X-API-Key": API_KEY})
    return r.json()

rows = query("SELECT * FROM users")
print(rows)

curl

curl -X POST http://localhost:8080/db/myapp/query \
     -H "Content-Type: application/json" \
     -H "X-API-Key: sdb_your_key_here" \
     -d '{"sql":"SELECT * FROM users"}'

Deploy on Custom Hardware

This covers bare-metal servers, Raspberry Pi, old PCs repurposed as servers, or any Linux box you physically control.

1. Cross-compile on Windows, deploy to Linux

If you build on Windows but your server runs Linux (e.g. a Raspberry Pi):

# On a Linux machine or WSL:
g++ -std=c++17 -O2 -o skilldb main.cpp -lpthread
scp skilldb user@192.168.1.100:/opt/skilldb/

2. Build directly on the hardware

# SSH into the machine
ssh user@192.168.1.100

# Install GCC if not present
sudo apt update && sudo apt install -y g++

# Clone or copy source
mkdir -p /opt/skilldb && cd /opt/skilldb
# (copy your source files here)

# Build
g++ -std=c++17 -O2 -o skilldb main.cpp -lpthread

# Create data directory
mkdir -p /opt/skilldb/data

3. Run

cd /opt/skilldb
PORT=8080 DATA_DIR=/opt/skilldb/data ./skilldb --server

4. Firewall

Open the port you're using:

# ufw
sudo ufw allow 8080/tcp

# iptables
sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT

For production, expose only port 80/443 via a reverse proxy (see Nginx section) and keep skilldb on a private port.

5. Local network access

Once running, any device on the same network can access it:

http://192.168.1.100:8080/health

Deploy on a VPS

Works with any provider: DigitalOcean, Linode/Akamai, Vultr, Hetzner, AWS EC2, etc.

1. Provision a server

Minimum specs:

1 vCPU, 512 MB RAM (it runs fine on the cheapest tier)
Ubuntu 22.04 LTS (or any modern Linux)

2. SSH in and build

ssh root@YOUR_SERVER_IP

# Install build tools
apt update && apt install -y g++ build-essential

# Set up app directory
mkdir -p /opt/skilldb/data
cd /opt/skilldb

# Upload your source files (from local machine):
# scp -r ./dbf/* root@YOUR_SERVER_IP:/opt/skilldb/

# Build
g++ -std=c++17 -O2 -o skilldb main.cpp -lpthread

3. Run manually (test)

PORT=8080 DATA_DIR=/opt/skilldb/data ./skilldb --server

Test from your local machine:

curl http://YOUR_SERVER_IP:8080/health

4. Firewall (UFW)

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

skilldb itself runs on an internal port (e.g. 8080) and is exposed via Nginx.

Running as a System Service

Set up skilldb to auto-start and auto-restart on crash using systemd.

Create the service file

sudo nano /etc/systemd/system/skilldb.service

[Unit]
Description=skilldb Database Engine
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/skilldb
ExecStart=/opt/skilldb/skilldb --server
Environment=PORT=8080
Environment=DATA_DIR=/opt/skilldb/data
Restart=on-failure
RestartSec=5
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=skilldb

[Install]
WantedBy=multi-user.target

Enable and start

sudo systemctl daemon-reload
sudo systemctl enable skilldb
sudo systemctl start skilldb
sudo systemctl status skilldb

View logs

journalctl -u skilldb -f

Reverse Proxy with Nginx

Proxying through Nginx lets you run skilldb on a private port while exposing it publicly on port 80/443, and handles TLS termination.

Install Nginx

sudo apt install -y nginx

Configure

sudo nano /etc/nginx/sites-available/skilldb

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 30s;
    }
}

sudo ln -s /etc/nginx/sites-available/skilldb/etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Now skilldb is accessible at http://yourdomain.com.

TLS / HTTPS

Use Certbot for a free Let's Encrypt certificate.

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

Certbot automatically updates your Nginx config to serve HTTPS and redirect HTTP → HTTPS.

After this, your connection URLs look like:

https://yourdomain.com/db/myapp?apiKey=sdb_xxx

Update your API key connection URLs by changing the host in auth.hpp or by re-creating users pointing to the new domain. The setEndpoint call in DBServer controls the host used in generated connectionUrl values:

// server.hpp — constructor calls:
auth.setEndpoint("yourdomain.com", 443);

Or you can set the host dynamically via the HOST environment variable — add this to main.cpp:

const char* hostEnv = std::getenv("HOST");
server.auth.setEndpoint(hostEnv ? hostEnv : "localhost", SERVER_PORT);

Data Persistence

File	Contents
`data/data.json`	All databases and tables (auto-saved on every write)
`data/users.json`	API keys and user credentials (auto-saved)

Both files are plain JSON — human-readable and easy to back up.

Backup

# Simple cron backup (daily at 2am)
crontab -e
# Add:
0 2 * * * cp -r /opt/skilldb/data /opt/skilldb/backups/$(date +\%F)

Restore

Copy data.json and users.json back to DATA_DIR and restart the service.

Export to standard SQL (for migration)

Use menu option 9 in the UI, or via the API:

curl http://localhost:8080/db/myapp/export/sql \
     -H "X-API-Key: sdb_your_key" | jq -r '.sql' > myapp_export.sql

Import into PostgreSQL / MySQL:

psql -U user -d dbname -f myapp_export.sql
mysql -u user -p dbname < myapp_export.sql

Supported SQL

Statement	Syntax
CREATE DATABASE	`CREATE DATABASE name`
USE	`USE name`
CREATE TABLE	`CREATE TABLE t (col TYPE, ...)`
DROP TABLE	`DROP TABLE t`
INSERT	`INSERT INTO t (col1, col2) VALUES (v1, v2)`
SELECT	`SELECT */cols FROM t [WHERE col op val]`
UPDATE	`UPDATE t SET col=val [WHERE col op val]`
DELETE	`DELETE FROM t [WHERE col op val]`
DESCRIBE	`DESCRIBE t`
SHOW TABLES	`SHOW TABLES`
SHOW DATABASES	`SHOW DATABASES`

WHERE operators: =, !=, >, <, >=, <=, AND

Column types: TEXT, INT, FLOAT

An id INT primary key column is automatically added to every table.

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
web-ui		web-ui
.dockerignore		.dockerignore
CMakeLists.txt		CMakeLists.txt
Dockerfile		Dockerfile
README.md		README.md
auth.hpp		auth.hpp
build.bat		build.bat
data.json		data.json
dbforge.exe		dbforge.exe
docker-compose.yml		docker-compose.yml
engine.hpp		engine.hpp
fgfgf_export.sql		fgfgf_export.sql
fly.toml		fly.toml
httplib.h		httplib.h
json.hpp		json.hpp
main.cpp		main.cpp
server.hpp		server.hpp
ui.hpp		ui.hpp
users.json		users.json

Folders and files

Latest commit

History

Repository files navigation

skilldb (sdb) self hostable PostgreSQL-like Database Engine

Table of Contents

Build

Run

Environment Variables

Terminal UI Menu

SQL Shell (Option 7)

REST API

Authentication

Endpoints

Health check

Register a new user

Validate an API key

Connection info

Execute SQL

List tables

Describe a table

Get all rows

Export database as SQL

Connect from Your Project

JavaScript / Node.js

Python

curl

Deploy on Custom Hardware

1. Cross-compile on Windows, deploy to Linux

2. Build directly on the hardware

3. Run

4. Firewall

5. Local network access

Deploy on a VPS

1. Provision a server

2. SSH in and build

3. Run manually (test)

4. Firewall (UFW)

Running as a System Service

Create the service file

Enable and start

View logs

Reverse Proxy with Nginx

Install Nginx

Configure

TLS / HTTPS

Data Persistence

Backup

Restore

Export to standard SQL (for migration)

Supported SQL

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages