GraphLite

A graph database as simple as SQLite for embedded processes

GraphLite is a fast, light-weight and portable embedded graph database that brings the power of the new ISO GQL (Graph Query Language) standard to the simplicity of SQLite.

GraphLite uses a single binary and is an ideal solution for applications requiring graph database capabilities without the complexity of client-server architectures.

Features

• ISO GQL Standard - Full implementation of ISO GQL query language based on grammar optimized from OpenGQL project
• Pattern Matching - Powerful MATCH clauses for graph traversal
• ACID Transactions - Full transaction support with isolation levels
• Embedded Storage - Sled-based embedded database (no server needed)
• Type System - Strong typing with validation and inference
• Query Optimization - Cost-based query optimization
• Pure Rust - Memory-safe implementation in Rust

Prerequisites

Before building GraphLite, you need to install Rust and a C compiler/linker.

macOS

# Install Xcode Command Line Tools (C compiler, linker)
xcode-select --install

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Restart terminal or run:
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

Linux (Ubuntu/Debian)

# Install build essentials
sudo apt-get update
sudo apt-get install build-essential

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Restart terminal or run:
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

Linux (Fedora/RHEL)

# Install development tools
sudo dnf groupinstall "Development Tools"

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Restart terminal or run:
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

Getting Started

Get up and running with GraphLite in 3 simple steps:

Step 1: Installation

Choose your installation method:

Option A: Use as a Crate (Recommended for Rust Applications)

Add GraphLite to your Rust project - no cloning or building required:

# For application development (SDK - recommended)
cargo add graphlite-rust-sdk

# For advanced/low-level usage
cargo add graphlite

See: Using GraphLite as a Crate for complete integration guide.

Option B: Use Docker (Easiest for Quick Start)

Run GraphLite instantly with Docker - no installation required:

# Initialize database
docker run -it -v $(pwd)/mydb:/data ghcr.io/graphlite-ai/graphlite:latest \
  graphlite install --path /data/mydb --admin-user admin --admin-password secret

# Start interactive GQL shell
docker run -it -v $(pwd)/mydb:/data \
  -e GRAPHLITE_DB_PATH=/data/mydb \
  -e GRAPHLITE_USER=admin \
  -e GRAPHLITE_PASSWORD=secret \
  ghcr.io/graphlite-ai/graphlite:latest

See: Docker Guide for complete Docker setup including multi-architecture builds and Docker Compose.

Option C: Install CLI from crates.io

Install the GraphLite CLI tool directly from crates.io:

cargo install gql-cli

After installation, the graphlite binary will be available in your PATH.

Option D: Clone and Build (For Development/Contributing)

# Clone the repository
git clone https://github.com/GraphLite-AI/GraphLite.git
cd GraphLite

# Build the project
./scripts/build_all.sh --release

After building, the binary will be available at target/release/graphlite.

Custom Build Options

# Development build (faster compilation, slower runtime)
./scripts/build_all.sh

# Build and run tests
./scripts/build_all.sh --release --test

# Clean build (useful when dependencies change)
./scripts/build_all.sh --clean --release

# View all options
./scripts/build_all.sh --help

Advanced: Manual Build with Cargo

If you prefer to build manually without the script:

1. Build in release mode for production-use: bash cargo build --release

2. Build in debug mode for development:

   bash cargo build

Step 2: Initialize Database (For CLI Usage)

Note: If you're using GraphLite as a crate in your application, skip to Using GraphLite as a Crate instead.

# If you installed via 'cargo install gql-cli' (Option B)
graphlite install --path ./my_db --admin-user admin --admin-password secret

# If you built from source (Option C)
./target/release/graphlite install --path ./my_db --admin-user admin --admin-password secret

This command: - Creates a new database at path: ./my_db. - Sets up the admin user with the specified password. - Creates default admin and user roles. - Initializes the default schema.

Step 3: Start Using GQL (CLI)

# If you installed via 'cargo install gql-cli' (Option B)
graphlite gql --path ./my_db -u admin -p secret

# If you built from source (Option C)
./target/release/graphlite gql --path ./my_db -u admin -p secret

That's it! You're now ready to create graphs and run queries:

$ gql>

Next Steps: - Using GraphLite as a Crate - Embed in your Rust application (recommended) - Quick Start.md - 5-minute tutorial with CLI and first queries - Getting Started With GQL.md - Complete query language reference

CLI Reference

Show help:

# All commands and options
./target/release/graphlite --help

# Help for specific commands
./target/release/graphlite gql --help
./target/release/graphlite install --help

Global options (available for all commands): - -u, --user <USER> - Username for authentication - -p, --password <PASSWORD> - Password for authentication - -l, --log-level <LEVEL> - Set log level (error, warn, info, debug, trace, off) - -v, --verbose - Verbose mode (equivalent to --log-level debug) - -h, --help - Show help information - -V, --version - Show version information

Show version:

./target/release/graphlite --version

Testing

GraphLite includes comprehensive test coverage with 189 unit tests and 537 total tests (including integration and benchmark tests).

Note: Tests now run in parallel by default thanks to instance-based session isolation, providing ~10x faster test execution compared to the previous single-threaded approach.

Quick Testing

# Fast feedback during development (uses optimized release build)
cargo test --release

Comprehensive Testing

Recommended: Parallel Test Runner (~10x faster)

# Fast parallel execution (8 jobs, ~75 seconds for 169 tests)
./scripts/run_integration_tests_parallel.sh --release --jobs=8

# With failure analysis
./scripts/run_integration_tests_parallel.sh --release --jobs=8 --analyze

Note: Requires GNU Parallel (brew install parallel on macOS, apt install parallel on Ubuntu)

Alternative: Sequential Test Runner (slower but no dependencies)

# Run all integration tests sequentially (~10-15 minutes)
./scripts/run_integration_tests.sh --release

# Include detailed failure analysis for debugging
./scripts/run_integration_tests.sh --release --analyze

Specific Tests

# Run a specific integration test
cargo test --release --test <test_name>

# Example: Run aggregation tests
cargo test --release --test aggregation_tests

** Comprehensive testing documentation (In Progress)**, which will cover: - Test configuration and architecture - Test categories and organization - Writing tests with TestFixture - Debugging test failures - CI/CD configuration - Test runner script options

Configuration

GraphLite provides flexible configuration for logging, performance tuning, and production deployment.

Quick Configuration Examples

# Enable debug logging
./target/release/graphlite -v gql --path ./my_db -u admin -p secret

** Comprehensive configuration documentation (In Progress)**, which will cover: - Logging configuration (CLI flags, RUST_LOG, module-specific) - Performance tuning (caching, indexing, batch operations) - Production deployment (systemd, backups, monitoring) - Storage backend configuration - Security configuration (authentication, authorization) - Environment variables

Using GraphLite Like SQLite

GraphLite follows the same embedded database pattern as SQLite, making it familiar and easy to use:

Similarities to SQLite

Embedding in Your Application

Both databases can be embedded directly in your application without external dependencies:

SQLite (Rust):

use rusqlite::{Connection, Result};

fn main() -> Result<()> {
    // Open/create database file
    let conn = Connection::open("myapp.db")?;

    // Create table and insert data
    conn.execute("CREATE TABLE users (id INTEGER, name TEXT)", [])?;
    conn.execute("INSERT INTO users VALUES (1, 'Alice')", [])?;

    // Query data
    let mut stmt = conn.prepare("SELECT name FROM users")?;
    let names: Vec<String> = stmt.query_map([], |row| row.get(0))?.collect();

    Ok(())
}

GraphLite (Rust) - Recommended SDK:

use graphlite_sdk::GraphLite;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open database (SQLite-style API)
    let db = GraphLite::open("./myapp_db")?;

    // Create session
    let session = db.session("user")?;

    // Create schema and graph
    session.execute("CREATE SCHEMA myschema")?;
    session.execute("USE SCHEMA myschema")?;
    session.execute("CREATE GRAPH social")?;
    session.execute("USE GRAPH social")?;

    // Insert data with transaction
    let mut tx = session.transaction()?;
    tx.execute("INSERT (:Person {name: 'Alice'})")?;
    tx.commit()?;

    // Query data
    let result = session.query("MATCH (p:Person) RETURN p.name")?;

    Ok(())
}

GraphLite (Rust) - Advanced Core Library:

use graphlite::QueryCoordinator;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize database from path
    let coordinator = QueryCoordinator::from_path("./myapp_db")?;

    // Create session
    let session_id = coordinator.create_simple_session("user")?;

    // Create schema and graph
    coordinator.process_query("CREATE SCHEMA /myschema", &session_id)?;
    coordinator.process_query("CREATE GRAPH /myschema/social", &session_id)?;
    coordinator.process_query("SESSION SET GRAPH /myschema/social", &session_id)?;

    // Insert data
    coordinator.process_query(
        "INSERT (:Person {name: 'Alice'})",
        &session_id
    )?;

    // Query data
    let result = coordinator.process_query(
        "MATCH (p:Person) RETURN p.name",
        &session_id
    )?;

    // Display results
    for row in &result.rows {
        println!("Name: {:?}", row.values.get("p.name"));
    }

    Ok(())
}

Examples and Documentation

For Rust Applications: - SDK Examples - Recommended high-level API (start here!) - Examples - SDK (high-level) and bindings (low-level) examples for Rust, Python, and Java

See also: - Getting Started With GQL.md - Complete query language reference - sdk-rust/README.md - Full SDK documentation

Uninstall options

Cleanup Script

GraphLite includes a comprehensive cleanup script to uninstall and remove all project artifacts:

# Show help (also shown when no options provided)
./scripts/cleanup.sh --help

# Clean build artifacts only
./scripts/cleanup.sh --build

# Clean Python/Java bindings
./scripts/cleanup.sh --bindings

# Complete cleanup (bindings, build artifacts, data, config)
./scripts/cleanup.sh --all

What gets cleaned: - --build: Rust build artifacts, compiled binaries, Cargo.lock - --bindings: Python packages, Java artifacts, compiled libraries - --all: Everything above plus database files, configuration, logs

License and Resources

License

GraphLite is licensed under the Apache License 2.0.

Documentation

GraphLite provides comprehensive documentation for all skill levels:

Getting Started: - Quick Start.md - Get running in 5 minutes - Getting Started With GQL.md - Complete query language reference

Development (to be updated) : - "Testing Guide.md" - Comprehensive testing documentation - "Configuration Guide.md" - Advanced configuration and deployment - "Contribution Guide.md" - How to contribute

Code Examples: - SDK Examples - High-level API examples (recommended) - Examples - SDK (high-level) and bindings (low-level) examples for Rust, Python, and Java

Legal: - LICENSE - Apache License 2.0 full text - NOTICE - Third-party attributions

Questions?

• Open an issue for bugs or feature requests
• Check existing issues before creating new ones
• Join discussions in open issues and PRs
• **[Join our Discord