Excalibase GraphQL¶

Automatic GraphQL API generation from PostgreSQL database schemas

Transform your PostgreSQL database into a powerful GraphQL API in minutes

Overview¶

Excalibase GraphQL is a Spring Boot application that automatically generates a complete GraphQL API from your existing PostgreSQL database. Simply point it at your database and get instant GraphQL queries and mutations with built-in pagination, filtering, and relationship resolution.

🚀 Zero Configuration

Auto-generates GraphQL schema from your database structure. No manual type definitions needed.

🔍 Advanced Filtering

Modern object-based filtering with 15+ operators. Supports complex nested conditions and type safety.

⚡ High Performance

Optimized for production with sub-1s response times and built-in N+1 query prevention.

🛡️ Security First

Comprehensive security testing with SQL injection prevention and input validation.

📈 Production Ready

Docker support, CI/CD integration, and extensive test coverage for enterprise deployment.

🔗 Relationship Magic

Foreign keys automatically become GraphQL relationships. Supports one-to-one, one-to-many, and many-to-many.

Quick Start¶

📦 Install

Get started with Docker in under 2 minutes.

git clone https://github.com/excalibase/excalibase-graphql.git
cd excalibase-graphql

⚙️ Configure

Set your database connection details.

export DB_HOST=localhost
export DB_NAME=your_database
export DB_USERNAME=postgres
export DB_PASSWORD=your_password

🚀 Launch

Start the GraphQL API server.

docker-compose up -d

🎯 Query

Access your GraphQL endpoint.

http://localhost:10000/graphql

Prerequisites¶

Java 21+ - Required for running the application
PostgreSQL 15+ - Supported database version
Docker - Recommended for easy deployment
Maven 3.8+ - For local development builds

Option 2: Local Development¶

Clone the repository:

git clone https://github.com/excalibase/excalibase-graphql.git
cd excalibase-graphql

Configure your database in src/main/resources/application.yaml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/your_database
    username: your_username
    password: your_password

app:
  allowed-schema: public  # Your database schema
  database-type: postgres

Build and run:
```
mvn clean compile
mvn spring-boot:run
```
Access GraphQL endpoint:
```
http://localhost:10000/graphql
```

Example Usage¶

Given this database schema:

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    title VARCHAR(200) NOT NULL,
    content TEXT,
    author_id INTEGER REFERENCES users(id)
);

You can immediately query:

# Get all users
{
  users {
    id
    name
    email
    created_at
  }
}

# Get posts with authors (automatic relationship resolution)
{
  posts {
    id
    title
    content
    users {  # Foreign key relationship automatically resolved
      name
      email
    }
  }
}

# Filtered query with pagination
{
  users(
    name_contains: "john"
    limit: 10
    orderBy: { created_at: DESC }
  ) {
    id
    name
    email
  }
}

And perform mutations:

# Create a new user
mutation {
  createUsers(input: {
    name: "Alice Johnson"
    email: "alice@example.com"
  }) {
    id
    name
    email
    created_at
  }
}

# Update existing user
mutation {
  updateUsers(input: {
    id: 1
    name: "Alice Smith"
  }) {
    id
    name
    email
  }
}

# Delete user
mutation {
  deleteUsers(id: 1)
}

Key Features¶

✅ Currently Available¶

🎯 Advanced Filtering

Modern object-based filtering with 41+ tests and 15+ operators including string matching, numeric comparisons, and date ranges.

⚡ High Performance

Optimized for large datasets with sub-1s response times, N+1 query prevention, and intelligent batching.

🛡️ Security Tested

Comprehensive security testing with 13+ security tests covering SQL injection prevention and input validation.

📊 Performance Tested

6+ performance tests ensuring scalability with 1000+ records and 20+ concurrent requests.

🔗 Smart Relationships

Foreign keys automatically become GraphQL relationships with support for one-to-one, one-to-many, and many-to-many patterns.

🐳 Production Ready

Docker support, CI/CD integration, and comprehensive test coverage for enterprise deployment.

🚧 In Development¶

Authentication & Authorization - Role-based access control
Multi-Database Support - MySQL, Oracle, SQL Server
GraphQL Subscriptions - Real-time data updates
Schema Caching - Improved performance for large schemas

🌟 Enhanced Filtering System¶

Excalibase GraphQL now features a modern, object-based filtering system that provides consistency with industry standards:

Modern Object-Based Syntax¶

New Syntax (Recommended):

{
  customer(where: { customer_id: { eq: 524 } }) {
    customer_id
    first_name
    last_name
  }
}

Complex Filtering:

{
  users(
    where: { 
      name: { startsWith: "John" },
      age: { gte: 18, lt: 65 },
      active: { eq: true }
    }
  ) { id name age }
}

OR Operations:

{
  users(or: [
    { name: { eq: "Alice" } },
    { email: { endsWith: "@admin.com" } }
  ]) { id name email }
}

Available Filter Operations¶

All Data Types: - eq, neq, isNull, isNotNull, in, notIn

String Operations: - contains, startsWith, endsWith, like, ilike

Numeric Operations: - gt, gte, lt, lte

Date/Time Operations: - Supports multiple formats: "2023-12-25", "2023-12-25 14:30:00", ISO 8601

Legacy Support¶

The old syntax continues to work for backward compatibility:

{
  users(
    name_contains: "john"      # Legacy syntax
    name_startsWith: "John"    # Still supported
    email_isNotNull: true
  ) { id name }
}

📚 Comprehensive Documentation¶

Complete Filtering Guide - All operations, examples, and migration guides
Test Coverage Documentation - 41+ comprehensive test methods
Security: SQL injection prevention with comprehensive security testing
Performance: Optimized for large datasets (1000+ records) with sub-1s response times

Pagination Options¶

Offset-based pagination:

{
  users(limit: 20, offset: 40, orderBy: { id: ASC }) {
    id
    name
    email
  }
}

Cursor-based pagination (Relay specification):

href="#__codelineno-16-1">{ usersConnection(first: 20, after: "cursor123", orderBy: { id: ASC }) { edges { node { id name email } cursor } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } totalCount } }

Configuration¶

Basic Configuration¶

# Database connection
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: ${DB_USERNAME:myuser}
    password: ${DB_PASSWORD:mypass}

# Schema settings  
app:
  allowed-schema: ${DATABASE_SCHEMA:public}
  database-type: postgres

# Server settings
server:
  port: ${SERVER_PORT:10000}

Development Configuration¶

# Enable debug logging
logging:
  level:
    io.github.excalibase: DEBUG
    org.springframework.jdbc.core: DEBUG  # Show SQL queries

# Use virtual threads (Java 21+)
spring:
  threads:
    virtual:
      enabled: true

Architecture¶

The project follows a modular, database-agnostic design:

At Startup (Schema Generation & Wiring):

                    ServiceLookup ───► Database-specific implementations
                         │
                         ▼
                   GraphqlConfig
                    │   │   │
       ┌────────────┘   │   └─────────────┐
       ▼                ▼                 ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Database   │  │   Schema    │  │   Data      │
│  Reflector  │  │  Generator  │  │  Fetchers   │
└─────────────┘  └─────────────┘  └─────────────┘
       │                ▼                 │
       │         ┌─────────────┐          │
       │         │  GraphQL    │          │
       └────────▶│   Schema    │◄─────────┘
                 └─────────────┘
                       │
                       ▼
              ┌─────────────┐
              │  Mutators   │
              │(Mutations)  │
              └─────────────┘

At Runtime (Request Processing):

HTTP Request ───► GraphQL Controller ───► GraphQL Engine ───► Data Fetchers/Mutators ───► Database

Key Components: - Schema Reflector: Introspects PostgreSQL metadata (startup only) - Schema Generator: Creates GraphQL types from database tables (startup only) - Data Fetchers: Handle query resolution with optimizations (runtime) - Mutators: Process CRUD operations (runtime) - Service Lookup: Enables database-specific implementations - GraphqlConfig: Central orchestrator that wires data fetchers and mutators to specific GraphQL fields for each table

Testing¶

Run the test suite (uses Testcontainers for real PostgreSQL testing):

# Run all tests
mvn test

# Run with coverage report
mvn clean test jacoco:report

# Run specific test class
mvn test -Dtest=PostgresDatabaseDataFetcherImplementTest

Current Limitations¶

PostgreSQL only: MySQL, Oracle, SQL Server support planned
No authentication: Built-in auth/authz coming soon
Docker available: Use docker-compose up -d for easy setup
Basic error handling: Some edge cases need improvement
Performance: Not yet optimized for very large schemas

Project Status¶

This project is in active early development. Core functionality works well, but many enterprise features are still being built.

What works well: - PostgreSQL schema introspection - GraphQL schema generation - Basic queries and mutations - Relationship resolution - Pagination and filtering

What's coming soon: - Docker support - Authentication & authorization - Additional database support - CI/CD pipeline - Performance optimizations

Contributing¶

This is currently a solo project, but contributions are welcome!

Check the issues for open tasks
Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

Getting Help¶

GitHub Issues: Bug reports and feature requests
GitHub Discussions: Questions and general discussion

License¶

Apache License 2.0 - see LICENSE for details.

⭐ Star the project on GitHub if you find it useful!Test edit: Sat Jul 12 23:50:29 +07 2025