Server Configuration

galaxdb-server is the standalone server binary. It accepts PostgreSQL wire protocol connections on port 5433 (default) and serves HTTP observability endpoints on port 9090 (default).

CLI Flags

bash

galaxdb-server [OPTIONS]

Options:
  --data-dir PATH        Data directory (default: temp dir)
  --port PORT            Wire protocol port (default: 5433)
  --observe-port PORT    HTTP observability port (default: 9090)
  --sidecar PATH         Path to galaxdb-sidecar binary
  --model MODEL_ID       HuggingFace model ID for embeddings

Flag	Default	Description
--data-dir PATH	temp dir	Directory for database files. Use a persistent path in production.
--port PORT	5433	PostgreSQL wire protocol port.
--observe-port PORT	9090	HTTP port for /health and /metrics.
--sidecar PATH	(none)	Path to galaxdb-sidecar binary. Required for embeddings.
--model MODEL_ID	(none)	HuggingFace model ID. Required with --sidecar.

Warning

The default --data-dir is a temporary directory that is deleted when the process exits. Always specify a persistent path in production.

Starting the Server

Without embeddings (SQL + HNSW only)

bash

galaxdb-server --data-dir /var/lib/galaxdb --port 5433 --observe-port 9090

With embeddings (full AI features)

bash

galaxdb-server \
  --data-dir /var/lib/galaxdb \
  --port 5433 \
  --observe-port 9090 \
  --sidecar /usr/local/bin/galaxdb-sidecar \
  --model sentence-transformers/all-MiniLM-L6-v2

Verify startup

bash

# Check health
curl http://localhost:9090/health

# Connect with psql
psql "host=localhost port=5433 dbname=galaxdb sslmode=disable"

# Connect with Python
python3 -c "
import galaxdb
conn = galaxdb.connect('host=localhost port=5433 dbname=galaxdb sslmode=disable')
print(conn)
conn.close()
"

Environment Variables

Variable	Description
GALAXDB_KEY_PROVIDER	Key provider for encryption at rest. See Encryption docs.
GALAXDB_LOG_LEVEL	Log level: trace, debug, info (default), warn, error
GALAXDB_MASTER_KEY	Master key (hex) when using env: key provider

bash

# Set log level
GALAXDB_LOG_LEVEL=debug galaxdb-server --data-dir ./data

# Enable encryption with environment variable key
GALAXDB_KEY_PROVIDER=env:GALAXDB_MASTER_KEY \
GALAXDB_MASTER_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
galaxdb-server --data-dir ./data

Wire Protocol

GalaxDB implements the PostgreSQL wire protocol (v3). Any PostgreSQL client connects without modification:

bash

# psql
psql "host=localhost port=5433 dbname=galaxdb sslmode=disable"

# Python psycopg2
python3 -c "
import psycopg2
conn = psycopg2.connect(host='localhost', port=5433, dbname='galaxdb', sslmode='disable')
cur = conn.cursor()
cur.execute('SELECT 1')
print(cur.fetchone())
"

# Node.js (pg)
node -e "
const { Pool } = require('pg')
const pool = new Pool({ host: 'localhost', port: 5433, database: 'galaxdb', ssl: false })
pool.query('SELECT 1').then(r => console.log(r.rows))
"

# SQLAlchemy
python3 -c "
from sqlalchemy import create_engine, text
engine = create_engine('postgresql://localhost:5433/galaxdb')
with engine.connect() as conn:
    print(conn.execute(text('SELECT 1')).fetchone())
"

Training API

Docker