DOCSEARCHbyAlgolia
Submit Docs

SugarDB Documentation

website·Indexed 31 days ago

https://sugardb.io/

Documentation for SugarDB, featuring command references for strings, sets, sorted sets, and pub/sub. Includes guides on memory limits and passive eviction, as well as instructions for extending the database via JavaScript modules using the Otto engine or programmatic method definitions.

Tokens
35.5K
Snippets
320
Records
360
Agent score
54%

What's inside SugarDB

  1. Overview of SugarDB capabilities

    SugarDB is a highly configurable, distributed, in-memory data store and cache implemented in Go. It can be utilized as an independent service or imported as a Go library into existing projects. It supports a variety of data structures including Lists, Sets, Sorted Sets, and Hashes.

  2. Extend SugarDB functionality with custom commands

    SugarDB allows developers to extend its built-in command set to add missing functionality or custom logic. There are currently two primary methods for extending the system, with a third in development:

    1. Embedded API
    2. Shared object plugins
    3. Lua modules (Coming soon)

  3. Manage data persistence with the Append-Only File (AOF) engine

    SugarDB uses an append-only log file to track every write command. To optimize performance and storage, the log is compacted into a snapshot once a configured threshold of write commands is reached, after which a new log file begins. Users can manually trigger this compaction process using the REWRITEAOF command.
    REWRITEAOF

  4. Choose a data persistence strategy for SugarDB

    SugarDB primarily stores data in-memory but provides two strategies to persist data to disk for recovery after instance restarts: Append-Only Files and Snapshots. In standalone mode, if both strategies are configured, SugarDB defaults to using the append-only strategy.

  5. Build SugarDB on non-MacOS operating systems

    For operating systems other than MacOS, use the Go compiler to build the project. You must provide the relevant build flags specific to your system architecture.
    go build [relevant-flags-for-your-system]

  6. Understand passive and active eviction mechanisms

    Echovault employs two methods for removing expired keys:

    1. Passive Eviction: Expired keys are not deleted immediately. They remain in the store until they are accessed, at which point they are deleted.
    2. Active Eviction: A background process periodically samples a set of volatile keys and deletes those that have expired.

  7. Choose a SugarDB deployment mode

    SugarDB supports different operational modes depending on the required availability and consistency:

    • Standalone mode: A single instance running in isolation.
    • Replication cluster: A strongly consistent cluster based on the RAFT consensus algorithm.
    • Sharding: This feature is currently planned for future implementation.

  8. Manage user permissions using ACL flags

    SugarDB provides specific ACL flags to quickly modify user access levels and authentication requirements:

    • nopass: Removes all passwords associated with the user and allows future TCP connections to authenticate without a password.
    • resetpass: Removes all associated passwords but does not enable the nopass flag (authentication is still required).
    • nocommands: Completely blocks the user from executing any commands.
    • resetkeys (aliased as nokeys): Blocks the user from reading or writing any keys.
    • resetchannels: Grants the user access to all pub/sub channels.

  9. Restore SugarDB data from an AOF file

    To restore data from an Append-Only File (AOF), start the SugarDB instance with the --restore-aof flag set to true. You must also specify the directory containing the AOF file using the --data-dir flag. SugarDB will load the most recent snapshot (if available) and then replay all subsequent write commands from the latest log file.
    sugardb --restore-aof true --data-dir /path/to/aof/folder

  10. Example: Copy a key in SugarDB using Go

    This example demonstrates how to copy the value of key 'hello' to a new key 'bye' within the same database.
    db, err := sugardb.NewSugarDB()
if err != nil {
  log.Fatal(err)
}
db.Set("hello", "world")
key = db.Copy("hello", "bye")

  11. Manage and execute loaded modules

    Once a module is loaded, you can list all active modules, execute the custom commands defined within them, or unload them to remove them from the instance.
    # List all loaded modules
MODULE LIST

# Execute a custom command
JS.EXAMPLE key1 10

# Unload a module
MODULE UNLOAD path/to/module/module.js
    // Embedded API: List modules
modules := server.ListModules()

// Embedded API: Execute command
res, err := server.ExecuteCommand("JS.EXAMPLE", "key1", "10")

// Embedded API: Unload module
server.UnloadModule("path/to/module/module.js")

  12. Install SugarDB server via Docker

    SugarDB is available as a Docker image via Docker Hub and the GitHub Container Registry.
    # From Docker Hub
docker pull echovault/sugardb

# From GitHub Container Registry
docker pull ghcr.io/echovault/sugardb