Every server flag, client option, compaction setting, cluster configuration, and web panel parameter.
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. |
# 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
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. |
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.
| 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 |
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. |
# 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.
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. |
# 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
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. |
# Enable web panel on port 8080
./alosdb --username admin --password secret \
--webpanel-port 8080 \
--webpanel-pass mypanelpassword \
--webpanel-key mysecretencryptionkey123
The Go client library supports two configuration approaches:
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 |
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 |
A recommended production configuration with durability, compaction, and monitoring:
# 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
Never hard-code credentials in scripts. Use environment variables or a secrets manager.
The examples above use $ALOSDB_USER, $ALOSDB_PASS, etc.
The fastest way to get a server running for development:
# Start server (all defaults) ./alosdb --username dev --password dev # Connect from Go # go get github.com/guno1928/alosdbclient
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"})