Skip to content
BranchesTags

Repository files navigation

SharpGraph - GraphQL-Native Database for .NET

⚠️UNDER HEAVY CONSTRUCTION⚠️
This project is currently undergoing major development and refactoring. Features, APIs, and documentation may change rapidly. Please check back regularly for updates.

.NET 9.0License: MITStatus: PrototypeVibe CodedTests

A high-performance, embedded, GraphQL-native database engine written in C# for .NET 9+. Define your database schema in GraphQL SDL, load data from JSON files, and query with native GraphQL - all without writing any C# table definition code.

** Prototype Status**: This is an experimental database engine. While it has comprehensive features and passes all tests, it's not yet ready for production use. Use for research, prototyping, and educational purposes.

Table of Contents

Documentation

Quick Start

# schema.graphqltypeUser {
id: ID!name: String!email: String!posts: [Post]
}
typePost {
id: ID!title: String!content: String!author: User
}
usingSharpGraph.Core;usingSharpGraph.Core.GraphQL;vardbPath="my_database";varexecutor=newGraphQLExecutor(dbPath);varloader=newSchemaLoader(dbPath,executor);// Load schema and dataloader.LoadSchemaFromFile("schema.graphql");loader.LoadData(File.ReadAllText("data.json"));// Query with relationshipsvarresult=executor.Execute(@"{ users { name posts { title } }}");

Prisma-Style Filtering & Sorting

SharpGraph supports Prisma-style filtering and sorting through Connection types. This provides an intuitive, GraphQL-native way to query and sort data.

Filtering with where

Filter records using field-level conditions:

querySearchCharacters {
characters {
items(where: {name: {contains: "Luke"}}) {
idnamecharacterType
}
}
}

Available filter operators:

  • equals: Exact match
  • contains: String contains (case-insensitive)
  • startsWith: String starts with
  • endsWith: String ends with
  • gt: Greater than (for numbers)
  • lt: Less than (for numbers)
  • gte: Greater than or equal
  • lte: Less than or equal

Combined filters with AND/OR/NOT:

queryFindHumans {
characters {
items(where: {
AND: [
{characterType: {equals: "Human"}}
{name: {contains: "Solo"}}
]
}) {
idnamecharacterType
}
}
}

Sorting with orderBy (Prisma-style)

Sort by one or multiple fields using Prisma's intuitive syntax:

querySortedCharacters {
characters {
items(orderBy: [{name: asc}]) {
idnamecharacterType
}
}
}

Multiple sort fields (applied in order):

queryMultiSortCharacters {
characters {
items(orderBy: [{characterType: asc}, {name: asc}]) {
idnamecharacterTypeheight
}
}
}

Pagination with skip and take

Paginate through results:

queryPaginatedCharacters {
characters {
items(skip: 0, take: 10) {
idnamecharacterType
}
}
}

Combined: Filter, Sort, and Paginate

queryAdvancedQuery {
characters {
items(
where: {characterType: {equals: "Human"}}
orderBy: [{name: asc}]
skip: 0take: 5
) {
idnamecharacterTypeheightmass
}
}
}

Auto-Generated CRUD Mutations

SharpGraph automatically generates Create, Update, and Delete mutations for every entity in your schema. No configuration needed!

Create Mutation

mutationCreateCharacter {
createCharacter(input: {
name: "Luke Skywalker"characterType: "Human"appearsIn: ["NEWHOPE", "EMPIRE", "JEDI"]
height: 172.72mass: 77.0hairColor: "Blond"skinColor: "Fair"eyeColor: "Blue"birthYear: "19BBY"homePlanetId: "tatooine"
}) {
idnamecharacterType
}
}

Update Mutation

mutationUpdateCharacter {
updateCharacter(
id: "luke"input: {
name: "Luke Skywalker (Updated)"height: 173.0
}
) {
idnameheight
}
}

Delete Mutation

mutationDeleteCharacter {
deleteCharacter(id: "luke")
}

Bulk Operations Example

mutationCreateMultiple {
c1: createCharacter(input: {
name: "Character 1"characterType: "Human"
}) {
idname
}
c2: createCharacter(input: {
name: "Character 2"characterType: "Droid"
}) {
idname
}
}

Complete CRUD Example

# Createmutation {
createFilm(input: {
title: "A New Hope"episodeId: 4openingCrawl: "It is a period of civil war..."director: "George Lucas"producer: "Gary Kurtz"releaseDate: "1977-05-25"
}) {
idtitle
}
}
# Read with Filteringquery {
films {
items(where: {title: {contains: "Hope"}}) {
idtitleepisodeId
}
}
}
# Updatemutation {
updateFilm(id: "1", input: {
title: "Star Wars: Episode IV - A New Hope"
}) {
idtitle
}
}
# Deletemutation {
deleteFilm(id: "1")
}

Key Features

  • ** Schema-Driven**: Define your database with GraphQL SDL - no C# classes needed
  • ** High Performance**: Hash indexes (O(1)), B-tree indexes (O(log n)), LRU page cache
  • ** Relationships**: Automatic foreign key resolution with batch loading (N+1 prevention)
  • ** Embedded Database**: No separate server process required
  • ** Page-Based Storage**: 4KB pages with MessagePack serialization
  • ** Full GraphQL Support**: Queries, mutations, introspection, fragments
  • ** Zero Boilerplate**: Automatic table creation from schema types

Documentation

Getting Started

Core Concepts

  • Features - Schema-driven development, GraphQL support, storage engine
  • Architecture - System design, components, and data flow
  • Storage System - Page-based storage, MemTable, file format
  • Indexing - Hash indexes, B-tree indexes, performance impact
  • Relationships - Foreign keys, relationship types, query resolution

Performance & Configuration

  • Performance - Benchmarks, tuning, optimization tips
  • Configuration - Database options, server settings, performance tuning

Reference

Architecture Overview

SharpGraph is built as a layered architecture:

graph TB
subgraph "GraphQL Layer"
A[Lexer] --> B[Parser]
B --> C[Executor]
end
subgraph "Schema Layer"
D[Schema Parser] --> E[Schema Loader]
end
subgraph "Indexing Layer"
F[Hash Index] --> G[B-Tree Index]
G --> H[Index Manager]
end
subgraph "Storage Layer"
I[Table] --> J[MemTable]
J --> K[Page Cache]
K --> L[FileManager]
end
C --> E
E --> H
H --> I
Loading

For detailed architecture documentation, see ARCHITECTURE.md.

Performance

BenchmarkAverage TimeThroughput
Single record lookup (Hash Index)0.40ms2,500 ops/sec
Range queries (B-Tree)0.15ms6,667 ops/sec
Relationship queries1.86ms537 ops/sec
Full table scans0.74ms1,351 ops/sec

Test environment: Windows 11, .NET 9.0, Star Wars dataset (8 characters, 3 films, 4 planets)

See Performance Guide for detailed benchmarks and tuning options.

SharpGraph IDE

SharpGraph includes a comprehensive web-based administration interface built with Blazor and AdminLTE. The IDE provides a modern, intuitive interface for managing your GraphQL database.

Features

  • Dashboard: Real-time performance metrics, database statistics, and system status
  • GraphQL Playground: Interactive query editor with syntax highlighting and auto-completion
  • Table Management: Browse, search, and edit table data with pagination
  • Schema Viewer: Visualize and manage GraphQL schema definitions
  • Performance Monitoring: Query performance metrics, cache statistics, and alerts
  • Data Import/Export: JSON import and export functionality
  • Index Management: Create and monitor database indexes

Quick Start

# Run the IDEcd src/SharpGraph.Ide
dotnet run
# Open your browser to
https://localhost:5051

Screenshots

The IDE features a modern AdminLTE-based interface with:

  • Responsive sidebar navigation
  • Real-time performance dashboards
  • Interactive GraphQL query playground
  • Comprehensive table and data management

Installation

# Clone the repository
git clone https://github.com/your-org/sharpgraph.git
cd sharpgraph
# Build the solution
dotnet build --configuration Release
# Run tests
dotnet test# Run examplescd examples/StarWars
dotnet run
# Run the IDEcd src/SharpGraph.Ide
dotnet run
# Then open https://localhost:5051

Requirements:

  • .NET 9.0 or later
  • Windows, macOS, or Linux
  • Visual Studio 2022 or VS Code (recommended)

Use Cases

  • Prototyping: Rapid GraphQL API development
  • Embedded Applications: Desktop apps, local-first software
  • Testing: Mock GraphQL backends for testing
  • Education: Learning GraphQL and database internals
  • Research: Experimenting with database architectures

Example: Star Wars Database

cd examples/StarWars
dotnet run

Query example:

{
character(id: "luke") {
nameheightfriends {
name
}
homePlanet {
nameclimate
}
}
}

See Examples for more use cases including Blog, E-Commerce, and Social Network schemas.

Contributing

Contributions are welcome! Please see Development Guide for:

  • Building from source
  • Running tests
  • Code standards
  • Pull request process

License

MIT License - see LICENSE file for details.

Credits

  • GraphQL specification from GraphQL.org
  • Star Wars example based on official GraphQL tutorial
  • Inspired by modern database architectures (PostgreSQL, SQLite, RocksDB)

** SharpGraph - Where GraphQL meets high-performance storage!**

Built with for the .NET community

About

A high-performance, embedded, GraphQL-native database engine written in C# for .NET 9+. Define your database schema in GraphQL SDL, load data from JSON files, and query with native GraphQL - all without writing any C# table definition code.

Topics

databasegraphqlgraphql-apigraphql-enginegraphql-server

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages