Home / Documentation / Administration Guide

Administration Guide

Server administration tasks implemented in ShibuDB

Table of Contents

Starting and stopping the server

bash 
# Start server as a background process
shibudb start

# Stop server started via `shibudb start`
shibudb stop

Common flags

bash 
# Override data directory root (defaults to $XDG_DATA_HOME/shibudb or ~/.shibudb)
shibudb start --data-dir /path/to/data

# Set client + management ports (must differ)
shibudb start --port 9090 --management-port 19090

# Bootstrap admin non-interactively on first startup
shibudb start --admin-user admin --admin-password admin

# Set initial connection limit
shibudb start --max-connections 2000

Data directory layout

ShibuDB stores runtime files under a single data directory root.

text 
<data-dir>/
  lib/
    users.json
    management_tokens.json
    connection_limit.json
    <space>/
      space.meta.json
      data.db / wal.db / index.dat                          (key-value)
      vector_data.db / vector_wal.db / vector_index.faiss   (vector)
  log/
    shibudb.log
  run/
    shibudb.pid
  • Note: connection_limit.json persists the last saved connection limit across restarts.
  • Note: each space has its own directory under lib/.

Management API (connection limits + space settings)

The server exposes an HTTP management API on --management-port (default 5444). All endpoints require a bearer token.

text 
Authorization: Bearer <token>

Tokens

Tokens are stored in <data-dir>/lib/management_tokens.json.

bash 
# Create a long-lived token (admin-only)
shibudb manager --username <admin> --password <pass> generate-token

# List stored tokens
shibudb manager --username <admin> --password <pass> list-tokens

# Delete a stored token
shibudb manager --username <admin> --password <pass> delete-token <token_id>

HTTP endpoints

bash 
# Health
curl http://localhost:5444/health -H "Authorization: Bearer <token>"

# Stats
curl http://localhost:5444/stats -H "Authorization: Bearer <token>"

# Get current limit
curl http://localhost:5444/limit -H "Authorization: Bearer <token>"

# Set limit
curl -X PUT http://localhost:5444/limit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"limit": 2000}'

CLI management (recommended)

The shibudb manager command talks to the management API.

bash 
shibudb manager --username <admin> --password <pass> status
shibudb manager --username <admin> --password <pass> stats
shibudb manager --username <admin> --password <pass> limit 2000
shibudb manager --username <admin> --password <pass> increase 500
shibudb manager --username <admin> --password <pass> decrease 200
shibudb manager --username <admin> --password <pass> health

Space settings updates

The management API supports updating space settings:

  • CLI: shibudb manager ... update-space-settings --segment-rollover-bytes N --max-segments-before-merge N <space>
  • HTTP: PUT /spaces/settings

Important behavior:

  • Segment rollover / merge settings apply to Flat and HNSW vector index types.
  • For training-based vector index types (IVF, PQ, …), segment settings do not apply.

Rebuilding a space index

When the server is stopped, you can rebuild a space index from on-disk data.

bash 
shibudb rebuild-index <space_name>

If you use a non-default data directory:

bash 
shibudb rebuild-index --data-dir /path/to/data <space_name>