Configuration

Every server flag, client option, compaction setting, cluster configuration, and web panel parameter.

Core Server Flags

Required and essential flags for running the ALOS DB server:

Flag Default Description
--port localhost:6900 TCP listen address (host:port). Use 0.0.0.0:6900 to listen on all interfaces.
--username Required. Authentication username for client connections.
--password Required. Authentication password for client connections.
--db-name alosdb Default database name.
--data-path OS-specific Directory for data files. Defaults to OS app-data location if not set.
--debug false Enable debug logging for troubleshooting.
--load-dbs Comma-separated list of database names to load on startup.
bash
# Minimal required flags
./alosdb --username admin --password secret

# Custom data directory and database name
./alosdb --username admin --password secret \
    --data-path /var/lib/alosdb \
    --db-name myapp \
    --port 0.0.0.0:6900

Storage & Performance Flags

Tune the engine for your workload:

Flag Default Description
--shards 256 Number of shards for concurrent access. Higher values reduce lock contention but use more memory. Powers of 2 recommended.
--sync-mode async async — writes buffered in OS page cache (fastest). sync — writes fsynced to disk (safest).
--cache-mb 512 Hot cache size in MB. Frequently accessed documents are kept in memory.
--compression 1 Compression level: 0 = none, 1 = fast (LZ4-like), 9 = best ratio.
--disable-crc false Disable CRC integrity checks. Faster reads but no corruption detection.
--max-write-rate 0 Max write docs/sec rate limit. 0 = unlimited.
--max-offset-cache 0 Max offset-cache entries per shard. 0 = use engine default.
--hook-collections Comma-separated collection names to enable write hooks for.

sync-mode explained

async (default): Writes go to the OS page cache and are flushed to disk asynchronously. Maximum throughput (548K docs/sec remote, 2.2M ops/sec embedded). A sudden power loss could lose recent writes.

sync: Every write is fsynced to disk before returning. Full durability at the cost of throughput. Use for financial, medical, or other critical data.

Compression levels

Level Speed Ratio Use Case
0 Fastest (no compression) 1:1 SSDs with plenty of space
1 Fast ~2:1 Default — good balance
5 Medium ~3:1 Mixed workloads
9 Slow ~4:1 Archival, read-heavy workloads

Compaction

Background compaction reclaims disk space from deleted and updated documents:

Flag Default Description
--compaction false Enable background compaction.
--compact-interval 300 How often to check for compaction (seconds).
--compact-min-size 10485760 Minimum data file size (bytes) before compaction triggers. Default is 10 MB.
--compact-stale-ratio 0.3 Ratio of stale data (0.0–1.0) required to trigger compaction. At 0.3, compaction runs when 30% of data is stale.
--compact-parallel 1 Max concurrent compaction goroutines. Increase for SSDs with spare I/O.
bash
# Enable compaction with aggressive settings
./alosdb --username admin --password secret \
    --compaction \
    --compact-interval 120 \
    --compact-stale-ratio 0.2 \
    --compact-parallel 2

Compaction runs in the background and does not block reads or writes. It rewrites data files, removing stale entries, and atomically swaps the old file for the new one.

Cluster Replication

Enable cluster mode for multi-node replication:

Flag Default Description
--cluster false Enable cluster replication.
--cluster-port 0 Port for cluster data synchronization. Must be different from the main --port.
--cluster-bandwidth-mb 0 Bandwidth limit for cluster sync in MB/s. 0 = unlimited.
bash
# Node 1 — Primary
./alosdb --username admin --password secret \
    --port 0.0.0.0:6900 \
    --cluster \
    --cluster-port 6901

# Node 2 — Replica
./alosdb --username admin --password secret \
    --port 0.0.0.0:6900 \
    --cluster \
    --cluster-port 6901 \
    --cluster-bandwidth-mb 100

Web Panel

Built-in web administration panel for monitoring and management:

Flag Default Description
--webpanel-port 0 Port for the web panel. 0 = disabled.
--webpanel-bind 0.0.0.0 Bind address for the web panel.
--webpanel-user admin Web panel admin username.
--webpanel-pass Web panel admin password. Required when webpanel-port is set.
--webpanel-key Encryption key for session cookies (min 16 chars).
--webpanel-timeout 45 Session timeout in minutes.
--webpanel-users-file Path to a JSON file with additional web panel users.
bash
# Enable web panel on port 8080
./alosdb --username admin --password secret \
    --webpanel-port 8080 \
    --webpanel-pass mypanelpassword \
    --webpanel-key mysecretencryptionkey123

Client Configuration

The Go client library supports two configuration approaches:

Functional options (recommended)

go
db, err := alosdbclient.Connect("localhost:6900",
    alosdbclient.WithCredentials("admin", "secret"),
    alosdbclient.WithDatabase("myapp"),
    alosdbclient.WithTimeout(5 * time.Second),
    alosdbclient.WithBatchSize(50),
    alosdbclient.WithFlushInterval(2 * time.Millisecond),
)
Option Default Description
WithCredentials(user, pass) Server authentication credentials (required)
WithDatabase(name) "default" Target database for all operations
WithTimeout(d) 15s Per-request timeout
WithBatchSize(n) 100 Max requests per batch
WithFlushInterval(d) 1ms Max wait before sending a batch

Struct-based config

go
cfg := alosdbclient.DefaultClientConfig("localhost:6900")
cfg.Username = "admin"
cfg.Password = "secret"
cfg.PoolSize = 20
cfg.RequestTimeout = 10 * time.Second

db, err := alosdbclient.ConnectWithConfig(cfg)
Field Type Default Description
ServerAddr string TCP address of the server
PoolSize int 10 Connection pool size
Username string Auth username
Password string Auth password
RequestTimeout time.Duration 15s Per-request timeout
FireAndForget bool false Don’t wait for server ACK on writes

Production Deployment

A recommended production configuration with durability, compaction, and monitoring:

bash
# Production server
./alosdb \
    --username $ALOSDB_USER \
    --password $ALOSDB_PASS \
    --port 0.0.0.0:6900 \
    --data-path /var/lib/alosdb \
    --db-name production \
    --sync-mode sync \
    --shards 256 \
    --cache-mb 1024 \
    --compression 1 \
    --compaction \
    --compact-interval 180 \
    --compact-stale-ratio 0.25 \
    --compact-parallel 2 \
    --webpanel-port 8080 \
    --webpanel-pass $PANEL_PASS \
    --webpanel-key $PANEL_KEY

Key decisions

  • sync-mode sync — ensures committed data survives crashes
  • cache-mb 1024 — 1 GB hot cache for read-heavy workloads
  • compaction enabled — automatic disk reclamation
  • compact-parallel 2 — use spare I/O bandwidth on SSDs
  • webpanel enabled — monitor server health and collections

Never hard-code credentials in scripts. Use environment variables or a secrets manager. The examples above use $ALOSDB_USER, $ALOSDB_PASS, etc.

Minimal Setup

The fastest way to get a server running for development:

bash
# Start server (all defaults)
./alosdb --username dev --password dev

# Connect from Go
# go get github.com/guno1928/alosdbclient
go
db, _ := alosdbclient.Connect("localhost:6900",
    alosdbclient.WithCredentials("dev", "dev"),
)
defer db.Close()

// Ready to use
coll := db.Collection("test")
coll.InsertOne(alosdbclient.Document{"hello": "world"})
ESC
Configuration - ALOS DB

Configuration

ALOS DB exposes a compact but high-leverage configuration surface: shard count, cache sizing, sync mode, adaptive workers, compaction, web panel, and TCP server security. This page maps every important field back to the real defaults and validation rules in the codebase.

Default Config

alos.DefaultConfig(dbName) gives you a tuned baseline instead of a blank struct. The defaults prioritize local throughput and low operational friction: asynchronous sync, 256 shards, a hot-cache budget, zero required compaction config, and no web panel unless you opt in.

256 Shards

High default concurrency for both reads and writes without requiring manual tuning.

512 MB Cache

Hot-cache memory budget to keep frequently read documents close to the query path.

SyncAsync

Default durability mode favors throughput and latency over per-write fsync cost.

LZ4 Level 1

Fast compression enabled out of the box with low CPU overhead.

go
config := alos.DefaultConfig("mydb")

fmt.Printf("shards=%d cache=%dMB sync=%v\n",
    config.NumShards,
    config.HotCacheMemoryMB,
    config.SyncMode,
)
Field Default Source-backed meaning
DBName caller-supplied Logical database name and on-disk database identity
DataPath defaultDataPath() OS-specific storage root: Windows %APPDATA%\alosdb, macOS /usr/local/var/alosdb, Linux /etc/alosdb
SyncMode SyncAsync Asynchronous durability mode
HotCacheMemoryMB 512 Budget for the hot document cache
NumShards 256 Default partition count for concurrent storage paths
PreFetchNeighbors 10 How aggressively nearby records are prefetched during reads
CompressionLevel 1 Fast LZ4 compression
WorkerThresholds [{0,8},{100,32},{500,128},{1000,256},{5000,512},{10000,1024}] Adaptive background worker scaling table
Compaction nil Disabled until you explicitly opt in
WebPanel nil Browser UI remains off until configured

Core Fields

Most production configurations only touch a subset of the full struct. Start with the core storage and performance fields, then add compaction, web panel, and security once the data path and workload are stable.

Field Purpose When to change it
DBName Selects the database identity Always required
DataPath Storage root for on-disk data Set this explicitly for production deployments and containers
NumShards Controls internal partitioning and concurrency Raise or lower only after profiling contention or memory use
HotCacheMemoryMB Hot cache budget in megabytes Increase for read-heavy workloads; trim on small hosts
PreFetchNeighbors Neighbor read prefetch depth Lower for random access, raise for sequential scans
CompressionLevel Disk compression aggressiveness Use low values when CPU is precious
DisableCRC Disables checksum verification Only for controlled benchmarking, not general production
MaxWriteDocsPerSec Write-rate limiter Useful for backfills and shared hosts
LoadDBs Subset of databases to load Use when one process hosts many databases but only needs a few
HookCollections Collection hook registration list Use only when integrating hook-based extensions
MaxOffsetCacheEntries Offset cache sizing Touch only when profiling pagination-heavy workloads
Debug Verbose debug logging Enable temporarily during investigation, not steady state
go
config := alos.DefaultConfig("analytics")
config.DataPath = "/srv/alos/analytics"
config.HotCacheMemoryMB = 2048
config.NumShards = 256
config.PreFetchNeighbors = 16
config.MaxWriteDocsPerSec = 50000
config.Debug = false

db, err := alos.Open(config)

Sync Mode

The sync mode is the first durability/performance dial to understand. It controls how aggressively writes are synchronized to durable storage.

Mode Behavior Best fit
SyncAsync Default mode. Writes return before every persistence boundary is fully synced. General application workloads, low-latency services, most local deployments
SyncSync Stricter persistence path with higher write cost. Workflows that prefer stronger per-write durability over peak throughput
go
// Throughput-oriented default
fast := alos.DefaultConfig("events")
fast.SyncMode = alos.SyncAsync

// Stricter durability
strict := alos.DefaultConfig("ledger")
strict.SyncMode = alos.SyncSync

Practical rule: keep SyncAsync unless you have a clear durability requirement that justifies paying extra write latency on every commit.

Worker Thresholds

ALOS DB scales internal workers according to queue depth. The default table grows from 8 workers at idle to 1024 workers when the write queue is deeply saturated. This lets the system absorb bursty ingestion without forcing you to pin one worker count permanently.

Queue Size Workers Interpretation
0 8 Low idle overhead while still keeping write paths ready
100 32 Small backlog, moderate extra parallelism
500 128 Heavy but still controlled write traffic
1000 256 Sustained high-throughput ingestion
5000 512 Large burst absorption
10000 1024 Maximum default scaling tier
go
config := alos.DefaultConfig("write-heavy")
config.WorkerThresholds = []alos.WorkerThreshold{
    {QueueSize: 0, Workers: 16},
    {QueueSize: 250, Workers: 64},
    {QueueSize: 2000, Workers: 256},
    {QueueSize: 8000, Workers: 768},
}

Compaction

Compaction is off by default in DefaultConfig, which keeps the initial setup simple. When you need automated space recovery, start with DefaultCompactionConfig() and tune from there.

Compaction field Default Role
Enabled true Turns the background compaction scheduler on
Interval 300 Compaction cycle interval in seconds
MinFileSize 10 << 20 Only compact files at or above roughly 10 MB
StaleRatio 0.3 Requires about 30% stale content before rewrite
MaxParallel 1 Keeps rewrite pressure controlled by default
go
config := alos.DefaultConfig("archive")
config.Compaction = alos.DefaultCompactionConfig()
config.Compaction.Interval = 600
config.Compaction.MaxParallel = 2
config.Compaction.StaleRatio = 0.40

Start conservative: the shipped default compaction settings are tuned to avoid turning storage cleanup into a foreground performance problem.

Web Panel

The web panel is optional and validated aggressively. The defaults from DefaultWebPanelConfig() are intentionally incomplete until you supply a real password and encryption key.

WebPanel field Default Notes
Enabled true Default helper assumes you intend to run the panel
Port 8080 Panel listen port
BindAddress 127.0.0.1 Local-only by default
MasterUsername admin Administrative login user
MasterPassword "" Must be set and must not be trivial
SessionTimeout 45 Session lifetime setting from the source default helper
EncryptionKey "" Required and must be at least 16 chars
UsersFilePath users.json Backs user storage for the panel
go
panel := alos.DefaultWebPanelConfig()
panel.MasterPassword = os.Getenv("ALOS_PANEL_PASSWORD")
panel.EncryptionKey = os.Getenv("ALOS_PANEL_KEY")
panel.BindAddress = "127.0.0.1"
panel.Port = 8888

config := alos.DefaultConfig("ops")
config.WebPanel = panel

Validation rules from source: the panel rejects an empty EncryptionKey, keys shorter than 16 characters, empty passwords, insecure passwords like admin or password, and passwords shorter than 8 characters.

TCP Security

The TCP server path validates credentials before the listener starts. If you call StartServer or StartServerAsync without credentials, startup fails.

Requirement Validation behavior
Username Must be non-empty for the TCP server path
Password Must be non-empty and at least 8 characters
Server startup Returns an error before binding if validation fails
go
config := alos.DefaultConfig("remote")
config.Username = os.Getenv("ALOS_SERVER_USER")
config.Password = os.Getenv("ALOS_SERVER_PASS")

server, err := alos.StartServerAsync(":9210", config)
if err != nil {
    log.Fatal(err)
}
defer server.Stop()

Cluster Settings

Cluster settings live under Config.Cluster. The core fields are simple: whether clustering is enabled, the data port to use, and the sync bandwidth cap in MB/s.

Cluster field Meaning
Enabled Turns cluster replication behavior on
DataPort Port used for node-to-node data transport
SyncBandwidthMB Caps replication bandwidth
go
config := alos.DefaultConfig("clustered")
config.Cluster = &alos.ClusterSettings{
    Enabled:         true,
    DataPort:        9310,
    SyncBandwidthMB: 128,
}

Production Example

This example brings the major pieces together: explicit storage path, tuned cache, enabled compaction, secure web panel, TCP server credentials, and optional cluster settings.

go
package main

import (
    "log"
    "os"

    "alosdb/pkg/alos"
)

func main() {
    config := alos.DefaultConfig("production")
    config.DataPath = "/srv/alos/production"
    config.NumShards = 256
    config.HotCacheMemoryMB = 4096
    config.PreFetchNeighbors = 16
    config.SyncMode = alos.SyncAsync
    config.CompressionLevel = 1
    config.Username = os.Getenv("ALOS_SERVER_USER")
    config.Password = os.Getenv("ALOS_SERVER_PASS")

    config.Compaction = alos.DefaultCompactionConfig()
    config.Compaction.Interval = 600
    config.Compaction.MaxParallel = 2

    panel := alos.DefaultWebPanelConfig()
    panel.Port = 8888
    panel.MasterPassword = os.Getenv("ALOS_PANEL_PASSWORD")
    panel.EncryptionKey = os.Getenv("ALOS_PANEL_KEY")
    config.WebPanel = panel

    config.Cluster = &alos.ClusterSettings{
        Enabled:         true,
        DataPort:        9310,
        SyncBandwidthMB: 128,
    }

    server, err := alos.StartServerAsync(":9210", config)
    if err != nil {
        log.Fatal(err)
    }
    defer server.Stop()

    select {}
}
ESC