alosdbclient

README

ALOS DB Client

Go client library for ALOS DB — a high-performance document database with MongoDB-compatible queries, built-in indexing, and clustering support.

Server Licensing

ALOS DB server is proprietary software. A license must be purchased to run the server in production. Contact us or visit alos.gg for licensing details.

Documentation

Full documentation is available at https://alos.gg/dbdocs/.

Installation

go get github.com/guno1928/alosdbclient

Quick Start

package main

import (
	"fmt"
	"log"
	"time"

	alosdbclient "github.com/guno1928/alosdbclient"
)

func main() {
	db, err := alosdbclient.Connect("localhost:6900",
		alosdbclient.WithCredentials("admin", "secret"),
		alosdbclient.WithTimeout(10*time.Second),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	coll := db.Collection("users")

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

	// Find
	user, _ := coll.FindOne(alosdbclient.Document{"_id": id})
	fmt.Println("Found:", user)
}

Query Protection

When using untrusted input in queries, always validate and sanitize values before constructing documents. Untrusted input containing operator keys such as $ne can bypass authentication checks or leak data.

// Validate input before use
if username == "" || password == "" {
	log.Fatal("missing credentials")
}

user, _ := coll.FindOne(alosdbclient.Document{
	"username": username,
	"password": password,
})

For server-side literal-value helpers that prevent operator injection, see the ALOS DB documentation.

Configuration Options

Option	Description
WithBatchSize(n)	Batch size for request pipelining
WithFlushInterval(d)	Max time to wait before flushing a batch
WithTimeout(d)	Per-request timeout
WithCacheTTL(d)	Client-side cache TTL
WithoutCache()	Disable client-side caching
WithDatabase(name)	Target database name
WithCredentials(user, pass)	Authentication

Transactions

err := db.Transaction(func(tx alosdbclient.TransactionInterface) error {
	users := tx.Collection("users")
	users.InsertOne(alosdbclient.Document{"name": "Bob"})
	users.UpdateOne(
		alosdbclient.Document{"name": "Alice"},
		alosdbclient.Document{"$set": alosdbclient.Document{"age": 31}},
	)
	return nil
})

License

The ALOS DB server is proprietary software requiring a purchased license. This client library is provided for use with a licensed ALOS DB server.

Documentation

Index

• func Arr(items ...interface{}) []interface{}
• func Bool(v bool) bool
• func Bytes(v []byte) []byte
• func Float(v float64) float64
• func Int(v int) int
• func Int64(v int64) int64
• func Nil() interface{}
• func SetClientLogging(enabled bool)
• func Str(v string) string
• func Time(v time.Time) time.Time
• type Client
  • func (c *Client) Close()
  • func (c *Client) Flush() error
• type ClientConfig
  • func DefaultClientConfig(serverAddr string) *ClientConfig
• type ClientOption
  • func WithBatchSize(size int) ClientOption
  • func WithCacheTTL(ttl time.Duration) ClientOption
  • func WithCredentials(username, password string) ClientOption
  • func WithDatabase(name string) ClientOption
  • func WithFlushInterval(interval time.Duration) ClientOption
  • func WithTimeout(timeout time.Duration) ClientOption
  • func WithoutCache() ClientOption
• type CollectionInterface
• type DatabaseInterface
  • func Connect(serverAddr string, opts ...ClientOption) (DatabaseInterface, error)
  • func ConnectWithConfig(config *ClientConfig, opts ...ClientOption) (DatabaseInterface, error)
• type Document
  • func Map(items ...interface{}) Document
  • func (d Document) GetID() string
• type ImportResult
• type TransactionInterface
• type TxCollectionInterface

Functions

func Arr

func Arr(items ...interface{}) []interface{}

func Bool

func Bool(v bool) bool

func Bytes

func Bytes(v []byte) []byte

func Float

func Float(v float64) float64

func Int

func Int(v int) int

func Int64

func Int64(v int64) int64

func Nil

func Nil() interface{}

func SetClientLogging

func SetClientLogging(enabled bool)

func Str

func Str(v string) string

func Time

func Time(v time.Time) time.Time

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client manages a connection to a remote ALOS DB server.

func (*Client) Close

func (c *Client) Close()

Close flushes pending writes and closes the connection.

func (*Client) Flush

func (c *Client) Flush() error

Flush sends any pending batched requests immediately.

type ClientConfig

type ClientConfig struct {
	ServerAddr     string
	PoolSize       int
	Username       string
	Password       string
	RequestTimeout time.Duration
	CacheTTL       time.Duration
	DisableCache   bool
	FireAndForget  bool
}

ClientConfig configures a client connection to a remote ALOS DB server.

ServerAddr is the TCP address of the server (e.g. "localhost:6900").

PoolSize is the number of pooled connections. Default is 10.

Username is the authentication username.

Password is the authentication password.

RequestTimeout is the per-request timeout. Default is 15 seconds.

CacheTTL is the client cache time-to-live. Default is 135 milliseconds.

DisableCache disables client-side caching.

FireAndForget sends requests without waiting for a response.

func DefaultClientConfig

func DefaultClientConfig(serverAddr string) *ClientConfig

DefaultClientConfig returns a ClientConfig with sensible defaults.

type ClientOption

type ClientOption func(*Client)

ClientOption is a functional option for configuring a client connection.

func WithBatchSize

func WithBatchSize(size int) ClientOption

WithBatchSize sets the batch size for client requests.

Example:

db, err := alosdbclient.Connect("localhost:6900", alosdbclient.WithBatchSize(500))

func WithCacheTTL

func WithCacheTTL(ttl time.Duration) ClientOption

WithCacheTTL sets the cache time-to-live for the client.

Example:

db, err := alosdbclient.Connect("localhost:6900", alosdbclient.WithCacheTTL(200*time.Millisecond))

func WithCredentials

func WithCredentials(username, password string) ClientOption

WithCredentials sets the username and password for client authentication.

Example:

db, err := alosdbclient.Connect("localhost:6900", alosdbclient.WithCredentials("admin", "secret"))

func WithDatabase

func WithDatabase(name string) ClientOption

WithDatabase sets the target database name for all requests.

Example:

db, err := alosdbclient.Connect("localhost:6900", alosdbclient.WithDatabase("analytics"))

func WithFlushInterval

func WithFlushInterval(interval time.Duration) ClientOption

WithFlushInterval sets the maximum time to wait before sending a batch.

Example:

db, err := alosdbclient.Connect("localhost:6900", alosdbclient.WithFlushInterval(5*time.Millisecond))

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets the per-request timeout for a client connection.

Example:

db, err := alosdbclient.Connect("localhost:6900", alosdbclient.WithTimeout(30*time.Second))

func WithoutCache

func WithoutCache() ClientOption

WithoutCache disables client-side caching entirely.

Example:

db, err := alosdbclient.Connect("localhost:6900", alosdbclient.WithoutCache())

type CollectionInterface

type CollectionInterface interface {
	InsertOne(doc Document) (string, error)
	InsertMany(docs []Document) ([]string, error)
	InsertManyRaw(rawDataMap map[string][]byte) error
	FindOne(query Document) (Document, error)
	FindOneReadonly(query Document) (Document, error)
	FindMany(query Document) ([]Document, error)
	FindManyReadonly(query Document) ([]Document, error)
	UpdateOne(filter Document, update Document) error
	DeleteOne(filter Document) error
	DeleteMany(filter Document) (int, error)
	UpdateMany(filter Document, update Document) (int, error)
	UpsertOne(filter Document, update Document) (bool, error)
	UpsertMany(filter Document, update Document) (int, int, error)
	Aggregate(pipeline []Document) ([]Document, error)
	Count() int64
	Drop()
	GetName() string
	HasCollection() (bool, error)
}

CollectionInterface defines the operations available on a document collection.

type DatabaseInterface

type DatabaseInterface interface {
	Collection(name string) CollectionInterface
	CreateCollection(name string) error
	ListCollections() []string
	GetStats() map[string]interface{}
	Close() error
	BeginTransaction() TransactionInterface
	Transaction(fn func(tx TransactionInterface) error) error
	Export(w io.Writer, collections []string) error
	Import(r io.Reader) (*ImportResult, error)
	DBExists(name string) (bool, error)
}

DatabaseInterface defines the operations available on a database instance.

func Connect

func Connect(serverAddr string, opts ...ClientOption) (DatabaseInterface, error)

Connect connects to a remote database server using TCP.

Example:

db, err := alosdbclient.Connect("localhost:6900",
	alosdbclient.WithCredentials("admin", "secret"),
	alosdbclient.WithTimeout(10*time.Second),
)
if err != nil {
	log.Fatal(err)
}
defer db.Close()

func ConnectWithConfig

func ConnectWithConfig(config *ClientConfig, opts ...ClientOption) (DatabaseInterface, error)

ConnectWithConfig connects to a remote server using a full ClientConfig.

Example:

config := &alosdbclient.ClientConfig{
	ServerAddr: "localhost:6900",
	PoolSize:   4,
	Username:   "admin",
	Password:   "secret",
}
db, err := alosdbclient.ConnectWithConfig(config)
if err != nil {
	log.Fatal(err)
}
defer db.Close()

type Document

type Document map[string]interface{}

Document is a map with string keys and arbitrary values.

func Map

func Map(items ...interface{}) Document

func (Document) GetID

func (d Document) GetID() string

GetID returns the document's _id field as a string, or "" if not set.

type ImportResult

type ImportResult struct {
	Total  int64
	Errors int64
}

ImportResult holds the result of an import operation.

type TransactionInterface

type TransactionInterface interface {
	Collection(name string) TxCollectionInterface
	Commit() error
	Rollback() error
	GetID() string
}

TransactionInterface defines operations within an ACID transaction.

type TxCollectionInterface

type TxCollectionInterface interface {
	FindOne(query Document) (Document, error)
	InsertOne(doc Document) (string, error)
	UpdateOne(filter Document, update Document) error
	DeleteOne(filter Document) error
}

TxCollectionInterface defines operations on a collection within a transaction.