Quick Start Guide

Requirements

To use Graphitron, you'll need:

• Java 17 or higher
• jOOQ
  • The open source edition works with newer versions of open source databases, like PostgreSQL, MySQL and MariaDB
  • For commercial databases or older open source database versions, a commercial jOOQ license is required
  • See the jOOQ website for supported databases
• Maven (Graphitron runs as a Maven plugin)

Getting Started

1. Generate jOOQ classes:
   • Use the jOOQ code generator to generate Java classes from your database schema. This is required for Graphitron to work.

Sample jOOQ code generator configuration for your pom.xml, assuming you are using PostgreSQL

<plugin>
    <groupId>org.jooq</groupId>
    <artifactId>jooq-codegen-maven</artifactId>
    <executions>
        <execution>
            <id>jooq-code-generator</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <jdbc>
                    <driver>org.postgresql.Driver</driver>
                    <url>${db.url}</url>
                    <user>${db.username}</user>
                    <password>${db.password}</password>
                </jdbc>
                <generator>
                    <database>
                        <inputSchema>public</inputSchema>
                    </database>
                    <target>
                        <packageName>${generatedJooqPackage}</packageName>
                        <directory>target/generated-sources/jooq</directory>
                    </target>
                </generator>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>${version.postgresql}</version>
        </dependency>
    </dependencies>
</plugin>

---

2. Write your GraphQL schema:
   • Create one or more GraphQL schema files (e.g., schema.graphqls) and define your GraphQL types, queries, and mutations.
   • Use Graphitron GraphQL directives to specify how the schema maps to your database model.

Sample GraphQL schema with Graphitron directives. This schema is based on the Sakila database

type Query {
    customers: [Customer]
}

type Customer @table {
    id: ID
    firstName: String! @field(name: "FIRST_NAME")
    lastName: String! @field(name: "LAST_NAME")
    email: String
    address: Address!
}

type Address @table {
    id: ID
    addressLine1: String! @field(name: "ADDRESS_")
    addressLine2: String @field(name: "ADDRESS2")
    zip: String @field(name: "POSTAL_CODE")
    phone: String!
}

---

3. Configure graphitron-maven-plugin:
   • Add the graphitron-maven-plugin to your pom.xml file and configure it to use your GraphQL schema files.

Sample configuration for the graphitron-maven-plugin in your pom.xml

<plugin>
    <groupId>no.sikt</groupId>
    <artifactId>graphitron-maven-plugin</artifactId>
    <version>${versions.graphitron}</version>
    <configuration>
        <schemaFiles>
            <schemaFile>${project.basedir}/schema.graphql</schemaFile>
        </schemaFiles>
        <jooqGeneratedPackage>${generatedJooqPackage}</jooqGeneratedPackage>
        <outputPackage>${generatedGraphitronPackage}</outputPackage>
    </configuration>
    <executions>
        <execution>
            <id>generate-with-graphitron</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

---

Maven Build Process Requirements

Graphitron requires:

1. jOOQ classes must be generated and compiled first
2. Graphitron needs the jOOQ classes to be available during its own code generation phase

Recommended approach: Use two separate Maven modules:

• One module for jOOQ code generation
• A dependent module for Graphitron code generation

While possible to configure both in one module with multiple compilation phases, a multi-module approach is cleaner and simpler.

Next Steps

After setting up Graphitron:

1. Run your Maven build to generate the GraphQL resolvers
2. Integrate with your GraphQL server
   • Graphitron includes a maven module for Quarkus that you can use to run a GraphQL server with the generated resolvers.
   • Alternatively, you can integrate the generated resolvers into your existing graphql-java based GraphQL server

Fully Working Example Project

See Graphitron example for a working demonstration of how to use Graphitron to generate GraphQL resolvers from a given GraphQL schema. This example is based on the Sakila test database and also includes a Quarkus based GraphQL server that runs the generated resolvers.