Forem: Matthaios Stavrou

Building a Kafka Event-Driven Spring Boot Application with Avro, Schema Registry and PostgreSQL

Matthaios Stavrou — Sun, 04 Jan 2026 21:28:07 +0000

If you’re building event-driven systems with Apache Kafka, you must think about data contracts early.

This post shows a practical, end-to-end Spring Boot example using:

Apache Kafka
Confluent Schema Registry
Avro serialization
PostgreSQL
Docker Compose

👉 Full source code:
🔗 https://github.com/mathias82/kafka-schema-registry-spring-demo

🧠 Why Schema Registry + Avro?

JSON works… until it doesn’t.

Common problems in Kafka-based systems:

breaking consumers when producers change payloads
no schema versioning
unclear data contracts between teams

Avro + Schema Registry solves this by:

enforcing schema compatibility
allowing safe schema evolution
decoupling producers from consumers

This demo shows how to do it the right way with Spring Boot.

🏗️ Architecture Overview
Client (Postman)
|
v
Spring Boot Producer (REST)
|
v
Kafka Topic (users.v1)
|
v
Spring Boot Consumer
|
v
PostgreSQL

Producer exposes POST /users
Payload is converted to an Avro record
Message is published to Kafka
Consumer deserializes Avro and persists data to PostgreSQL

✨ What This Demo Includes

Spring Boot Kafka Producer (Avro)
Spring Boot Kafka Consumer (Avro)
Confluent Schema Registry
PostgreSQL persistence using Spring Data JPA
Schema evolution with backward compatibility
Docker Compose for local development

🐳 Local Setup (Kafka + Schema Registry + PostgreSQL)
Prerequisites

Java 21
Maven
Docker & Docker Compose

Start infrastructure

docker compose up -d

Services started:

Kafka → localhost:29092
Schema Registry → http://localhost:8081
PostgreSQL → localhost:5432

▶️ Run the Applications
Consumer
cd consumer-app
mvn spring-boot:run

Listens to users.v1 and persists messages to PostgreSQL.

Producer
cd producer-app
mvn spring-boot:run

Exposes REST endpoint.

📬 Produce an Event
curl -X POST http://localhost:8080/users \
-H "Content-Type: application/json" \
-d '{
"id": "u-1",
"email": "user@test.com",
"firstName": "John",
"lastName": "Doe",
"isActive": true,
"age": 30
}'

You’ll see:

Avro schema registered (or validated)
Message published to Kafka
Consumer saving the record to PostgreSQL

🔄 Schema Evolution (The Important Part)

Avro allows safe evolution when rules are respected.

Example:

Add a new optional field
Provide a default value
Keep compatibility set to BACKWARD

Schema Registry ensures:

old consumers keep working
new producers don’t break the system

This demo is designed to show real-world schema evolution, not toy examples.

☁️ Confluent Cloud Ready

The project also supports Confluent Cloud via Spring profiles:

SASL/SSL
Schema Registry API keys
use.latest.version=true
auto.register.schemas=false
Perfect for CI/CD pipelines.

🔗 Source Code

👉 GitHub repository:
https://github.com/mathias82/kafka-schema-registry-spring-demo

Includes:

Docker Compose
Avro schemas
Producer & Consumer apps
PostgreSQL setup
Postman collection

🧩 Who Is This For?

Java & Spring Boot developers
Kafka users moving beyond JSON
Teams building event-driven microservices
Anyone learning Schema Registry + Avro

⭐ Final Thoughts

This is a production-style Kafka example, not a hello-world.

If you’re serious about:

schema contracts
backward compatibility
safe evolution
real persistence

then this demo will save you a lot of trial and error.

👉 Star the repo if it helped you
👉 Fork it and adapt it to your own system

🚦 How to Fail Fast on Kafka Schema Registry in Spring Boot (Avoid Production Breaks)

Matthaios Stavrou — Sat, 03 Jan 2026 12:33:10 +0000

If you are using Kafka Schema Registry with Spring Boot and want to avoid runtime failures in production, this guide shows how to implement fail-fast schema validation the right way.
Apache Kafka is the backbone of many modern event-driven architectures. When combined with Spring Boot, it enables scalable, decoupled microservices that communicate through events instead of tight REST dependencies.

However, as Kafka systems grow, one problem appears again and again:

Schema incompatibility reaching production.

A single incompatible change in an Avro or Protobuf schema can silently break consumers, cause deserialization failures, or — even worse — lead to corrupted data flows that are detected days later.

In this article, we’ll explore why Kafka Schema Registry validation must fail fast, how Spring Boot applications often get this wrong, and how to catch schema contract issues before production.

Why Kafka Schema Issues Are So Dangerous

Kafka is schema-agnostic by default. This flexibility is powerful — but also dangerous.

Common real-world problems include:

Producers sending incompatible schemas
Consumers crashing due to deserialization errors
Schema Registry compatibility set correctly, but violations detected only at runtime
CI/CD pipelines that deploy code without validating schema contracts

By the time the issue is detected, production data is already affected.

The Myth: “Schema Registry Will Protect Me”

Many teams believe that using Confluent Schema Registry automatically guarantees safety.

Reality check ❌
Schema Registry enforces compatibility only when schemas are registered — not when your Spring Boot application starts.

That means:

Your app can deploy successfully

Kafka topics can exist
CI pipelines pass
And yet… the first produced message fails at runtime

This is the opposite of what we want.

Fail-Fast Principle for Kafka Schema Contracts

A fail-fast Kafka application must:

Validate schema compatibility on startup
Fail immediately if schema registration is rejected
Block deployment before traffic reaches production
Shift schema validation left into CI/CD

Spring Boot makes this possible — but not out of the box.

*Common Anti-Patterns in Spring Boot Kafka
*
Here are patterns that look fine but hide serious risks:

Relying on auto-registration without validation
Allowing producers to lazily register schemas
Catching and ignoring serialization exceptions
Letting consumers discover incompatibility at runtime

These patterns lead to late failures, operational firefighting, and broken SLAs.

The Correct Approach: Validate Schemas at Startup

The right solution is simple in concept:

If schema registration fails, the application must not start.

This means:

Explicit schema registration
Compatibility checks during application bootstrap
No lazy runtime surprises
Full alignment with DevOps and CI/CD best practices

When implemented correctly, your Spring Boot Kafka service becomes self-defensive.

Why This Matters in Real Production Systems

In real enterprise environments:
Multiple teams evolve schemas independently
Kafka topics are shared across domains
Rolling deployments happen continuously
Backward compatibility mistakes are inevitable

Fail-fast schema validation turns these risks into early, actionable errors instead of production incidents.

Deep Dive: Practical Implementation

The full technical breakdown — including:

Spring Boot startup hooks
Schema Registry compatibility validation
Producer configuration pitfalls
CI/CD integration patterns

is covered step-by-step in the following article 👇

👉 Read the full implementation guide on Medium:
Fail-Fast Kafka Schema Contracts in Spring Boot — Before Production Breaks
https://medium.com/@mstauroy/fail-fast-kafka-schema-contracts-in-spring-boot-before-production-breaks-1b080204b49e

FAQ

Does Kafka Schema Registry validate schemas at application startup?
No. By default, schema compatibility is checked only when schemas are registered at runtime, which can lead to late production failures.

How do you fail fast with Kafka Schema Registry in Spring Boot?
By validating schema registration and compatibility during application startup and failing the application if registration is rejected.

Why do Kafka schema incompatibility issues reach production?
Because most Spring Boot applications rely on lazy schema registration and do not enforce compatibility checks during deployment.

Final Thoughts

Kafka is reliable. Schema Registry is powerful.
But without fail-fast validation, your system is still fragile.

If you are serious about:

Production safety
Contract-driven development
Kafka best practices
Spring Boot reliability

then schema validation must happen before your app ever starts.

Fail fast and sleep better.

Quarkus Multitenant Plugin (Java): Tenant Resolution in 5 Minutes (Header/JWT/Cookie)

Matthaios Stavrou — Tue, 30 Dec 2025 12:57:36 +0000

If you build multi-tenant Quarkus services, you’ve probably repeated the same logic in multiple codebases:

read tenantId from a header (API gateways / service-to-service)
or from a JWT claim (auth-centric flows)
or from a cookie (browser apps)
and then wire it into your persistence strategy (Hibernate ORM multitenancy, datasource routing, etc.)

I built a small Quarkus multitenant plugin/extension that standardizes tenant resolution so every service follows the same contract and you don’t keep re-implementing edge cases.

👉 Full deep-dive (architecture + implementation + publishing to Maven Central):

https://medium.com/@mstauroy/building-a-generic-multitenancy-extension-for-quarkus-from-idea-to-maven-central-7c4045c404a3

What this extension solves (in plain terms)

Tenant resolution is the missing “glue” between the HTTP request and whatever tenant isolation strategy you use downstream.

This extension gives you:

a consistent way to resolve tenantId
configurable strategy: Header / JWT / Cookie
a clean place to validate & normalize tenant ids
a shared runtime API you can extend with your own resolver

It’s intentionally lightweight: it focuses on tenant resolution, not on re-implementing Quarkus security or ORM internals.

When you should use it (and when you shouldn’t)

Use it if:

you have multiple services and you want a single tenant contract
you keep duplicating tenant parsing logic across codebases
you need consistent behavior for “missing tenant” / “invalid tenant”

You may not need it if:

your scenario is purely OIDC multitenancy (tenant-aware auth provider selection) and tenant id never needs to be resolved independently
you already have a centralized gateway that injects tenant id consistently and you never read from JWT/cookie

Quick start (Maven Central)

Add the runtime module you need.




### HTTP runtime

<dependency>
  <groupId>io.github.mathias82</groupId>
  <artifactId>quarkus-multitenancy-http-runtime</artifactId>
  <version>0.1.15</version>
</dependency>

### ORM runtime

<dependency>
  <groupId>io.github.mathias82</groupId>
  <artifactId>quarkus-multitenancy-orm-runtime</artifactId>
  <version>0.1.15</version>
</dependency>

Header strategy
quarkus.multi-tenant.http.enabled=true
quarkus.multi-tenant.http.strategy=header
quarkus.multi-tenant.http.header-name=X-Tenant

Call it:
curl -H "X-Tenant: tenant1" http://localhost:8080/api/users

JWT strategy (tenant inside claims)

quarkus.multi-tenant.http.enabled=true
quarkus.multi-tenant.http.strategy=jwt
# example claim name (adjust to your token)
quarkus.multi-tenant.http.jwt-claim=tenant_id

Cookie strategy (browser clients)

quarkus.multi-tenant.http.enabled=true
quarkus.multi-tenant.http.strategy=cookie
quarkus.multi-tenant.http.cookie-name=tenantId


Demo (run locally)

If you want to see it working end-to-end with multiple datasources, there’s a demo project in the repo.

docker-compose up -d
mvn quarkus:dev

GitHub repo: https://github.com/mathias82/quarkus-multitenancy

Notes & best practices

A few things I learned while building this:

- Decide precedence (Header vs JWT vs Cookie) once and document it.
- Validate tenant ids (empty/length/pattern) to avoid weird bugs and security issues.
- Make “missing tenant” behavior consistent across services (400 vs 401 vs default tenant).

Read the full article

If you want the full breakdown (idea → extension modules → design choices → Maven Central publishing), the complete write-up is on Medium:

https://medium.com/@mstauroy/building-a-generic-multitenancy-extension-for-quarkus-from-idea-to-maven-central-7c4045c404a3

If you’re using tenant resolution in Quarkus today, I’d love to hear what works best for you (header vs JWT vs cookie) and what constraints you have.