Page 1: Prerequisites

The example you build against lives at graphitron-rewrite/graphitron-sakila-example/. Everything in this tutorial happens from the repository root unless stated otherwise.

The example reads from a database named rewrite_test on localhost:5432 with postgres / postgres credentials. The DDL and seed data live in graphitron-rewrite/graphitron-sakila-db/src/main/resources/init.sql; load that file into a fresh database and you are done.

With Docker:

The init.sql mount runs once on first start, so the database comes up with customer, address, store, film, and the rest of the Sakila schema already populated.

If you already run PostgreSQL natively: create the database, then load init.sql.

The first build pulls jOOQ, graphql-java, Quarkus, and a few hundred other artifacts; expect a couple of minutes on a warm Maven repository, longer on a cold one. The -Plocal-db profile points the jOOQ code generator at the database you just started instead of spinning up a Testcontainer.

You will see the rewrite’s modules build in order: javapoet, the generator, the Sakila catalog and service modules, the Maven plugin, and finally the example. When it ends with BUILD SUCCESS the example’s generated resolvers, runtime app, and test suite are all in place.

Quarkus boots in a few seconds and prints a banner ending with Listening on: http://0.0.0.0:8080. Leave this terminal running; every subsequent page sends queries to that endpoint from a second terminal.

To verify the server is up, try a tiny query against the schema’s introspection endpoint:

A response of {"data":{"__typename":"Query"}} means the GraphQL engine is wired up and ready.

Three failures account for most newcomer hiccups; if you hit one, the fix is short.

The build fails with Detected JDK …​ is version 21.x.x which is not in the allowed range [25,). The Maven enforcer is reading JAVA_HOME, which inherited a JDK 21 from your shell or a prior session. Install JDK 25 and point JAVA_HOME at it:

On macOS or Windows, install a JDK 25 distribution (Temurin, Liberica, etc.) and set JAVA_HOME accordingly. mvn -version is the verification step; it must report Java 25 before the build will pass.

Quarkus fails to start with "address already in use" or never reaches Listening on: http://0.0.0.0:8080. Port 8080 is taken by another process (a previous run that didn’t shut down, a system service, another local app). Either stop the offender (lsof -i :8080 finds it) or run the example on a different port: mvn quarkus:dev -Dquarkus.http.port=8081. Adjust the localhost:8080 URLs in the rest of this tutorial to match.

The example app starts but every query returns a connection error. Postgres isn’t reachable on localhost:5432. If you used the Docker command above, docker ps should show graphitron-pg; if it isn’t there, the container exited (check docker logs graphitron-pg). If you’re running Postgres natively, confirm psql -U postgres -d rewrite_test -c "SELECT 1" returns 1. The default credentials the example expects are postgres / postgres against database rewrite_test.

The example bundles the GraphiQL playground: an in-browser editor with auto-complete, query history, and a one-click run button against the same /graphql endpoint. Open http://localhost:8080/graphiql/ directly, or visit http://localhost:8080/graphql in a browser and you are redirected there automatically.

Every query and mutation in the rest of this tutorial works in GraphiQL too: paste the GraphQL string (the part inside "query":"…​" in each curl body) into the editor’s left pane and hit run. We show curl in the prose because it copies cleanly into a terminal, but if you prefer a GUI the playground is the ergonomic choice.

How the rewrite organises itself into the generator, the Sakila catalog, the example module, and the Quarkus runtime; how to load the example data into PostgreSQL; how to build and run the example; and how to send queries with either curl or GraphiQL.

Page 2: The starter schema introduces the directives that turn GraphQL types into PostgreSQL queries.