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.

# 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

# 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

# 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: Clone and Build

# 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.

# 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

If you prefer to build manually without the script:

1. Build in release mode for production-use:

   cargo build --release
   

2. Build in debug mode for development:

   cargo build
   

Step 2: Initialize Database

# Create a new database with admin credentials
./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

# Launch the interactive GQL console
./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:

• Quick Start.md - 5-minute tutorial with first queries
• Getting Started With GQL.md - Complete query language 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 185 unit tests and 250+ integration tests.

Note: Tests are configured to run single-threaded by default (via .cargo/config.toml) to avoid database state conflicts.

Quick Testing

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

Comprehensive Testing

# Run all integration tests with organized output and summary
./scripts/run_tests.sh --release

# Include detailed failure analysis for debugging
./scripts/run_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

Aspect	SQLite	GraphLite
Architecture	Embedded, file-based	Embedded, file-based
Server	No daemon required	No daemon required
Setup	Zero configuration	Zero configuration
Deployment	Single binary	Single binary (11 MB)
Storage	Single file	Directory with Sled files

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("CREATE (p: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(
        "CREATE (p: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!)
• Core Library Examples - Advanced low-level usage

See also:

• Getting Started With GQL.md - Complete query language reference
• graphlite-sdk/README.md - Full SDK documentation

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)
• Core Library Examples - Advanced low-level usage

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
• Contribution guidelines (In Progress)

---

Contributing

We welcome contributions! GraphLite is built with transparent AI-assisted development practices and we sincerely appreciate help from the community.

Quick start for Rustaceans:

git clone https://github.com/GraphLite-AI/GraphLite.git
cd GraphLite
cargo build
cargo test

👉 Contribution guide (In Progress) will include complete details on:

• How to contribute
• Development setup
• Testing guidelines
• Code style and quality standards
• AI-assisted development philosophy

Acknowledgements

GraphLite is built on top of excellent open source projects. We are grateful to the maintainers and contributors of these libraries:

Special Recognition

OpenGQL - GraphLite's ISO GQL implementation is based on the grammar and specifications from the OpenGQL project, which provides the open-source reference grammar for the ISO Graph Query Language (GQL) standard. We are deeply grateful to the OpenGQL community and the ISO GQL Working Group for their work in standardizing graph query languages.

Special Thanks

• Rust Community - For creating an amazing ecosystem of high-quality libraries
• All open source contributors whose work makes projects like GraphLite possible

---