Skip to main content

Getting Started with DiceDB

This guide provides a practical introduction to DiceDB, covering installation, basic usage, and project-specific setup.

Installation​

Prerequisites​

  • Go: Ensure Go is installed and configured.
  • Docker: (Optional) If you prefer to run DiceDB using Docker.

Building from Source​

  1. Clone the DiceDB repository:

    git clone https://github.com/dicedb/dice
    cd dice

  2. Build the DiceDB binary:

    make build

    This command compiles the dicedb binary.

Running with Docker (Alternative)​

  1. Pull the DiceDB Docker image:

    docker run -p 7379:7379 dicedb/dicedb:latest

    This starts a DiceDB server on port 7379.

Usage​

Running the Server​

  • From Source:

    ./dicedb --engine ironhawk --log-level debug

    This starts the server with the Ironhawk engine and debug logging.

  • Using Docker: The server starts automatically after running the docker run command.

Connecting with the CLI​

  1. Install DiceDB CLI:

    sudo su
    curl -sL https://raw.githubusercontent.com/DiceDB/dicedb-cli/refs/heads/master/install.sh | sh

  2. Connect to the server: Open a new terminal and run:

    dicedb-cli

    This connects to the local DiceDB instance on port 7379.

Basic Commands​

localhost:7379> SET mykey "Hello, DiceDB!"
OK
localhost:7379> GET mykey
"Hello, DiceDB!"

Project-Specific Setup​

Configuration​

  • DiceDB uses a configuration file (dicedb.yaml) located in:

    • macOS: /usr/local/etc/dicedb/
    • Linux: /etc/dicedb/
    • Current working directory: if running without sudo privileges

    You can initialize the config file with:

    go run main.go config-init

Dependencies​

  • Consider checking out the dicedb-go repository locally for development, by adding the following line to the end of the go.mod file:
replace github.com/dicedb/dicedb-go => ../dicedb-go
This ensures you're using your local changes in the `dice` project. Remember to remove this line before committing.

Testing​

  • Unit tests:

    make unittest

    To run a specific unit test:

    TEST_FUNC=TestByteList make unittest-one

  • Integration tests: Make sure the DiceDB server is running.

    make test

    To run a specific integration test:

    TEST_FUNC=^TestSet$ make test-one

Logging​

DiceDB leverages structured logging. For the best practice, please consider the points in CONTRIBUTING/logging.md.

slog.Info("starting DiceDB", slog.String("version", config.DiceDBVersion))  // okay