Quick Start Guide - Excalibase GraphQL¶

This guide helps you quickly get started with Excalibase GraphQL using Docker Compose.

Prerequisites¶

Docker and Docker Compose installed on your system
The excalibase/excalibase-graphql Docker image available locally or in a registry

Quick Start¶

Clone the repository and navigate to the project directory:
```
git clone <repository-url>
cd excalibase-graphql
```
Start the services:
```
docker-compose up -d
```
Check the status:
```
docker-compose ps
```
Access the application:
GraphQL API: http://localhost:10000
Database: localhost:5432 (if you need direct access)

What's Included¶

The Docker Compose setup provides a complete environment with:

PostgreSQL Database¶

Image: postgres:15-alpine
Container: excalibase-postgres
Port: 5432
Database: hana
User: hana001
Password: password123
Schema: hana

The database is automatically initialized with sample data including: - Users table with sample users - Posts table with sample blog posts - Comments table with sample comments - Proper indexes and foreign key relationships

Excalibase GraphQL Application¶

Image: excalibase/excalibase-graphql
Container: excalibase-graphql
Port: 10000
Health Check: Available at /actuator/health

Common Commands¶

Start services¶

docker-compose up -d

Stop services¶

docker-compose down

View logs¶

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f excalibase-app
docker-compose logs -f postgres

Restart a service¶

docker-compose restart excalibase-app

Connect to PostgreSQL¶

docker-compose exec postgres psql -U hana001 -d hana

Reset everything (including data)¶

docker-compose down -v
docker-compose up -d

Sample GraphQL Queries¶

Once the application is running at http://localhost:10000, you can try these sample queries:

Get all users¶

query {
  users {
    id
    username
    email
    firstName
    lastName
  }
}

Get posts with authors¶

query {
  posts {
    id
    title
    content
    published
    author {
      username
      email
    }
  }
}

Get comments with post and author details¶

query {
  comments {
    id
    content
    post {
      title
    }
    author {
      username
    }
  }
}

Composite Key Operations¶

The sample database includes tables with composite keys. Try these queries:

Query order items with composite primary keys:

query {
  order_items {
    order_id
    product_id
    quantity
    price
  }
}

Create order item with composite key:

mutation {
  createOrder_items(input: {
    order_id: 3
    product_id: 2
    quantity: 5
    price: 199.99
  }) {
    order_id
    product_id
    quantity
    price
  }
}

Update order item using composite key:

mutation {
  updateOrder_items(input: {
    order_id: 3          # Required: part of composite PK
    product_id: 2        # Required: part of composite PK
    quantity: 10         # Updated field
    price: 299.99        # Updated field
  }) {
    order_id
    product_id
    quantity
    price
  }
}

Delete order item with composite key:

mutation {
  deleteOrder_items(input: {
    order_id: 3
    product_id: 2
  }) {
    order_id
    product_id
    quantity
    price
  }
}

Filter by composite key:

query {
  order_items(where: {
    order_id: { eq: 1 }
    product_id: { eq: 2 }
  }) {
    order_id
    product_id
    quantity
    price
  }
}

Troubleshooting¶

Application won't start¶

Check if the database is healthy:
```
docker-compose ps
```
View application logs:
```
docker-compose logs excalibase-app
```

Database connection issues¶

Ensure the PostgreSQL service is running and healthy
Check if the database initialization completed successfully:
```
docker-compose logs postgres
```

Port conflicts¶

If you get port conflicts, you can modify the ports in docker-compose.yml:

ports:
  - "YOUR_PORT:10000"  # Change YOUR_PORT to an available port

Next Steps¶

Explore the GraphQL schema at http://localhost:10000/graphql
Check out the API Documentation for more details
See Contributing Guidelines if you want to contribute

Configuration¶

The application uses these default settings: - Database: PostgreSQL with hana schema - Application port: 10000 - Database port: 5432 - Default credentials: hana001/password123 - CDC enabled by default for real-time subscriptions

To customize these settings, edit the environment variables in docker-compose.yml:

Key CDC Configuration Options: - APP_CDC_ENABLED=true - Enable/disable real-time subscriptions - APP_CDC_CREATE_SLOT_IF_NOT_EXISTS=true - Auto-create PostgreSQL replication slot - APP_CDC_CREATE_PUBLICATION_IF_NOT_EXISTS=true - Auto-create publication