Chapter 3: Installation and Setup

Everything you need to get AstraeaDB running on your machine, from building the Rust source to making your first client connection in Python, R, Go, or Java.

3.1 Prerequisites

Before installing AstraeaDB, make sure your development environment meets the following requirements.

Rust Toolchain (Required)

AstraeaDB is written in Rust. You will need the Rust toolchain installed via rustup:

# Install Rust (if you haven't already)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify installation
rustc --version   # should be 1.75+ recommended
cargo --version

Supported Platforms

Optional: Client Language SDKs

AstraeaDB ships official client libraries for four languages. Install whichever you plan to use:

Java Dependency (Maven)

<!-- pom.xml -->
<dependency>
  <groupId>com.astraeadb</groupId>
  <artifactId>astraeadb-unified-client</artifactId>
  <version>0.1.0</version>
</dependency>

Java Dependency (Gradle)

implementation 'com.astraeadb:astraeadb-unified-client:0.1.0'

3.2 Building from Source

Clone the repository and build the entire workspace in release mode:

# Clone the repository
git clone https://github.com/AstraeaDB/AstraeaDB-Official.git
cd graph-astraeadb

# Build all crates in release mode
cargo build --workspace --release

# Run the full test suite
cargo test --workspace

After a successful build, the binaries are located in target/release/:

Verifying the Build

Confirm everything is working:

# Check the CLI version
./target/release/astraea-cli --version
# AstraeaDB CLI v0.1.0

# Run a quick smoke test
cargo test --workspace -- --test-threads=1

3.3 Starting the Server

Basic Startup

The simplest way to start AstraeaDB is through the CLI:

cargo run -p astraea-cli -- serve

This starts the server with default settings: binding to 127.0.0.1 on the standard ports.

Custom Bind Address and Port

To expose the server on all network interfaces (for remote connections), specify the bind address and port:

cargo run -p astraea-cli -- serve --bind 0.0.0.0 --port 7687

Default Ports

AstraeaDB listens on three ports, each serving a different protocol:

Configuration via TOML

For production deployments, use a TOML configuration file instead of command-line flags. Create a file called astraeadb.toml:

# astraeadb.toml - AstraeaDB Server Configuration

[server]
bind     = "0.0.0.0"
port     = 7687
grpc_port = 7688
flight_port = 7689

[storage]
data_dir = "/var/lib/astraeadb/data"
wal_dir  = "/var/lib/astraeadb/wal"

[storage.tiering]
hot_cache_mb  = 4096     # RAM for pointer-swizzled subgraphs
warm_cache_mb = 16384    # NVMe page cache
cold_backend  = "local"  # "local", "s3", or "gcs"

[logging]
level = "info"          # "debug", "info", "warn", "error"
file  = "/var/log/astraeadb/server.log"

Start the server with your configuration:

cargo run -p astraea-cli -- serve --config astraeadb.toml

3.4 Your First Connection

With the server running, let us connect from each of the supported client languages. Each snippet opens a connection, sends a ping command to verify connectivity, and prints the server response.

from astraeadb import AstraeaClient

with AstraeaClient("127.0.0.1", 7687) as client:
    result = client.ping()
    print(f"Connected! Server says: {result}")

source("r_client.R")

client <- AstraeaClient$new("127.0.0.1", 7687)
client$connect()
result <- client$ping()
cat("Connected! Server says:", result, "\n")
client$close()

package main

import (
    "context"
    "fmt"
    "github.com/AstraeaDB/AstraeaDB-Official"
)

func main() {
    client := astraeadb.NewClient(astraeadb.WithAddress("127.0.0.1", 7687))
    ctx := context.Background()
    client.Connect(ctx)
    defer client.Close()
    result, _ := client.Ping(ctx)
    fmt.Println("Connected!", result)
}

import com.astraeadb.unified.UnifiedClient;

try (var client = UnifiedClient.builder()
        .host("127.0.0.1").port(7687).build()) {
    client.connect();
    var result = client.ping();
    System.out.println("Connected! " + result);
}

If everything is working, you should see output like:

Connected! Server says: PONG (AstraeaDB v0.1.0)

3.5 The Interactive Shell

AstraeaDB includes a built-in interactive shell (REPL) for running queries directly from the terminal, without writing a separate client program.

Launching the Shell

cargo run -p astraea-cli -- shell

You will see a prompt like this:

   _        _                        ____  ____
  / \   ___| |_ _ __ __ _  ___  __ _|  _ \| __ )
 / _ \ / __| __| '__/ _` |/ _ \/ _` | | | |  _ \
/ ___ \\__ \ |_| | | (_| |  __/ (_| | |_| | |_) |
/_/   \_\___/\__|_|  \__,_|\___|\__,_|____/|____/

AstraeaDB Interactive Shell v0.1.0
Type 'help' for commands, 'exit' to quit.

astraeadb>

Example Session

Here is a quick session that creates some data and queries it:

# Create a node with label "Person" and properties
astraeadb> CREATE (p:Person {name: "Alice", age: 30}) RETURN p
+-------+------------------------------------+
| p.id  | p.labels | p.name | p.age          |
+-------+------------------------------------+
| nd-1  | Person   | Alice  | 30             |
+-------+------------------------------------+
1 row returned in 2ms

# Create another node and an edge between them
astraeadb> CREATE (b:Person {name: "Bob", age: 25}) RETURN b
1 row returned in 1ms

astraeadb> MATCH (a:Person {name: "Alice"}), (b:Person {name: "Bob"})
       CREATE (a)-[:KNOWS {since: 2020}]->(b)
       RETURN a.name, b.name
+-------------------+
| a.name | b.name   |
+-------------------+
| Alice  | Bob      |
+-------------------+
1 row returned in 3ms

# Query for connections
astraeadb> MATCH (p:Person)-[r:KNOWS]->(friend)
       RETURN p.name, friend.name, r.since
+-------------------------------+
| p.name | friend.name | r.since|
+-------------------------------+
| Alice  | Bob         | 2020   |
+-------------------------------+
1 row returned in 1ms

Useful Shell Commands