Appendix C: Configuration Reference

Complete reference for configuring the AstraeaDB server, including the TOML configuration file, command-line flags, environment variables, and the JSON import format.

C.1 Server Configuration (TOML)

AstraeaDB reads its configuration from a TOML file. By default, the server looks for astraeadb.toml in the current working directory. You can specify a different path with the --config flag or the ASTRAEA_CONFIG environment variable.

Below is a complete configuration file with all available options and their default values:

# =============================================================================
# AstraeaDB Server Configuration
# =============================================================================

# ---------------------------------------------------------------------------
# [server] — Network binding and protocol ports
# ---------------------------------------------------------------------------
[server]
bind = "0.0.0.0"           # IP address to listen on (0.0.0.0 = all interfaces)
port = 7687                 # JSON-TCP protocol port
grpc_port = 7688            # gRPC protocol port
flight_port = 7689          # Apache Arrow Flight protocol port

# ---------------------------------------------------------------------------
# [storage] — Data persistence and buffer management
# ---------------------------------------------------------------------------
[storage]
data_dir = "/var/lib/astraeadb/data"   # Directory for graph data files
wal_dir = "/var/lib/astraeadb/wal"     # Directory for write-ahead log
page_size = 8192                       # Page size in bytes (4096, 8192, or 16384)
buffer_pool_pages = 10000              # Number of pages in the buffer pool

# ---------------------------------------------------------------------------
# [tls] — Transport Layer Security
# ---------------------------------------------------------------------------
[tls]
enabled = false                            # Enable TLS for all protocols
cert_path = "/etc/astraeadb/server.crt"    # Path to server certificate (PEM)
key_path = "/etc/astraeadb/server.key"     # Path to server private key (PEM)
ca_cert_path = "/etc/astraeadb/ca.crt"    # Path to CA certificate for mutual TLS

# ---------------------------------------------------------------------------
# [auth] — Authentication
# ---------------------------------------------------------------------------
[auth]
enabled = false             # Enable token-based authentication
# Tokens are configured via the admin API at runtime.
# When enabled, all client requests must include a valid
# Bearer token in the connection handshake.

# ---------------------------------------------------------------------------
# [vector] — HNSW vector index parameters
# ---------------------------------------------------------------------------
[vector]
dimensions = 128           # Dimensionality of embedding vectors
m = 16                      # HNSW: max connections per layer
ef_construction = 200      # HNSW: beam width during index build
ef_search = 50             # HNSW: beam width during search
distance_metric = "cosine" # Distance metric: cosine, euclidean, dot_product

# ---------------------------------------------------------------------------
# [connection] — Connection pool and timeout settings
# ---------------------------------------------------------------------------
[connection]
max_connections = 1024             # Maximum simultaneous client connections
max_concurrent_requests = 256     # Maximum in-flight requests across all connections
idle_timeout_seconds = 300        # Close idle connections after this many seconds
request_timeout_seconds = 30     # Maximum time for a single request to complete

Section-by-section explanation

[server]

Controls which network interfaces and ports the server binds to. AstraeaDB exposes three ports, one for each supported transport protocol. Set bind to "127.0.0.1" if you only want to accept local connections, or "0.0.0.0" to listen on all interfaces.

[storage]

Configures where data is persisted and how the buffer pool manages in-memory pages. The write-ahead log (WAL) ensures durability: every mutation is written to the WAL before being applied to the data files.

[tls]

Enables encrypted communication between clients and the server. When enabled, all three protocol ports (JSON-TCP, gRPC, Arrow Flight) require TLS. If ca_cert_path is set, mutual TLS (mTLS) is enforced: clients must present a certificate signed by the specified CA.

[auth]

Controls token-based authentication. When enabled, clients must present a valid Bearer token during the connection handshake. Tokens are managed through the admin API (not in the config file) and can be created, revoked, and rotated at runtime.

[vector]

Configures the HNSW (Hierarchical Navigable Small World) index used for vector search. These parameters directly affect the trade-off between index build time, search accuracy, and memory usage.

[connection]

Controls connection pooling, concurrency limits, and timeouts. These settings protect the server from being overwhelmed by too many simultaneous clients or long-running queries.

C.2 Command-Line Flags

Command-line flags override values from the configuration file. They are useful for quick testing or container deployments where you want to set a single option without modifying a file.

C.3 CLI Commands

The astraeadb binary supports several subcommands for managing the server and data.

C.4 Environment Variables

Environment variables provide a third layer of configuration, with the highest precedence. The priority order is: environment variable > CLI flag > config file > built-in default.

C.5 Configuration Precedence

When the same setting is specified in multiple places, AstraeaDB resolves it using the following priority order (highest to lowest):

C.6 JSON Import Format

The astraeadb import command expects a JSON file with the following structure. Node references in the edges array use zero-based indices into the nodes array.

{
  "nodes": [
    {
      "labels": ["Person"],
      "properties": {
        "name": "Alice",
        "age": 30
      }
    },
    {
      "labels": ["Person"],
      "properties": {
        "name": "Bob",
        "age": 25
      }
    },
    {
      "labels": ["Company"],
      "properties": {
        "name": "Acme Corp",
        "industry": "Technology"
      }
    }
  ],
  "edges": [
    {
      "source": 0,
      "target": 1,
      "edge_type": "KNOWS",
      "properties": {
        "since": 2020
      }
    },
    {
      "source": 0,
      "target": 2,
      "edge_type": "WORKS_AT",
      "properties": {
        "role": "Engineer",
        "start_date": "2021-03-15"
      }
    }
  ]
}

Field reference

Node fields

Edge fields