Skip to content
HeliosDB HeliosDB Full

HeliosDB GraphQL Package - Complete Implementation Summary

HeliosDB GraphQL Package - Complete Implementation Summary

Overview

The heliosdb-graphql package provides a comprehensive GraphQL API layer for HeliosDB v3.0, enabling modern web and mobile applications to interact with the database through a strongly-typed, auto-generated GraphQL schema.

Package Structure

heliosdb-graphql/
├── Cargo.toml                    # Package configuration with all dependencies
├── README.md                     # Comprehensive usage documentation
├── QUICK_REFERENCE.md            # Quick reference guide
├── PACKAGE_SUMMARY.md            # This file
├── src/
│   ├── lib.rs                    # Package entry point with metrics
│   ├── config.rs                 # Server configuration and builder
│   ├── error.rs                  # Error types and Result alias
│   ├── schema.rs                 # Auto-schema generation from SQL tables
│   ├── types.rs                  # SQL to GraphQL type mapping
│   ├── resolver.rs               # Query and mutation resolvers
│   ├── subscriptions.rs          # Real-time subscriptions with CDC
│   ├── server.rs                 # HTTP server with WebSocket support
│   ├── filters.rs                # Filtering, sorting, pagination
│   ├── pagination.rs             # Cursor-based pagination (Relay)
│   ├── auth.rs                   # JWT authentication and RBAC
│   ├── middleware.rs             # Rate limiting, caching, logging
│   ├── introspection.rs          # Schema introspection
│   └── federation.rs             # Apollo Federation support
├── examples/
│   ├── basic_server.rs           # Basic server example
│   └── subscription_example.rs   # Real-time subscription example
└── tests/
    └── integration_test.rs       # Integration tests

Core Components

1. Schema Generation (schema.rs)

Purpose: Automatically generate GraphQL schemas from SQL table metadata.

Key Features:

  • Converts SQL tables to GraphQL object types
  • Generates input types for filtering, sorting, ordering
  • Creates CRUD queries and mutations
  • Generates subscription types for CDC events
  • Handles relationships (foreign keys)

Example:

let mut generator = SchemaGenerator::new();
let schema = generator.generate(tables)?;
let sdl = schema.to_sdl();

2. Type Mapping (types.rs)

Purpose: Map SQL data types to GraphQL types.

Supported Mappings:

  • VARCHAR/TEXT → String
  • INTEGER/SERIAL → Int
  • BIGINT → String (to avoid precision loss)
  • FLOAT/DOUBLE → Float
  • NUMERIC/DECIMAL → Decimal
  • BOOLEAN → Boolean
  • UUID → UUID
  • JSON/JSONB → JSON
  • TIMESTAMP/DATE → DateTime
  • BYTEA/BLOB → Bytes

Extensibility: Custom type mappings can be added for database-specific types.

3. Resolvers (resolver.rs)

Purpose: Execute GraphQL queries and mutations against the database.

Components:

  • QueryResolver: Handles queries (find by ID, list, count)
  • MutationResolver: Handles mutations (create, update, delete)
  • BatchResolver: Optimized batch loading (DataLoader pattern)

SQL Generation: Automatically generates SQL from GraphQL queries with:

  • WHERE clause generation from filters
  • ORDER BY from sorting parameters
  • LIMIT/OFFSET from pagination
  • SQL injection protection

4. Subscriptions (subscriptions.rs)

Purpose: Real-time updates through WebSocket subscriptions.

Features:

  • CDC integration for database change events
  • Event filtering by table and operation type
  • Broadcast channel for efficient multi-subscriber support
  • Automatic subscription cleanup
  • Lag handling for slow consumers

Event Types:

  • Created: New record inserted
  • Updated: Record modified
  • Deleted: Record removed

5. Server (server.rs)

Purpose: HTTP/WebSocket server for GraphQL API.

Features:

  • Axum-based HTTP server
  • WebSocket support for subscriptions
  • GraphQL Playground UI
  • Health check endpoint
  • CORS support
  • Request tracing and logging

Endpoints:

  • POST /graphql - GraphQL queries/mutations
  • GET / - GraphQL Playground (optional)
  • GET /ws - WebSocket for subscriptions
  • GET /health - Health check

6. Filtering (filters.rs)

Purpose: Advanced filtering, sorting, and pagination.

Filter Operations:

  • Comparison: equals, not equals, lt, lte, gt, gte
  • String: contains, starts with, ends with
  • Array: in, not in
  • Null checks: is null, is not null
  • Logical: AND, OR, NOT

SQL Generation: Converts GraphQL filters to SQL WHERE clauses with proper escaping.

7. Pagination (pagination.rs)

Purpose: Support both offset-based and cursor-based pagination.

Features:

  • Offset pagination: skip and take parameters
  • Cursor pagination: Relay-style connections
  • Page info with navigation metadata
  • Base64-encoded cursors
  • Total count (optional)

8. Authentication (auth.rs)

Purpose: Secure API access with JWT and RBAC.

Features:

  • JWT token generation and verification
  • Role-based access control (RBAC)
  • Permission checking
  • Token expiration handling
  • Authorization header parsing

Example:

let claims = Claims::new("user123", vec!["admin"], 3600);
let token = manager.generate_token(claims)?;

9. Middleware (middleware.rs)

Purpose: Request processing and protection.

Components:

  • AuthenticationMiddleware: JWT verification
  • RateLimitMiddleware: Per-IP rate limiting
  • ComplexityAnalyzer: Query complexity limits
  • QueryLogger: Query logging and monitoring
  • CacheMiddleware: LRU cache for results

10. Introspection (introspection.rs)

Purpose: GraphQL schema introspection support.

Features:

  • Type information generation
  • Field metadata
  • Directive information
  • Schema documentation
  • Standard GraphQL introspection queries

11. Federation (federation.rs)

Purpose: Apollo Federation support for microservices.

Features:

  • Entity resolution by representation
  • _entities and _service queries
  • Reference resolvers
  • Federation directives (@key, @extends, etc.)
  • SDL generation with federation support

12. Configuration (config.rs)

Purpose: Server configuration management.

Options:

  • Bind address
  • Playground enable/disable
  • Introspection enable/disable
  • Query depth limits
  • Query complexity limits
  • Subscriptions enable/disable
  • Federation enable/disable
  • Request timeout
  • Rate limiting
  • JWT secret
  • CORS origins
  • Query logging

Builder Pattern:

let config = GraphQLConfigBuilder::new()
    .bind_address("0.0.0.0:8080".parse()?)
    .playground(true)
    .max_depth(10)
    .rate_limit(1000)
    .build();

Dependencies

Core Dependencies

  • async-graphql (7.0): GraphQL framework
  • async-graphql-axum (7.0): Axum integration
  • axum (0.7): HTTP server
  • tokio: Async runtime
  • futures: Async utilities

Internal Dependencies

  • heliosdb-common: Common utilities
  • heliosdb-storage: Storage layer
  • heliosdb-metadata: Schema metadata
  • heliosdb-compute: Query execution
  • heliosdb-cdc: Change data capture

Additional Dependencies

  • serde, serde_json: Serialization
  • jsonwebtoken: JWT authentication
  • governor: Rate limiting
  • inflector: String case conversion
  • tower, tower-http: Middleware
  • tracing: Logging
  • prometheus: Metrics

Key Features

1. Automatic Schema Generation

  • Zero-configuration GraphQL schema from SQL tables
  • Proper type mappings
  • Relationship handling
  • Input type generation

2. CRUD Operations

  • Generated queries for single and list retrieval
  • Generated mutations for create, update, delete
  • Proper error handling
  • Transaction support

3. Advanced Filtering

  • Complex filter conditions
  • Logical operators (AND, OR, NOT)
  • String matching (contains, startsWith, endsWith)
  • Numeric comparisons
  • Null checks

4. Real-time Subscriptions

  • CDC integration
  • WebSocket transport
  • Event filtering
  • Multiple subscribers
  • Automatic cleanup

5. Security

  • JWT authentication
  • Role-based authorization
  • Rate limiting
  • Query complexity limits
  • SQL injection protection

6. Performance

  • Query result caching
  • Batch loading (DataLoader)
  • Connection pooling
  • Efficient subscriptions

7. Developer Experience

  • GraphQL Playground
  • Schema introspection
  • Comprehensive error messages
  • Type safety
  • Auto-completion support

8. Federation

  • Apollo Federation v2 support
  • Entity resolution
  • Service composition
  • Distributed schemas

Usage Examples

Starting a Server

use heliosdb_graphql::{GraphQLServer, GraphQLConfigBuilder};


#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = GraphQLConfigBuilder::new()
        .bind_address("0.0.0.0:8080".parse()?)
        .playground(true)
        .build();


    let server = GraphQLServer::new(config).await?;
    server.run().await?.wait().await?;


    Ok(())
}

Query Example

query {
  users(
    where: {
      AND: [
        { status: { equals: "active" } }
        { email: { contains: "@example.com" } }
      ]
    }
    orderBy: [{ createdAt: DESC }]
    take: 10
  ) {
    id
    name
    email
    createdAt
  }
}

Mutation Example

mutation {
  createUser(data: {
    name: "Alice"
    email: "alice@example.com"
  }) {
    id
    name
    email
  }
}

Subscription Example

subscription {
  userCreated {
    id
    name
    email
  }
}

Testing

The package includes comprehensive tests:

  • Unit tests for each module
  • Integration tests for end-to-end flows
  • Example programs for manual testing

Run tests:

Terminal window
cargo test -p heliosdb-graphql

Run examples:

Terminal window
cargo run -p heliosdb-graphql --example basic_server
cargo run -p heliosdb-graphql --example subscription_example

Metrics

Prometheus metrics are exported:

  • heliosdb_graphql_requests_total: Total GraphQL requests
  • heliosdb_graphql_query_duration_seconds: Query execution time
  • heliosdb_graphql_errors_total: Total errors
  • heliosdb_graphql_subscriptions_active: Active subscriptions

Integration Points

With HeliosDB Core

  1. Metadata: Introspect table schemas for schema generation
  2. Storage: Execute queries through storage layer
  3. Compute: Leverage query optimizer and executor
  4. CDC: Subscribe to database changes for subscriptions
  5. Security: Integrate with database authentication/authorization

With Client Applications

  1. HTTP: Standard GraphQL over HTTP
  2. WebSocket: Subscriptions via WebSocket
  3. Playground: Interactive development tool
  4. SDL Export: Schema definition language export

Performance Considerations

  1. Query Complexity: Limit depth and complexity to prevent abuse
  2. Rate Limiting: Protect against excessive requests
  3. Caching: LRU cache for frequently accessed data
  4. Batch Loading: DataLoader pattern for N+1 query prevention
  5. Connection Pooling: Efficient database connection management
  6. Subscription Backpressure: Handle slow subscribers

Security Best Practices

  1. Enable authentication in production
  2. Configure rate limiting appropriately
  3. Set reasonable query complexity limits
  4. Disable introspection in production (optional)
  5. Use HTTPS/WSS in production
  6. Implement proper authorization checks
  7. Validate and sanitize all inputs

Future Enhancements

  1. Query Caching: Automatic query result caching
  2. Persisted Queries: Support for persisted queries
  3. File Uploads: GraphQL multipart upload support
  4. Deferred Queries: @defer directive support
  5. Streaming: @stream directive support
  6. Custom Scalars: User-defined scalar types
  7. Directives: Custom directive support
  8. Schema Stitching: Combine multiple schemas

Conclusion

The heliosdb-graphql package provides a complete, production-ready GraphQL interface for HeliosDB v3.0. It combines automatic schema generation, real-time subscriptions, and enterprise-grade security features to deliver a modern API layer for database access.

Lines of Code: ~3,000 lines Test Coverage: Comprehensive unit and integration tests Dependencies: All production-ready, well-maintained libraries Status: Complete and ready for use