This page is a high-level orientation. If you want to type commands yourself and see real responses, the Tutorial takes a fresh checkout to a working query against the Sakila example. For the rewrite-side workflow with worked examples (custom scalars, Apollo Federation, the dev loop), see Getting Started.

Requirements

  • Java 17 or higher (consumers of Graphitron’s generated output run on Java 17; the generator itself runs on Java 25).

  • jOOQ. The open-source edition covers PostgreSQL, MySQL, MariaDB, SQLite, and others. Commercial databases require a commercial jOOQ licence. See the jOOQ database matrix.

  • Maven. Graphitron runs as a Maven plugin.

Outline

  1. Generate jOOQ classes from your database schema. Use the jOOQ code generator to produce typed table/record classes. Graphitron consumes them.

  2. Write your GraphQL schema with Graphitron directives. Annotate types and fields to declare how they map to tables and columns. The directive reference lives at Reference: directives.

  3. Configure the Graphitron Maven plugin. Wire it into your pom.xml so it runs after jOOQ codegen and before your application code compiles.

  4. Build. The generated resolvers land alongside your code, ready to be wired into your GraphQL server.

Sample directive-annotated schema

The example project uses the Sakila database. A trimmed view:

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!
}

Maven build shape

Graphitron requires jOOQ classes to exist before it runs, so the generator and its consumers split cleanly into separate Maven modules:

  • One module runs the jOOQ code generator.

  • A dependent module runs Graphitron, with the jOOQ module as a <dependency>.

A single-module setup is possible with multi-phase configuration but ends up fiddlier. Multi-module is the recommended path.

Running the generated code

After the build, you have generated DataFetchers, TypeResolvers, and supporting classes ready to plug into a GraphQL server. Two options:

  • Use the Quarkus integration shipped with Graphitron (see the example project).

  • Wire the generated resolvers into an existing graphql-java application.

Working example

graphitron-sakila-example is a complete working project: Sakila schema, GraphQL schema with directives, generated resolvers, and a Quarkus + JAX-RS server that runs them.

The same module also doubles as the recommended consumer test pattern: the in-process query-to-database tests under src/test/java/…​/querydb/ build the schema via Graphitron.buildSchema(…​), instantiate a GraphQL engine, execute via graphql-java, and assert against a live PostgreSQL DSLContext. Two worked examples (one match-style, one approval-style) are templates you can copy. See the module’s README for which directories to copy and what each role looks like.

Where to next