Quarkus Reference

This section documents Quarkus 3.39.x (current) with 3.33.x LTS as the production recommendation, on the Java 17+ baseline, as published at the official Quarkus guides — which are the reference these pages are written and verified against.

Quarkus 4 raises the baseline to Java 21 (first release candidate planned for end of September 2026, see the Quarkus blog); readers upgrading past 3.39.x/3.33.x LTS should expect that change.

This content was generated with the assistance of AI and should be verified against those official guides before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

Welcome to the Quarkus reference. Quarkus is a Kubernetes-native Java framework built for GraalVM and the JVM alike: it moves as much work as possible — classpath scanning, bean discovery, proxy generation, configuration metadata — from application startup into an augmentation build step, so the resulting application starts in milliseconds, uses a fraction of the memory of a traditionally-bootstrapped Java application, and compiles cleanly to a native executable. That trade — accepting a closed-world assumption about what the application will do at runtime, in exchange for build-time speed and density — is the thread that runs through every page in this section.

If you are new to Quarkus, read Getting Started with Quarkus first, then Build-Time Augmentation and the Closed World to understand why it behaves the way it does, then CDI and the Programming Model (ArC) and Configuration for the two mechanisms every other page assumes. From there, read the rest of this section as needed for the technology you are integrating.

Quarkus sits alongside, not in place of, several existing references in this repository. For the Java framework most directly comparable to it, see the sibling SpringBoot Reference — Quarkus vs. Spring Boot maps the two concept-for-concept and Spring API Compatibility Extensions covers migrating existing Spring code, while Java or Kotlin for Quarkus? mirrors the SpringBoot section’s own language comparison. Quarkus does not re-document the technologies it integrates: for JPA/Hibernate fundamentals see the Hibernate Reference (Quarkus’s own pages cover only what Hibernate ORM in Quarkus and Panache add on top); for GraphQL schema design, pagination, security and federation see the GraphQL Reference (Quarkus adds only the SmallRye server and client bindings on GraphQL with SmallRye); and for the OAuth/OIDC protocols themselves — flows, tokens, JWTs, the Security BCP — see the OAuth Reference (Quarkus adds only the quarkus-oidc/quarkus-smallrye-jwt bindings on JWT, OIDC and Keycloak).

What’s covered

Foundations

REST, web and APIs

  • Quarkus REST — resources and parameter annotations, the @Blocking/non-blocking dispatch decision, exception mapping, CORS/HTTP configuration, and migrating from RESTEasy Classic.

  • The MicroProfile REST Client — typed client interfaces, headers and propagation, exception mapping, TLS, and composing with fault tolerance and Stork.

  • OpenAPI and Swagger UI — SmallRye OpenAPI generation, /q/openapi and /q/swagger-ui, and code-first vs. contract-first development.

  • GraphQL with SmallRye — the SmallRye GraphQL server (@GraphQLApi, @Query, @Mutation, @Subscription) and clients, linking the GraphQL reference for everything else.

  • gRPC — protobuf-first code generation, blocking/Mutiny/virtual-thread service implementations, streaming, and interceptors.

  • WebSockets Next — connection and broadcast APIs, security integration, back-pressure, and the legacy Undertow-based extension.

  • Qute Templating — syntax, type-safe templates with @CheckedTemplate, i18n, and the adjacent Quinoa/Renarde extensions.

  • Reactive Routes and the Vert.x HTTP Layer — reactive routes, direct Vert.x API access and the event bus, and the HTTP/management interface split.

Data

  • Datasources and Transactions — JDBC and reactive datasources, Agroal connection-pool tuning, Narayana JTA transactions, and XA/LRA.

  • Hibernate ORM in Quarkus — the no-persistence.xml configuration model, entity discovery, second-level caching, and build-time metamodel generation.

  • Panache: The Quarkus Data API — active record vs. repository, simplified queries, pagination and sorting, and REST Data with Panache.

  • Reactive Data Access — reactive SQL clients, Hibernate Reactive (including with Panache), and the rule against mixing blocking calls into a reactive path.

  • NoSQL and Other Stores — MongoDB, Redis, Elasticsearch/ OpenSearch, Infinispan, Cassandra, and a survey of Quarkiverse-hosted stores.

  • Database Migrations — Flyway and Liquibase, and migration strategy in a rolling Kubernetes deploy.

  • The Quarkus Cache Extension — the @CacheResult annotation family, the Caffeine/Redis/Infinispan backends, and cache-stampede/invalidation caveats.

  • Validation with Hibernate Validator — constraints on REST payloads and CDI beans, custom constraints, and native-image considerations.

Reactive, concurrency and messaging

Security

Observability and resilience

Testing

  • Testing Quarkus Applications — @QuarkusTest and mocking, @QuarkusComponentTest/@QuarkusIntegrationTest, continuous testing, and testing secured endpoints.

Packaging, native images and deployment

Advanced

Comparison

  • Quarkus vs. Spring Boot — a concept-and-annotation mapping table, an architecture/startup/ecosystem comparison, and a decision guide with no benchmark figures.

Reference

  • Quarkus Cheat Sheet — a one-page, printable summary of the whole section, with a downloadable PDF.

Bibliography

Wherever either book and the official Quarkus guides disagree — or wherever a book is silent on something introduced after its own target version — the official guides are authoritative. Neither book’s benchmark or footprint figures may be quoted anywhere in this section; both books are cited and linked here only and are never attached, uploaded or excerpted.