Documentation

Getting Started

ALOS DB ships as a compiled server binary and a lightweight Go client library. Start the server, install the client, and connect — no source code required.

Getting Started Benchmarks API Reference Queries Indexing Data Management Transactions Configuration FAQ

Architecture

ALOS DB uses a client-server architecture. You get two deliverables:

  • Server binary — a compiled executable (alosdb on Linux, alosdb.exe on Windows) that stores data, manages indexes, and handles queries
  • Client library — a Go package (github.com/guno1928/alosdbclient) that your application imports to connect to the server

All communication is over TCP with MessagePack serialization and AES-256-GCM encryption. The client batches requests for efficient network utilization.

The server binary is self-contained — no runtime dependencies, no JVM, no Docker required. Just copy the binary and run it.

Start the Server

Download the server binary for your platform and start it with authentication credentials:

1

Start the server

bash 
# Linux
./alosdb --username admin --password secret --port localhost:6900

# Windows
alosdb.exe --username admin --password secret --port localhost:6900

The server is now listening on localhost:6900 with data stored in the OS default directory.

2

Custom data directory

bash 
./alosdb --username admin --password secret \
    --port localhost:6900 \
    --data-path /var/lib/alosdb \
    --db-name myapp \
    --sync-mode sync

The --username and --password flags are required. The server will refuse to start without them.

All Server Flags

text 
--port              TCP listen address          (default: localhost:6900)
--data-path         Data directory              (default: OS-specific)
--db-name           Database name               (default: alosdb)
--username          Auth username               (required)
--password          Auth password               (required)
--shards            Number of shards            (default: 256)
--sync-mode         Write mode: async or sync   (default: async)
--cache-mb          Hot cache size in MB        (default: 512)
--compression       Compression level 0-9       (default: 1)
--debug             Enable debug mode           (default: false)
--compaction        Enable auto-compaction      (default: false)
--webpanel-port     Web panel port (0=disabled) (default: 0)
--cluster           Enable cluster replication  (default: false)

See Configuration for every flag and its meaning.

Install the Client Library

Add the client library to your Go module:

bash 
go get github.com/guno1928/alosdbclient

Requires Go 1.21 or later. The client library has only two dependencies: msgpack/v5 for serialization and golang.org/x/crypto for AES-GCM encryption.

Connect to the Server

Use Connect() with functional options to establish a connection:

go 
package main

import (
    "log"
    "github.com/guno1928/alosdbclient"
)

func main() {
    db, err := alosdbclient.Connect("localhost:6900",
        alosdbclient.WithCredentials("admin", "secret"),
        alosdbclient.WithDatabase("myapp"),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // db implements DatabaseInterface — ready to use
    users := db.Collection("users")
    _ = users
}

The Connect() function returns a DatabaseInterface that provides access to collections, transactions, stats, and more.

Insert Documents

A Document is a map[string]interface{}. Insert single or bulk documents:

InsertOne

go 
users := db.Collection("users")

id, err := users.InsertOne(alosdbclient.Document{
    "name":  "Alice",
    "email": "alice@example.com",
    "age":   30,
    "tags":  []string{"admin", "active"},
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("Inserted:", id)  // auto-generated _id

InsertMany

go 
docs := []alosdbclient.Document{
    {"name": "Bob", "age": 25},
    {"name": "Carol", "age": 28},
    {"name": "Dave", "age": 35},
}

ids, err := users.InsertMany(docs)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Inserted %d documents\n", len(ids))

Query Documents

Find by ID

go 
doc, err := users.FindOne(alosdbclient.Document{"_id": id})
if err != nil {
    log.Fatal(err)
}
fmt.Println(doc["name"])  // "Alice"

Find by field

go 
// Single result
user, _ := users.FindOne(alosdbclient.Document{"name": "Alice"})

// Multiple results with query operators
adults, _ := users.FindMany(alosdbclient.Document{
    "age": alosdbclient.Document{"$gte": 21},
})

for _, u := range adults {
    fmt.Printf("%s (age %v)\n", u["name"], u["age"])
}

For all query operators ($eq, $gt, $in, $regex, $and, $or, etc.), see Queries.

Update & Delete

UpdateOne

go 
err = users.UpdateOne(
    alosdbclient.Document{"name": "Alice"},
    alosdbclient.Document{"$set": alosdbclient.Document{"age": 31}},
)

DeleteOne / DeleteMany

go 
// Delete one
err = users.DeleteOne(alosdbclient.Document{"name": "Bob"})

// Delete many
deleted, err := users.DeleteMany(alosdbclient.Document{
    "age": alosdbclient.Document{"$lt": 18},
})
fmt.Printf("Deleted %d documents\n", deleted)

UpsertOne

go 
// Insert if not found, update if found
isNew, err := users.UpsertOne(
    alosdbclient.Document{"email": "eve@example.com"},
    alosdbclient.Document{"$set": alosdbclient.Document{
        "name": "Eve",
        "age":  29,
    }},
)
fmt.Println("Was inserted:", isNew)

Transactions

ALOS DB supports ACID transactions with snapshot isolation. Use the closure pattern for automatic commit/rollback:

go 
err = db.Transaction(func(tx alosdbclient.TransactionInterface) error {
    users := tx.Collection("users")
    accounts := tx.Collection("accounts")

    // Read inside transaction
    user, err := users.FindOne(alosdbclient.Document{"name": "Alice"})
    if err != nil {
        return err  // auto-rollback
    }

    // Write inside transaction
    _, err = accounts.InsertOne(alosdbclient.Document{
        "user_id": user["_id"],
        "balance": 100.0,
    })
    return err  // auto-commit if nil
})

For manual transactions and advanced patterns, see Transactions.

Client Options

Customize the client connection with functional options:

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 none Username and password for server authentication
WithDatabase "default" Target database name for all operations
WithTimeout 15s Per-request timeout
WithBatchSize 100 Max requests per batch
WithFlushInterval 1ms Max wait before sending a batch

Complete Application

A production-ready example — connect, insert, query, update, and transaction:

go 
package main

import (
    "fmt"
    "log"
    "github.com/guno1928/alosdbclient"
)

func main() {
    // Connect to server
    db, err := alosdbclient.Connect("localhost:6900",
        alosdbclient.WithCredentials("admin", "secret"),
        alosdbclient.WithDatabase("myapp"),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    users := db.Collection("users")

    // Insert
    id, _ := users.InsertOne(alosdbclient.Document{
        "name": "Alice", "email": "alice@example.com", "age": 30,
    })
    fmt.Println("Inserted:", id)

    // Query
    doc, _ := users.FindOne(alosdbclient.Document{"name": "Alice"})
    fmt.Println("Found:", doc["email"])

    // Update
    users.UpdateOne(
        alosdbclient.Document{"_id": id},
        alosdbclient.Document{"$set": alosdbclient.Document{"age": 31}},
    )

    // Transaction
    db.Transaction(func(tx alosdbclient.TransactionInterface) error {
        txUsers := tx.Collection("users")
        txUsers.InsertOne(alosdbclient.Document{
            "name": "Bob", "age": 25,
        })
        return nil  // auto-commit
    })

    // Count
    count := users.Count()
    fmt.Printf("Total users: %d\n", count)

    // Stats
    stats := db.GetStats()
    fmt.Println("Server stats:", stats)
}
ESC