Ask an LLM “When does the nightly settlement batch run at Harbourline Payments?” and one of two things happens.

The polite model says it doesn’t know. The confident model says “Usually around midnight!” with the energy of a student who didn’t read the book but really wants a good mark.

Both are fair, because Harbourline Payments doesn’t exist. I made it up. It’s a fictional company with a fictional engineering handbook: founders, services, deploy rules, on-call pay, and even a famous incident called “the Double Tap”. No model has seen this text during training.

That’s exactly why it’s a good test. If the model answers “02:30 UK time” correctly, it didn’t remember it. It found it. That’s RAG.

In this article we’ll build a small RAG service in Java with Spring Boot, LangChain4j, PostgreSQL with pgvector, and Ollama. No cloud, no API keys, no bill at the end of the month.

The full code is on GitHub: SukachVitally/rag-demo.

What is RAG, in one exam

RAG stands for Retrieval-Augmented Generation. Long name, simple idea.

Think about two exams:

• Closed-book exam. The student answers from memory. This is a normal LLM. It knows a lot, but only what it learned during training. It knows nothing about your company’s wiki, last week’s incident, or your internal rules. If it doesn’t know, it may still try to sound smart.
• Open-book exam. Before answering, the student finds the right pages in the book and reads them. This is RAG.

So RAG doesn’t make the model smarter. It gives the model a cheat sheet for each question: “Here are 5 pieces of text that look relevant. Answer using only these.”

Why not just put the whole handbook into the prompt? For one small file you can. But real knowledge bases have thousands of documents. They don’t fit into the context window, and even when they do, you pay for every token on every question. RAG sends only the few pieces that matter.

The big idea

The whole thing is two flows.

Ingest (once per document):

1. Take the text and split it into small pieces called chunks.
2. Ask an embedding model to turn each chunk into a vector: a long list of numbers.
3. Save each chunk together with its vector in the database.

Ask (every question):

1. Ask the same embedding model to turn the question into a vector.
2. Find the chunks whose vectors are closest to the question vector.
3. Send the question and those chunks to a chat model and ask it to answer using only these chunks.

That’s it. The rest of this article is details.

Notice that there are two different models:

The embedding model is small and fast. The chat model is the big one. Both run locally in Ollama.

Wait, what is this vector?

This is the most interesting part, so let’s slow down a little.

An embedding model reads a piece of text and returns a fixed-size array of numbers. nomic-embed-text returns 768 numbers for any text, whether it’s one word or a full paragraph:

"settlement batch runs at 02:30"  →  [-0.064, 0.142, 0.009, ... 765 more ...]

The model is trained so that texts with similar meaning get vectors that point in a similar direction. “When does the nightly batch run?” and “settlement-service runs the nightly batch at 02:30” share almost no grammar, but their meaning is close, so their vectors are close too.

Now the fun part. It’s natural to think that each number means something: dimension 17 is “money”, dimension 302 is “time of day”, dimension 555 is “how angry the on-call engineer is”. It doesn’t work like that.

No single dimension has a physical meaning. Nobody designed these axes. The model learned the layout by itself during training. Meaning is spread across all 768 numbers at once, a bit like a smell is spread across many different molecules. You can’t point at one number and say “this is the time part”. Only the vector as a whole means something, and only when you compare it with other vectors.

Here’s a 2D sketch of what that looks like. The real space has 768 dimensions, and I have only two axes on my screen:

The question vector points almost in the same direction as the “settlement batch runs at 02:30” chunk. The sourdough recipe chunk points somewhere else entirely. So for a computer, “similar meaning” becomes simple geometry: a small angle between two vectors.

The usual way to measure this is cosine similarity, the cosine of that angle:

• 1: same direction, very similar
• 0: unrelated
• -1: opposite direction

LangChain4j turns it into a friendlier score from 0 to 1: (1 + cos θ) / 2. That’s the score you’ll see in the API response later.

One important rule: vectors from different embedding models are not compatible. Each model builds its own space with its own layout. If you change the embedding model, you have to re-embed all your documents. It’s like changing the map projection: the old coordinates don’t match the new map.

The stack

• Java 25 and Spring Boot 4.1: the usual REST app.
• LangChain4j 1.22: the Java library that does the AI work.
• Ollama: runs both models locally.
• PostgreSQL 17 + pgvector: stores chunks and vectors, and searches by similarity.
• Testcontainers: for functional tests with a real database.

Run the infrastructure with one command:

Source: docker-compose.yaml

services:
  db:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_DB: rag
      POSTGRES_USER: rag
      POSTGRES_PASSWORD: rag
    ports: ["5432:5432"]
  ollama:
    image: ollama/ollama
    ports: ["11434:11434"]
    volumes:
      - ollama-models:/root/.ollama   # keeps downloaded models between restarts
  ollama-init:
    image: ollama/ollama
    depends_on: [ollama]
    environment:
      OLLAMA_HOST: ollama:11434
    entrypoint: ["sh", "-c", "sleep 5 && ollama pull nomic-embed-text && ollama pull llama3.1:8b"]
volumes:
  ollama-models:

The ollama-init container is a one-off job that downloads the models. The first time it pulls a few GB, so it’s a good moment to make some tea.

LangChain4j: AI LEGO for Java

LangChain4j is to AI roughly what Spring Data is to databases. It gives you small interfaces with many implementations, so your code doesn’t depend on a specific vendor.

The demo uses four building blocks, plus one helper that glues three of them together:

• DocumentSplitter cuts text into chunks.
• EmbeddingModel turns text into a vector. Here it’s OllamaEmbeddingModel.
• EmbeddingStore<TextSegment> saves vectors and finds the nearest ones. Here it’s PgVectorEmbeddingStore.
• ChatModel sends a prompt and gets an answer. Here it’s OllamaChatModel.
• EmbeddingStoreIngestor runs split → embed → store in one call.

The nice part is the bottom of that picture. Want OpenAI instead of Ollama? Change one bean. Want Qdrant instead of Postgres? Change one bean. The services don’t care.

Dependencies

Source: build.gradle

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-jdbc'
    implementation 'org.springframework.boot:spring-boot-starter-webmvc'
    implementation 'dev.langchain4j:langchain4j:1.22.0'
    implementation 'dev.langchain4j:langchain4j-ollama:1.22.0'
    implementation 'dev.langchain4j:langchain4j-pgvector:1.22.0-beta32'
    runtimeOnly 'org.postgresql:postgresql'
}

Three LangChain4j modules: the core, the Ollama integration and the pgvector store. That’s all.

Wiring the beans

Source: LangChain4jConfig.java

@Configuration
public class LangChain4jConfig {
    public static final String CHUNK_TABLE = "chunk_embedding";
    @Bean
    EmbeddingModel embeddingModel(OllamaClientProperty property) {
        return OllamaEmbeddingModel.builder()
                .baseUrl(property.baseUrl())
                .modelName(property.embedModel())
                .build();
    }
    @Bean
    ChatModel chatModel(OllamaClientProperty property) {
        return OllamaChatModel.builder()
                .baseUrl(property.baseUrl())
                .modelName(property.chatModel())
                .build();
    }
    @Bean
    DocumentSplitter documentSplitter(ChunkProperty property) {
        return DocumentSplitters.recursive(property.size(), property.overlap());
    }
    @Bean
    EmbeddingStore<TextSegment> embeddingStore(DataSource dataSource) {
        return PgVectorEmbeddingStore.datasourceBuilder()
                .datasource(dataSource)
                .table(CHUNK_TABLE)
                .createTable(false)
                .skipCreateVectorExtension(true)
                .metadataStorageConfig(DefaultMetadataStorageConfig.builder()
                        .storageMode(MetadataStorageMode.COMBINED_JSONB)
                        .columnDefinitions(List.of("metadata JSONB NULL"))
                        .build())
                .build();
    }
}

The embedding store reuses Spring’s DataSource, so there’s one connection pool and one config. I also told it not to create the table (createTable(false)) because I prefer to own the schema myself:

Source: schema.sql

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS chunk_embedding (
    embedding_id UUID PRIMARY KEY,
    embedding    vector(768) NOT NULL,
    text         TEXT NULL,
    metadata     JSONB NULL
);
CREATE INDEX IF NOT EXISTS chunk_embedding_hnsw
    ON chunk_embedding USING hnsw (embedding vector_cosine_ops);

Two things to notice:

• vector(768) is the pgvector column type. 768 must match the embedding model’s output. If you switch to a model with 1024 dimensions, this column has to change too.
• The HNSW index with vector_cosine_ops makes nearest-neighbour search fast. Without it, Postgres compares the question with every row. That’s fine for 9 chunks, but not for 9 million. HNSW is an approximate search: it trades a tiny bit of accuracy for a lot of speed.

Everything is configurable in application.yaml:

app:
  olama-client:
    base-url: http://localhost:11434
    embed-model: nomic-embed-text
    chat-model: llama3.1:8b
  chunk:
    size: 1000
    overlap: 150

Part 1: Ingest, or feeding the database

Here’s what happens to a document on the way in:

Why chunks?

Why not embed the whole document as one vector? Because one vector for a whole handbook would be an average of everything: founders, deploy rules, on-call pay, the sourdough recipe someone accidentally uploaded. It would be “kind of about everything”, and that means it’s close to nothing.

Small chunks keep the meaning sharp. One chunk is about the settlement batch, another is about deploy windows. Now the search can find the right one.

The demo uses DocumentSplitters.recursive(1000, 150):

• 1000: the maximum chunk size in characters.
• 150: overlap. Each chunk repeats about 150 characters from the end of the previous one. So if an important sentence lands on a border, it’s still complete in at least one chunk.
• Recursive means it tries to cut nicely. First by paragraphs. If a paragraph is too big, then by lines, then by sentences, then by words. It cuts the text like a polite butcher, not with a chainsaw.

The ingest service

Source: IngestService.java

@Service
@RequiredArgsConstructor
public class IngestService {
    public static final String SOURCE = "source";
    private final DocumentSplitter splitter;
    private final EmbeddingModel embeddingModel;
    private final EmbeddingStore<TextSegment> store;
    
    public int ingest(String source, String text) {
        if (text.isBlank()) return 0;
        var chunks = new AtomicInteger();
        EmbeddingStoreIngestor.builder()
                .documentSplitter(splitter)
                .textSegmentTransformer(segment -> { chunks.incrementAndGet(); return segment; })
                .embeddingModel(embeddingModel)
                .embeddingStore(store)
                .build()
                .ingest(Document.from(text, Metadata.from(SOURCE, source)));
        return chunks.get();
    }
}

EmbeddingStoreIngestor does all three steps for us: split, embed, store. The textSegmentTransformer is a hook that runs for every chunk. Here I only use it to count chunks for the API response, but it’s also the right place to clean text or add extra metadata.

The source metadata (the file name) travels with every chunk into the metadata JSONB column. Later it lets the answer say where the information came from.

The controller is a plain multipart upload:

Source: RagController.java

@PostMapping(value = "/ingest", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public Map<String, Object> upload(@RequestParam MultipartFile file) throws IOException {
    String text = new String(file.getBytes(), StandardCharsets.UTF_8);
    return Map.of("chunks", ingest.ingest(file.getOriginalFilename(), text));
}

Let’s feed it the Harbourline handbook:

curl -F file=@docs/notes.md http://localhost:8080/api/ingest

{ "chunks": 9 }

Nine chunks, nine vectors, nine rows. The database now knows about a company that doesn’t exist.

Part 2: Ask, or the open-book exam

Source: RagService.java

@Service
@RequiredArgsConstructor
public class RagService {
    private final EmbeddingModel embeddingModel;
    private final EmbeddingStore<TextSegment> store;
    private final ChatModel chatModel;
    private static final String SYSTEM = """
        Answer using ONLY the provided context. If the answer is not in the
        context, say you don't know. Cite sources as [1], [2]...""";
    
public record Answer(String answer, List<Hit> sources) {}
    public Answer ask(String question) {
        var q = embeddingModel.embed(question).content();
        var hits = store.search(EmbeddingSearchRequest.builder().queryEmbedding(q).maxResults(5).build())
                .matches().stream()
                .map(m -> new Hit(m.embedded().metadata().getString(IngestService.SOURCE), m.embedded().text(), m.score()))
                .toList();
        var ctx = new StringBuilder();
        for (int i = 0; i < hits.size(); i++)
            ctx.append("[").append(i + 1).append("] (").append(hits.get(i).source()).append(")\n")
                    .append(hits.get(i).content()).append("\n\n");
        String prompt = "Context:\n" + ctx + "\nQuestion: " + question;
        return new Answer(chatModel.chat(SystemMessage.from(SYSTEM), UserMessage.from(prompt)).aiMessage().text(), hits);
    }
}

This is the heart of the project, and it follows the plan exactly:

1. Embed the question with the same model we used for the chunks. Same model means same space, so the distances make sense.
2. Search the store for the 5 nearest vectors. Under the hood, pgvector uses the HNSW index and cosine distance.
3. Build the context: number each chunk and add its source.
4. Ask the chat model with a strict system message: use only the context, say “I don’t know” if the answer isn’t there, and cite sources.

This is roughly what llama actually receives:

SYSTEM:
Answer using ONLY the provided context. If the answer is not in the
context, say you don't know. Cite sources as [1], [2]...

USER:
Context:
[1] (notes.md)
... settlement-service — runs the nightly settlement batch at 02:30 UK time ...

[2] (notes.md)
...

Question: When does the nightly settlement batch run?

The chat model never sees the database, the vectors or the other chunks. It sees a small, focused cheat sheet and a question. Its job is now easy: read and summarise.

Let’s try it:

curl -H 'Content-Type: application/json' \
     -d '{"question": "When does the nightly settlement batch run?"}' \
     http://localhost:8080/api/ask

{
  "answer": "According to the context in [3] (notes.md), the nightly settlement batch runs at 02:30 UK time.",
  "sources": [
    { "source": "notes.md", "content": "...", "score": 0.79 }
  ]
}

02:30 UK time. Correct, and with a source. Open-book exam passed. 🎓

The sources list matters as much as the answer. You can show it to users, so they can check where the answer came from instead of trusting the model blindly. Trust, but verify, especially with an 8B model.

Things to keep in mind

The demo is small on purpose. Before you take it to production, think about these:

• Chunk size is a trade-off. Too small, and a chunk loses context (“it runs at 02:30”, but what is “it”?). Too big, and the meaning gets blurry again. 1000/150 is a reasonable start, not a law.
• The top 5 are always returned, even when nothing is relevant. Ask about pizza, and you’ll still get the 5 “least irrelevant” chunks. The strict system prompt helps the model say “I don’t know”. In a real system I’d also add a minimum score (EmbeddingSearchRequest supports minScore).
• Changing the embedding model means re-ingesting everything. Different model, different space, different vector(N) column.
• Re-uploading the same file creates duplicates. The demo only appends. A real system needs to update or delete chunks by source.
• Garbage in, garbage out. RAG is only as good as the documents you give it. If the wiki is wrong, the answer will be wrong, but now with a citation.

Summary

RAG sounds like a fancy AI term, but in code it’s a short pipeline:

• Ingest: split text into chunks → embed each chunk into a vector → store the text and vector in pgvector.
• Ask: embed the question → find the closest chunk vectors → give the question and those chunks to the chat model → answer with sources.

The vectors are the only “magic” part. They are 768 numbers with no human meaning in any single dimension, but their direction captures meaning. Similar text means a small angle, and a small angle is something a database can search.

LangChain4j turns each step into one small interface, so the whole service is a handful of Spring beans. You can swap Ollama for OpenAI, or pgvector for Qdrant, without touching the business code.

And now a local 8B model knows when Harbourline’s settlement batch runs. Harbourline still doesn’t exist, but at least its batch is on time. ⏰

The full code is on GitHub: SukachVitally/rag-demo. Clone it, run docker compose up -d, upload your own notes and ask them questions.

In my previous article I built an MCP server from scratch in Python. I wrote the JSON-RPC 2.0 message handling, declared tool schemas by hand and wired up the STDIO transport myself. It’s a good way to learn how the protocol works on the wire.

Python isn’t the only option, though. Most of the systems I work on are Java and Spring, and that’s where the data lives. So this time I built the same kind of server in Java.

It turns out you don’t need to implement JSON-RPC yourself. Spring AI has a Boot starter for MCP servers. It handles the protocol, the transport, schema generation and tool registration. You write ordinary Spring beans and add a few annotations.

The full code is on GitHub: SukachVitally/mcp-demo.

Why bother: the server is the boundary

The business logic here is deliberately boring. It’s a task list: you create tasks, move them through statuses, and finish or cancel them. Swap in your own domain; the MCP part stays the same.

The point is how Claude Code reaches the data:

Claude Code ──HTTP + API key──▶ MCP server (Spring) ──JDBC──▶ PostgreSQL

• Claude never sees database credentials. The server holds the connection. Claude holds only an API key that works for the MCP endpoint and nothing else.
• Claude can only do what you expose. There’s no SQL console. If you don’t write a delete_task tool, tasks can’t be deleted, however the prompt is phrased.
• Your validation and transactions still apply. Every call goes through the same service layer as the rest of your application.

Giving an agent a database URL and a password is quick, but you can’t take it back. An MCP server gives the agent a small, typed and auditable API instead.

What we’re building

A PostgreSQL table of tasks. Each task has a name and one of four statuses: NEW, IN_PROGRESS, DONE or CANCELLED. The server exposes four tools:

Stack: Java 25, Spring Boot 4, Spring AI 2.0 MCP server, PostgreSQL 18 with Liquibase, and Spring Security.

Step 1: Dependencies

Source: build.gradle

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-liquibase'
    implementation 'org.springframework.boot:spring-boot-starter-webmvc'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation platform('org.springframework.ai:spring-ai-bom:2.0.1')
    implementation 'org.springframework.ai:spring-ai-starter-mcp-server-webmvc'
    implementation 'org.springaicommunity:mcp-server-security-spring-boot:0.1.14'
    runtimeOnly 'org.postgresql:postgresql'
}

Two lines do the MCP work:

• spring-ai-starter-mcp-server-webmvc is the MCP server over HTTP on Spring MVC. There’s a -webflux variant for reactive apps, and a plain spring-ai-starter-mcp-server for stdio.
• mcp-server-security-spring-boot from the spring-ai-community/mcp-security project adds API-key and OAuth2 support on top of Spring Security. We’ll come back to it.

Step 2: Configure the server

Source: application.yaml

spring:
  ai:
    mcp:
      server:
        protocol: STATELESS
        type: sync
        name: "Task MCP demo"
        instructions: >-
          Manages a simple task list. Create tasks with add_task, look them up with get_task or
          get_task_list, and move them through the statuses NEW, IN_PROGRESS, DONE and CANCELLED
          with update_task_status.
        streamable-http:
          mcp-endpoint: /mcp

What these settings mean:

• protocol: STATELESS: plain HTTP request and response, with no session kept between calls. Our tools never need to push anything back to the client, so we don’t need sessions, and the server scales horizontally like any other REST service. Use STREAMABLE if you need server-to-client messages. The older SSE option is deprecated since Spring AI 2.0.
• type: sync: tools are ordinary blocking methods. With async, they return Reactor Mono/Flux types instead.
• instructions: sent to the client when it connects. It’s the server’s short explanation to the model of how the tools fit together. Treat it as part of the prompt.
• mcp-endpoint: /mcp: the URL that Claude Code will call.

Step 3: Business logic (keep it boring)

Nothing here knows about MCP. It’s a normal JPA entity, repository and service:

Source: TaskService.java

@Service
@Validated
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class TaskService {
    public static final int NAME_MAX_LEN
GTH = 255;
    private final TaskRepository repository;
    private final TaskMapper mapper;
    @Transactional
    public TaskDto create(@NotBlank @Size(max = NAME_MAX_LENGTH) String name) {
        var entity = new TaskEntity();
        entity.setName(name);
        entity.setStatus(TaskStatus.NEW);
        return mapper.toDto(repository.save(entity));
    }
    @Transactional
    public TaskDto updateStatus(Long id, @NotNull TaskStatus status) {
        var entity = findEntity(id);
        entity.setStatus(status);
        return mapper.toDto(entity);
    }
    // get(id), getList(), findEntity(id) throws TaskNotFoundException ...
}

The service returns a small record, not the entity:

Source: TaskDto.java

public record TaskDto(Long id, String name, TaskStatus status) {}

That matters more than it looks. Whatever a tool returns is serialized and handed to the model, so the DTO decides exactly which fields leave your system.

Step 4: TaskMcpTool, the actual MCP server

This is the whole MCP layer:

Source: TaskMcpTool.java

@Component
@RequiredArgsConstructor
public class TaskMcpTool {
    private final TaskService service;
    @McpTool(name = "add_task", description = "Create a new task with status NEW and return it")
    public TaskDto add(@McpToolParam(description = "Task name, 1-255 characters") String name) {
        return service.create(name);
    }
    @McpTool(name = "get_task", description = "Get a task by its id. Fails if the task does not exist")
    public TaskDto get(@McpToolParam(description = "Task id") Long id) {
        return service.get(id);
    }
    @McpTool(name = "update_task_status",
            description = "Change the status of a task and return the updated task. Fails if the task does not exist")
    public TaskDto updateStatus(@McpToolParam(description = "Task id") Long id,
                                @McpToolParam(description = "New task status") TaskStatus status) {
        return service.updateStatus(id, status);
    }
    @McpTool(name = "get_task_list", description = "List all tasks")
    public List<TaskDto> getList() {
        return service.getList();
    }
}

Only a thin adapter: each method delegates to the service. Most of the work happens in the annotations.

How the tools get registered

The class is a plain @Component. When the application starts, Spring AI’s annotation scanner finds every bean method annotated with @McpTool and registers it as an MCP tool. You don’t need a registry, a ToolCallback list or any manual wiring. To add a tool, write another annotated method.

@McpTool: the name and description the model sees

• name is the tool id the model calls. I use snake_case verbs (add_task, get_task_list) because that’s the convention across MCP servers, and models pick such names up reliably. Without a name, the Java method name is used, and add on its own tells the model very little.
• description is the most important string in the class. It’s the only thing the model reads when deciding which tool to call and what to expect back. Say what the tool does, what it returns and when it fails (“Fails if the task does not exist”). A vague description gives you a model that guesses.

@McpToolParam: the schema is generated for you

Each parameter gets a description, and Spring AI builds a JSON Schema from the Java type. Here’s what the server actually returns for update_task_status when Claude Code asks for tools/list:

{
  "name": "update_task_status",
  "description": "Change the status of a task and return the updated task. Fails if the task does not exist",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id":     { "type": "integer", "format": "int64", "description": "Task id" },
      "status": { "type": "string",
                  "enum": ["NEW", "IN_PROGRESS", "DONE", "CANCELLED"],
                  "description": "New task status" }
    },
    "required": ["id", "status"]
  }
}

Things to notice:

• Long became integer with int64 format. You don’t write any schema by hand.
• Parameters are required by default (required = true). Set @McpToolParam(required = false) for optional ones.
• The TaskStatus enum became a JSON enum. The model sees the four allowed values up front, so it can’t invent a status like DELETED. If it tries, the call is rejected by schema validation before your method runs:

Tool (update_task_status) input validation failed: ... /status: does not 
have a value in the enumeration ["NEW", "IN_PROGRESS", "DONE", "CANCELLED"]

Use enums for anything with a fixed set of values. You get validation and documentation in one place.

Return values and errors

You return a normal Java object, and Spring AI serializes it to JSON as the tool result. TaskDto and List<TaskDto> just work.

Exceptions work too. When TaskService throws TaskNotFoundException, the client doesn’t get a stack trace or a broken JSON-RPC response. It gets a tool result with isError: true and the exception message as the text:

{ 
  "content": [{ "type": "text", "text": "Task with id -1 is not found" }], 
  "isError": true 
}

That’s the behaviour you want: the model reads the message, understands what went wrong and can recover, for example by calling get_task_list to find the right id. Write exception messages for the model to read, not just for your logs.

The same applies to Bean Validation. A blank name fails @NotBlank in the service and comes back to the model as an error result, not a 500.

A tip: add behaviour hints

If you look at the full tools/list response, every tool reports “readOnlyHint”: false, “destructiveHint”: true, including get_task_list. Those are the defaults. Clients such as Claude Code can use these hints to decide how cautious to be, so it’s worth being honest about read-only tools:

@McpTool(name = "get_task_list", description = "List all tasks",
        annotations = @McpTool.McpAnnotations(readOnlyHint = true, 
                                              destructiveHint = false))

These are hints, not enforcement. What actually protects your data is the fact that the tool only reads.

Step 5: SecurityConfig, briefly

By default, an HTTP MCP endpoint is an unauthenticated JSON-RPC endpoint. Anyone who can reach /mcp can call your tools. The mcp-security library closes it with a few lines:

Source: SecurityConfig.java

@Configuration
@EnableWebSecurity
class SecurityConfig {
    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http,
                                            ApiKeyEntityRepository<ApiKeyEntityImpl> apiKeyRepository) {
        return http
                .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
                .with(mcpServerApiKey(), apiKey -> apiKey.apiKeyRepository(apiKeyRepository))
                .build();
    }
    @Bean
    ApiKeyEntityRepository<ApiKeyEntityImpl> apiKeyRepository(@Value("${app.mcp.api-key.secret}") String secret) {
        var key = ApiKeyEntityImpl.builder()
                .name("demo key")
                .id("demo")
                .secret(secret)
                .build();
        return new InMemoryApiKeyEntityRepository<>(List.of(key));
    }
}

• mcpServerApiKey() plugs API-key authentication into the normal Spring Security filter chain.
• The client sends an X-API-key header in the form <id>.<secret>, so demo.<your secret> here. Requests without it get 401.

Step 6: Run it and connect Claude Code

Start PostgreSQL and the app:

Source: docker-compose.yaml,.env.tpl, README

cp .env.tpl .env          # sets MCP_API_KEY_SECRET
docker compose up -d
./gradlew bootRun

Register the server with Claude Code:

claude mcp add --transport http todos http://localhost:8080/mcp \
  --header "X-API-key: demo.mcp-demo-test-secret"

Then ask in plain language:

“Add todo with name test” becomes an add_task call. “Update task with id 1 to DONE” becomes update_task_status with a valid enum value. Claude never saw a JDBC URL, a username or a password.

To inspect the server without Claude, use the MCP Inspector (npx @modelcontextprotocol/inspector). Choose the Streamable HTTP transport and add the same header.

Testing

Because the server speaks standard MCP, the tests can use the official Java MCP client against a real server started by @SpringBootTest, with PostgreSQL in Testcontainers:

Source: TaskMcpToolTest.java

var transport = HttpClientStreamableHttpTransport
        .builder("http://localhost:" + port)
        .httpRequestCustomizer((builder, method, endpoint, body, context) ->
                builder.header("X-API-key", "demo." + API_KEY_SECRET))
        .build();
client = McpClient.sync(transport).build();
client.initialize();
var result = client.callTool(McpSchema.CallToolRequest.builder("get_task")
        .arguments(Map.of("id", -1L)).build());
assertThat(result.isError()).isTrue();

This covers the whole chain in one test: authentication, schema, serialization, error mapping and the database.

Takeaways

• You don’t write JSON-RPC in Java. spring-ai-starter-mcp-server-webmvc handles the protocol, the transport and tool discovery.
• An MCP tool is an annotated Spring bean method. @McpTool names and describes it, and @McpToolParam describes its inputs. The JSON Schema is generated from your Java types.
• Descriptions and error messages are prompts. The model reads them, so write them for the model.
• Use enums and DTOs to control what the model can send in and what it gets back.
• Secure the endpoint. API keys via mcp-security take ten lines, and OAuth2 is available when you need it.
• The MCP server is the security boundary. Claude Code works with your data through the operations you choose, never with your credentials.

The Python version showed how MCP works on the wire. The Spring version shows how little code you need once a framework handles it. Take the repo, replace tasks with your own domain, and give your agent an API instead of a password.

Links

• Demo code: github.com/SukachVitally/mcp-demo
• Spring AI MCP Server Boot Starter: docs.spring.io
• MCP security for Spring: github.com/spring-ai-community/mcp-security
• Previous article, MCP in Python from scratch: MCP: The Protocol That Finally Taught AI to Stop Being Useless

Ask ten Java developers what “the Java Memory Model” means and you’ll get two different answers.

Half of them will draw a box called Heap and another called Stack. The other half will start talking about volatile and happens-before.

Both groups are talking about something real, but only the second group is talking about the actual Java Memory Model (JMM). The first group is describing the runtime data areas — where objects physically live.

You need both to write correct concurrent code, so let’s go through them in order. Memory layout first, because it’s the easier one, then the JMM proper.

Part 1: Where your data lives

When the JVM starts, it carves the process memory into a few distinct regions. Each has an owner and a lifetime.

Heap — every object and array you ever create lives here. It’s shared, which is exactly why concurrency is hard. Garbage collection happens here. Modern collectors split it further (young generation, old generation, or regions in G1/ZGC), but that’s a GC detail, not a memory model one.

Metaspace — class metadata, bytecode, and static fields. It sits in native memory since Java 8, which is why PermGen errors disappeared and Metaspace OOM errors appeared instead.

Thread stack — each thread gets its own. Every method call pushes a frame containing local variables, parameters, and the return address. Frame pops when the method returns. This is where StackOverflowError comes from. Nothing here is shared, so locals are never a concurrency problem — unless the value they point to is a shared object.

PC register — the address of the instruction the thread is currently executing. One per thread.

Native method stack — the same idea, but for native (JNI) calls.

One thing worth burning in:

Order order = new Order();

The variable order is a reference sitting on the stack. The Order object itself sits on the heap. Two threads can hold two separate stack references pointing to the same heap object. That’s the whole source of the trouble.

Part 2: The actual Java Memory Model

The runtime areas tell you where data sits. They tell you nothing about when one thread sees a write made by another.

That question is what the JMM answers. It’s a specification (JSR-133, in Chapter 17 of the Java Language Specification) that defines exactly what guarantees you get about reads and writes across threads.

The problem it exists to solve

Modern CPUs are fast because they cheat, aggressively and correctly. Two things they do:

1. Caching. Each core has its own L1/L2 cache. When a thread writes to a field, that write may sit in the core’s cache or store buffer for a while before it becomes visible to other cores.

2. Reordering. The compiler, the JIT, and the CPU are all allowed to reorder instructions, as long as the result looks the same for a single thread. That last clause is the trap — nobody promised anything about how it looks to other threads.

So the JMM works with an abstraction:

Thread A and Thread B never see each other’s working memory. Everything they share has to travel through main memory — and the JMM decides when it does.

Every thread has a conceptual working memory (registers, cache, store buffers) holding copies of the variables it touches. Threads never talk to each other directly — they communicate only through main memory. The JMM specifies when a value must be flushed to main memory and when it must be re-read from it.

Here’s the classic demonstration:

public class StopFlag {
    private boolean running = true;   // no volatile
    
    public void run() {
        while (running) {
            // do work
        }
        System.out.println("stopped");
    }
    public void stop() {
        running = false;
    }
}

Thread A runs run(). Thread B calls stop(). Very often, thread A never stops.

Nothing is broken. The JIT sees that running is never modified inside the loop, so it’s free to hoist the read out:

boolean r = running;
while (r) { /* work */ }   // now an infinite loop

Without a memory model rule forcing it, the JVM has no obligation to ever re-read that field. Your bug is not a race in the “two writes collided” sense — it’s a visibility failure.

The three guarantees

Every concurrency problem in Java falls into one of these buckets.

count++ is the textbook atomicity failure — it’s three operations (read, add, write), and two threads can interleave in the middle. Two increments, one result.

The base components of the JMM

Here’s the toolbox. It’s smaller than most people expect.

1. happens-before — the rule that underpins everything

Everything else is a special case of this one relation. If action A happens-before action B, then:

• everything A wrote is visible to B, and
• A is guaranteed to appear to occur before B.

It is not just “A ran earlier in wall-clock time.” Two actions can be ordered in time and still have no happens-before relationship, which means B may see stale data.

The rules the JLS gives you:

1. Program order — within one thread, each statement happens-before the ones written after it.
2. Monitor lock — unlocking a monitor happens-before any later lock of the same monitor.
3. volatile — a write to a volatile field happens-before every later read of that field.
4. Thread start — Thread.start() happens-before anything in the started thread.
5. Thread join — everything in a thread happens-before another thread’s successful join() on it.
6. Interruption — a call to interrupt() happens-before the interrupted thread detects it.
7. Constructor / finalizer — the end of a constructor happens-before the start of that object’s finalizer.
8. Transitivity — if A hb B and B hb C, then A hb C.

That last one does most of the practical work. It’s why writing a plain field and then a volatile flag safely publishes the plain field.

2. volatile — visibility and ordering, no atomicity

private volatile boolean running = true;

This single keyword fixes the StopFlag example. It gives you:

• Visibility — a write goes to main memory immediately; a read comes from main memory, never a cache.
• Ordering — the JVM inserts memory barriers so reads and writes can’t be reordered across the volatile access.

What it does not give you is atomicity:

private volatile int count = 0;
public void increment() {
    count++;   // STILL BROKEN
}

Use volatile for flags and for single-writer state. For compound operations, use something else.

3. synchronized — all three guarantees

private int count = 0;
public synchronized void increment() {
    count++;   // correct
}
public synchronized int get() {
    return count;   // also needs to be synchronized
}

Entering the monitor gives mutual exclusion (atomicity). Exiting flushes to main memory, entering invalidates the local copy (visibility). Barriers around the block prevent reordering out of it.

The most common mistake here is synchronizing the writer but not the reader. Both sides need the same lock, or there’s no happens-before edge between them.

ReentrantLock gives you the same memory guarantees, plus tryLock, timeouts, fairness, and multiple conditions.

4. final — safe publication for free

public class Config {
    private final String url;
    public Config(String url) {
        this.url = url;   // guaranteed visible after construction
    }
}

The JMM guarantees that any thread that sees a properly constructed object sees the correct values of its final fields — no synchronization required. This is why immutable objects are the easiest possible concurrency strategy.

The catch is “properly constructed.” If the constructor leaks this (registering a listener, starting a thread), the guarantee is void.

5. Atomics and VarHandle

java.util.concurrent.atomic gives you lock-free compound operations built on CPU compare-and-swap instructions:

private final AtomicInteger count = new AtomicInteger();
public void increment() {
    count.incrementAndGet();   // atomic, visible, ordered
}

Under contention LongAdder usually beats AtomicLong — it spreads writes across cells and sums them on read, avoiding cache-line contention. VarHandle (Java 9+) is the modern, supported way to reach for finer-grained modes like getAcquire / setRelease when you know exactly what you’re doing.

Three bugs this explains

Unsafe publication. Building an object and handing the reference to another thread without a happens-before edge. The other thread can see a non-null reference to a half-initialized object — fields still at their defaults. Publish through a volatile field, a lock, a final field, or a concurrent collection.

Double-checked locking without volatile. The infamous one:

private static volatile Singleton instance;   // volatile is mandatory
public static Singleton getInstance() {
    if (instance == null) {
        synchronized (Singleton.class) {
            if (instance == null) {
                instance = new Singleton();
            }
        }
    }
    return instance;
}

Drop the volatile and it breaks, because instance = new Singleton() is three steps — allocate, construct, assign — and the last two can be reordered. Another thread can grab a reference to an object whose constructor hasn’t finished.

Check-then-act. if (!map.containsKey(k)) map.put(k, v); is two atomic operations, not one atomic operation. Use putIfAbsent or computeIfAbsent.

The practical cheat sheet

• Shared and mutable? It needs synchronization. Every time.
• One thread writes a flag, others read it? volatile.
• Compound operation on one variable? An atomic class.
• Compound operation across several variables? synchronized or ReentrantLock.
• Can you make it immutable instead? Do that. final fields, no setters, no shared mutation, no memory model to reason about.
• Reading is also access. Unsynchronized reads of synchronized state are still broken.
• “It works on my machine” proves nothing. x86 has a strong memory model that hides many of these bugs. ARM (Apple Silicon, Graviton) doesn’t. Code that ran fine for years on Intel servers can fail the week you move it to ARM instances.

Wrapping up

The runtime areas — heap, stacks, metaspace — tell you where your data sits. The Java Memory Model tells you when one thread’s writes become visible to another, and it comes down to a handful of pieces: happens-before as the underlying rule, and volatile, synchronized, final, and the atomics as the tools that create it.

You don’t need to memorize the specification. You need one habit: whenever two threads touch the same data, ask what creates the happens-before edge between them. If you can’t name it, it isn’t there.

If this was useful, the natural next step is Brian Goetz’s Java Concurrency in Practice — still the best treatment of this material, twenty years on.

There is a specific kind of bug that only shows up in production, only in October, and only for users in one country. It gets closed as “not reproducible” twice before someone finally sits down with a coffee and reads the column definition.

It is almost always a datetime bug.

The frustrating part is that both Java and PostgreSQL have excellent date/time support. java.time is one of the best-designed APIs in the JDK. PostgreSQL’s temporal types are precise and well documented. The bugs happen at the seam — in the assumptions each side makes about what the other means, and in the two or three words in the type names that mean the opposite of what you’d guess.

This guide walks through both models, then spends real time on the part that actually causes outages: time zones.

Every code output and query result below was executed — Java 21 and PostgreSQL 16 — not written from memory.

Part 1: The Java Side

Ask three questions, get one type

Every java.time class is an answer to some combination of three questions:

1. Do I know the date?
2. Do I know the time of day?
3. Do I know which point on the global timeline this is?

That last one is the important one, and it’s the one people skip. Here’s the map:

The single most useful sentence in this article: LocalDateTime is not a point in time. 2026-08-15T12:00 is twelve o’clock somewhere, and until you say where, it refers to a 26-hour-wide smear across the planet. If you have an Instant and you call .toLocalDateTime(), you have thrown away information and the compiler will not warn you.

Instant is the boring, correct default

Instant now = Instant.now();     // 2026-08-15T10:00:00.123456789Z

An Instant is nanoseconds since the epoch. No zone, no offset, no calendar. When it prints with a Z, that isn’t a stored time zone — it’s the ISO-8601 way of rendering an epoch value.

Anything that happened — a login, a payment, a row insert — is an Instant. Reach for something else only when you have a reason.

ZoneId vs ZoneOffset: not the same thing

This distinction matters more than any other in this article.

ZoneId.of("Europe/London")  // -> java.time.ZoneRegion
ZoneId.of("+01:00")         // -> java.time.ZoneOffset

A ZoneOffset is a fixed number of hours and minutes from UTC. +01:00. That’s the whole thing. It’s a fact about one moment.

A ZoneId (specifically a ZoneRegion, like Europe/London) is a rulebook. It knows that London was +00:00 in January, +01:00 in August, and it knows the exact instants at which it flips — going back decades and forward as far as legislators have declared.

ZoneOffset is a value. ZoneId is a function from instant to offset. Confusing them is the root cause of most scheduling bugs.

OffsetDateTime vs ZonedDateTime

Both identify a real instant. The difference is what survives.

ZonedDateTime nyc = ZonedDateTime.of(2026, 7, 4, 12, 0, 0, 0,
                                     ZoneId.of("America/New_York"));
nyc                    // 2026-07-04T12:00-04:00[America/New_York]
nyc.toOffsetDateTime() // 2026-07-04T12:00-04:00
nyc.toInstant()        // 2026-07-04T16:00:00Z

All three describe the same moment. But the ZonedDateTime still knows it’s in New York, so if you add six months to it, it will correctly land on -05:00. The OffsetDateTime has been flattened — it remembers that the offset was -04:00, not why. Add six months and you get a wrong wall-clock time.

Rule of thumb: ZonedDateTime for calculating, OffsetDateTime for transporting, Instant for storing.

Duration vs Period

LocalDate.of(2026, 1, 31).plusMonths(1)  // 2026-02-28

Duration is exact elapsed time — seconds and nanos. Period is calendar time — years, months, days. “One month” is not a fixed number of seconds, and plusMonths clamps rather than overflowing. Both behaviors are correct; mixing them up is not.

This distinction resurfaces the moment DST enters the picture, and we’ll come back to it.

A word on the old API

java.util.Date is a mislabeled Instant (it has no time zone despite what toString() implies). Calendar is mutable and lenient. java.sql.Timestamp extends java.util.Date and adds nanoseconds while breaking the equals contract.

If you’re on a legacy codebase, convert at the boundary and never let them into your domain:

Instant i = oldDate.toInstant();
Date    d = Date.from(instant);

Part 2: The PostgreSQL Side

timestamptz does not store a time zone

This is the single biggest source of confusion, and it comes straight from the type name. TIMESTAMP WITH TIME ZONE is an 8-byte value. So is TIMESTAMP WITHOUT TIME ZONE. There is no room in there for a zone, and PostgreSQL doesn’t try:

SELECT pg_column_size('2026-08-15 12:00:00'::timestamp)     AS ts_bytes,     
       --  8
       pg_column_size('2026-08-15 12:00:00+02'::timestamptz) AS tstz_bytes,  
       --  8
       pg_column_size('12:00:00+02'::timetz)                 AS timetz_bytes; 
       -- 12

What timestamptz actually does is convert to UTC on write and convert back on read. The offset you supplied on input is used and then discarded. From the official docs:

In either case, the value is stored internally as UTC, and the originally stated or assumed time zone is not retained.

A better mental model: timestamptz is Instant. timestamp is LocalDateTime. The names lie; the semantics don’t.

The demo that makes it click

Insert the same two literals into both column types, with the session zone set to London:

SET TimeZone = 'Europe/London';
CREATE TABLE t (id int, ts timestamp, tstz timestamptz);
INSERT INTO t VALUES (1, '2026-08-15 12:00:00',    '2026-08-15 12:00:00');
INSERT INTO t VALUES (2, '2026-08-15 12:00:00+00', '2026-08-15 12:00:00+00');
SELECT * FROM t;

 id |         ts          |          tstz
----+---------------------+------------------------
  1 | 2026-08-15 12:00:00 | 2026-08-15 12:00:00+01
  2 | 2026-08-15 12:00:00 | 2026-08-15 13:00:00+01

Two things happened. Row 1’s tstz had no offset, so PostgreSQL assumed the session zone. Row 2’s explicit +00 was honoured and re-rendered as 13:00+01. Meanwhile the ts column ignored the offset entirely and stored the digits.

Now reconnect from New York and run the identical SELECT:

 id |         ts          |          tstz
----+---------------------+------------------------
  1 | 2026-08-15 12:00:00 | 2026-08-15 07:00:00-04
  2 | 2026-08-15 12:00:00 | 2026-08-15 08:00:00-04

The tstz column re-renders per client. The ts column is frozen. Neither row changed on disk.

That last point deserves emphasis, because it’s where the panic starts: when a developer sees a different value than QA saw, the instinct is “the data is corrupted.” It isn’t. Two clients with different TimeZone settings are looking at the same UTC value through different windows.

AT TIME ZONE runs both ways

AT TIME ZONE is the one operator you need, and its behavior flips depending on the input type:

-- timestamptz -> timestamp: "what does the clock read there?"
SELECT '2026-08-15 12:00:00+00'::timestamptz AT TIME ZONE 'Asia/Tokyo';
-- 2026-08-15 21:00:00   (type: timestamp without time zone)

-- timestamp -> timestamptz: "this wall clock reading WAS in Tokyo"
SELECT '2026-08-15 12:00:00'::timestamp AT TIME ZONE 'Asia/Tokyo';
-- 2026-08-15 03:00:00+00   (type: timestamp with time zone)

One removes zone context, the other attaches it. Read it as “interpret this value in that zone.” The function form timezone(‘Asia/Tokyo’, value) is identical.

The rest of the family

• date — 4 bytes, no zone, no ambiguity. Great for things that are genuinely dates.
• time — time of day, no zone.
• timetz — 12 bytes, and PostgreSQL itself recommends against it. A time of day with an offset but no date can’t resolve DST, so it’s not meaningfully anchored. It won’t even accept a zone name:

SELECT '12:00:00 Europe/London'::timetz; -- ERROR: invalid input syntax for type time with time zone

• interval — 16 bytes storing months, days, and microseconds separately, which is exactly why it can be DST-aware.

now() vs localtimestamp

SELECT pg_typeof(now()),            -- timestamp with time zone
       pg_typeof(current_timestamp), -- timestamp with time zone
       pg_typeof(localtimestamp),    -- timestamp without time zone
       pg_typeof(current_date);      -- date

now() and current_timestamp are timestamptz and are safe. localtimestamp and current_date are evaluated in the session zone, which means a DEFAULT current_date column produces different answers for different clients. Be deliberate.

So which do you pick?

The short version: use timestamptz for essentially everything. Reach for timestamp only when you genuinely mean a floating wall-clock time that must not shift — “the store opens at 09:00 local, whatever local means at that branch” — and store the zone ID beside it.

Part 3: Time Zones, Properly

This is where the real complexity lives, so let’s slow down.

Three things called “time zone”

1. An offset — +01:00. A number.
2. An IANA zone ID — Europe/London. A named set of historical and future rules. PostgreSQL ships ~499 of these in pg_timezone_names; Java reads the same tzdata.
3. An abbreviation — EST, BST, IST. Ambiguous, unversioned, and a trap.

That third one is genuinely dangerous:

SELECT '2026-08-15 12:00:00 EST'::timestamptz,               -- 2026-08-15 17:00:00+00
       '2026-08-15 12:00:00 America/New_York'::timestamptz;  -- 2026-08-15 16:00:00+00

One hour apart. EST is a fixed -05:00 in PostgreSQL — it does not mean “Eastern time,” it means “Eastern Standard Time, always.” In August, New York is on -04:00. If you accept zone abbreviations from user input, you have already shipped a bug. (IST is worse — it can mean India, Ireland, or Israel depending on who you ask.)

Always use full IANA names.

Offsets aren’t zones either. Nepal is +05:45; the Chatham Islands are +12:45:

ZonedDateTime.of(2026,8,15,12,0,0,0, ZoneId.of("Asia/Kathmandu"))
// 2026-08-15T12:00+05:45[Asia/Kathmandu]

If your API contract says “offset in whole hours,” it’s wrong.

Where PostgreSQL’s session zone comes from

The TimeZone GUC is a per-connection setting. Its value is decided by, in order: an explicit SET TimeZone, the connection’s startup parameters, the postgresql.conf value, and finally the server’s OS zone.

That last fallback is why the same query returns different results on a developer laptop and in CI. And with connection pooling, SET TimeZone on a borrowed connection leaks to whoever gets it next.

Pin it. Set timezone = ‘UTC’ in postgresql.conf, and add it to the JDBC URL so it survives pool reuse:

jdbc:postgresql://host:5432/db?options=-c%20TimeZone%3DUTC

Then make the client responsible for rendering. Formatting a timestamp for a human is a presentation concern, not a database one.

The spring-forward gap

On 29 March 2026, London jumps from 01:00 to 02:00. The local times between them do not exist.

Ask Java for one anyway:

LocalDateTime gap = LocalDateTime.of(2026, 3, 29, 1, 30);
gap.atZone(ZoneId.of("Europe/London"));
// 2026-03-29T02:30+01:00[Europe/London]
ZoneId.of("Europe/London").getRules().getTransition(gap);
// Transition[Gap at 2026-03-29T01:00Z to +01:00]

Java doesn’t throw. It silently pushes the value forward by the length of the gap. PostgreSQL does the same thing:

SET TimeZone='Europe/London';
SELECT '2026-03-29 01:30:00'::timestamptz;
-- 2026-03-29 02:30:00+01

Both are “correct” — but neither told you. If a user sets a 01:30 alarm on that date, you should be validating with getTransition() and telling them, not letting the platform quietly reschedule.

The fall-back overlap — where Java and PostgreSQL disagree

On 25 October 2026, London goes from 02:00 back to 01:00. Local times between 01:00 and 02:00 happen twice, one hour apart.

Java’s rules expose both:

ZoneId london = ZoneId.of("Europe/London");
LocalDateTime overlap = LocalDateTime.of(2026, 10, 25, 1, 30);
london.getRules().getValidOffsets(overlap);
// [+01:00, Z]
ZonedDateTime earlier = overlap.atZone(london);
// 2026-10-25T01:30+01:00[Europe/London]  instant = 2026-10-25T00:30:00Z
ZonedDateTime later = earlier.withLaterOffsetAtOverlap();
// 2026-10-25T01:30Z[Europe/London]       instant = 2026-10-25T01:30:00Z

Java’s default for an ambiguous local time is the earlier offset — 00:30Z.

Now ask PostgreSQL the same question:

SELECT '2026-10-25 01:30:00'::timestamp AT TIME ZONE 'Europe/London';
-- 2026-10-25 01:30:00+00

PostgreSQL picked 01:30Z — the later one.

Same input, same tzdata, one hour apart. If your application resolves an ambiguous local time in Java and your reporting job resolves it in SQL, they will disagree for one hour, twice a year, in every DST zone.

There is no clever fix. The lesson is: never let a LocalDateTime cross the boundary and get resolved on the other side. Resolve to an Instant in exactly one place, with explicit overlap handling, and send the instant.

DST arithmetic: plusDays is not plusHours(24)

ZonedDateTime start = ZonedDateTime.of(2026, 3, 28, 12, 0, 0, 0, london);
// 2026-03-28T12:00Z[Europe/London]
start.plusDays(1);                 // 2026-03-29T12:00+01:00  (23 real hours)
start.plus(Duration.ofDays(1));    // 2026-03-29T13:00+01:00  (24 real hours)
start.plusHours(24);               // 2026-03-29T13:00+01:00

plusDays preserves the wall clock. Duration preserves elapsed time. PostgreSQL draws the same line, using the same value:

SET TimeZone='Europe/London';
SELECT '2026-03-28 12:00:00+00'::timestamptz + interval '1 day',   -- 2026-03-29 12:00:00+01
       '2026-03-28 12:00:00+00'::timestamptz + interval '24 hours'; -- 2026-03-29 13:00:00+01

This is one place the two platforms agree beautifully — interval ‘1 day’ and plusDays(1) mean the same thing, and interval ‘24 hours’ and Duration.ofDays(1) mean the same thing. “Every day at 9am” is plusDays / interval ‘1 day’. “Every 24 hours” is Duration / interval ‘24 hours’. Pick the one the product actually means.

Future events: an instant is not enough

ZoneId ny = ZoneId.of("America/New_York");
ZonedDateTime.of(2027, 1, 15, 9, 0, 0, 0, ny).withZoneSameInstant(UTC); // 2027-01-15T14:00Z
ZonedDateTime.of(2027, 7, 15, 9, 0, 0, 0, ny).withZoneSameInstant(UTC); // 2027-07-15T13:00Z

“9am in New York” is a different UTC instant depending on the date. So if a user schedules a recurring 9am standup and a government later changes DST rules — which happens several times a year somewhere — the stored instant becomes wrong.

For past events, store the instant. That’s history; it can’t change.

For future user-scheduled events, store three things:

CREATE TABLE meetings (
  id            bigserial PRIMARY KEY,
  local_start   timestamp   NOT NULL,  -- 2027-01-15 09:00
  zone_id       text        NOT NULL,  -- 'America/New_York'
  computed_utc  timestamptz NOT NULL   -- cache; recompute on tzdata update
);

The first two are the truth. The third is a derived index for querying, refreshed when tzdata changes.

tzdata is a moving target

Java bundles a copy of the IANA database (2025b on the JDK I ran this on); PostgreSQL bundles its own; your OS has a third. They drift. When Java and PostgreSQL are on different tzdata versions, they will resolve recently-changed zones differently.

Check what you have:

ZoneRulesProvider.getVersions("Europe/London").lastKey();  // 2025b

SELECT name, utc_offset, is_dst FROM pg_timezone_names WHERE name = 'Europe/London';

Pin tzdata in your base images, and treat a tzdata bump as a deployment that requires recomputing cached future instants.

Part 4: Wiring Java to PostgreSQL

The mapping table

Per the pgJDBC documentation:

Note the omission, in the driver’s own words:

ZonedDateTime, Instant and OffsetTime / TIME WITH TIME ZONE are not supported.

So don’t hand the driver an Instant and hope — depending on the driver version you’ll either get a Can’t infer the SQL type to use for an instance of java.time.Instant exception or undocumented behavior. Convert explicitly at the boundary instead:

// write
ps.setObject(1, instant.atOffset(ZoneOffset.UTC));
// read
Instant i = rs.getObject("occurred_at", OffsetDateTime.class).toInstant();

Note that reading a timestamptz gives you an OffsetDateTime normalized to UTC — the driver’s offset is always Z, because that’s what the backend holds. The offset carries no information. Convert straight to Instant and don’t be tempted to read meaning into it.

Avoid setTimestamp / getTimestamp

The java.sql.Timestamp overloads convert using the JVM default time zone unless you pass an explicit Calendar. That makes your persistence layer’s correctness depend on the container’s TZ environment variable. Use the java.time setObject/getObject methods instead — they’re unambiguous.

If you must keep the JVM zone from mattering at all, set it explicitly at startup:

-Duser.timezone=UTC

Belt and braces, not a substitute for correct types.

Precision: Java has nanos, PostgreSQL has micros

Instant.parse("2026-08-15T10:00:00.123456789Z")           // .123456789
    .truncatedTo(ChronoUnit.MICROS)                        // .123456

PostgreSQL stores microseconds. Those last three digits are gone on the round trip, and PostgreSQL may round rather than truncate:

SELECT '2026-08-15 10:00:00.123456789'::timestamptz;  -- 10:00:00.123457

If you have an equality test or an optimistic-lock check comparing an in-memory Instant to one that’s been through the database, truncate to micros before you persist so both sides agree.

Don’t wrap the column in a function

Because timestamptz is stored as UTC, “give me everything that happened on 1 Feb in New York” tempts you into this:

EXPLAIN SELECT count(*) FROM events
WHERE (occurred_at AT TIME ZONE 'America/New_York')::date = DATE '2026-02-01';
--  Seq Scan on events

Index gone. Compute the boundary instants instead and do a half-open range scan:

SELECT (DATE '2026-02-01' + time '00:00') AT TIME ZONE 'America/New_York',  -- 2026-02-01 05:00+00
       (DATE '2026-02-02' + time '00:00') AT TIME ZONE 'America/New_York';  -- 2026-02-02 05:00+00
EXPLAIN SELECT count(*) FROM events
WHERE occurred_at >= '2026-02-01 05:00:00+00'
  AND occurred_at <  '2026-02-02 05:00:00+00';
--  Index Only Scan using events_occurred_at_idx

Note that this “day” is 24 hours only because February has no DST transition. On a transition day it’s 23 or 25 — which the boundary-instant approach handles correctly and a naive + interval ‘24 hours’ does not. Half-open ranges (>= and <) also dodge the microsecond-boundary problem that BETWEEN creates.

Part 5: JPA and Hibernate

Hibernate 6 made zoned types a first-class concern via TimeZoneStorageType:

For PostgreSQL, the practical consequence is settled by the database, not the ORM: timestamptz discards the offset, so under DEFAULT your OffsetDateTime round-trips as UTC. Which is fine — as long as you expected it.

Sensible defaults:

spring:
  jpa:
    properties:
      hibernate:
        jdbc:
          time_zone: UTC
        timezone:
          default_storage: NORMALIZE_UTC

And in the entity, be explicit about intent:

@Entity
public class Booking {
    
    // A moment. Maps to timestamptz.
    @Column(nullable = false)
    private Instant createdAt;
    
    // A date. Not a moment.
    @Column(nullable = false)
    private LocalDate serviceDate;
    
    // A wall-clock time that must not shift. Maps to timestamp.
    @Column(nullable = false)
    private LocalDateTime localStart;
    
    @Column(nullable = false)
    private String zoneId;   // 'Europe/London'
    
    public ZonedDateTime start() {
        return localStart.atZone(ZoneId.of(zoneId));
    }
}

If you genuinely need the user’s original offset preserved, @TimeZoneStorage(TimeZoneStorageType.COLUMN) with @TimeZoneColumn writes it to a companion column. Use it when the offset is data — an audit trail of what the user’s device claimed — not as a default.

Part 6: Testing This Stuff

Datetime bugs are only cheap if you catch them before the clocks change. Three habits do most of the work.

1. Inject a Clock

Instant.now() scattered through business logic is untestable. Inject java.time.Clock and you can move time at will:

@Bean Clock clock() { return Clock.systemUTC(); }
// in a test
Clock fixed = Clock.fixed(Instant.parse("2026-10-25T00:30:00Z"), ZoneOffset.UTC);

2. Run CI in a hostile time zone

If your JVM, your database, and your CI runner are all UTC, every zone bug hides until production. Force one of them somewhere awkward:

-Duser.timezone=Pacific/Chatham

+12:45 and it observes DST. If your test suite survives Chatham, it will survive most things. Do the same for the PostgreSQL container:

@Container
static PostgreSQLContainer<?> pg = new PostgreSQLContainer<>("postgres:16")
        .withEnv("TZ", "Asia/Kathmandu")
        .withUrlParam("options", "-c TimeZone=Asia/Kathmandu");

The point isn’t that production runs there — it’s that a test which only passes in UTC is a test that has proven nothing about zone handling.

3. Write the four transition tests

For any code that converts between local and instant, pin these explicitly:

static final ZoneId LONDON = ZoneId.of("Europe/London");
@Test void gapTimesAreRejectedNotSilentlyShifted() {
    LocalDateTime gap = LocalDateTime.of(2026, 3, 29, 1, 30);
    assertThat(LONDON.getRules().getValidOffsets(gap)).isEmpty();
    assertThatThrownBy(() -> scheduler.schedule(gap, LONDON))
        .isInstanceOf(NonExistentLocalTimeException.class);
}
@Test void overlapTimesResolveToTheDocumentedChoice() {
    LocalDateTime overlap = LocalDateTime.of(2026, 10, 25, 1, 30);
    assertThat(LONDON.getRules().getValidOffsets(overlap)).hasSize(2);
    assertThat(scheduler.resolve(overlap, LONDON))
        .isEqualTo(Instant.parse("2026-10-25T00:30:00Z")); // earlier, by policy
}
@Test void dailyRecurrenceKeepsWallClockAcrossDst() {
    ZonedDateTime start = ZonedDateTime.of(2026, 3, 28, 9, 0, 0, 0, LONDON);
    assertThat(recurrence.next(start).toLocalTime()).isEqualTo(LocalTime.of(9, 0));
}
@Test void instantSurvivesTheDatabaseRoundTrip() {
    Instant original = Instant.now().truncatedTo(ChronoUnit.MICROS);
    repository.save(new Event(original));
    assertThat(repository.findLatest().occurredAt()).isEqualTo(original);
}

The fourth one catches more real bugs than you’d expect — it’s the one that fails when someone quietly changes a column from timestamptz to timestamp.

The Short Version

If you skim one section, make it this one.

Schema

• timestamptz by default. It’s the same 8 bytes and it’s unambiguous.
• timestamp only for wall-clock times that must not shift — and store the zone ID beside it.
• date for dates. timetz for nothing.
• Pin timezone = ‘UTC’ in postgresql.conf and in the JDBC URL.

Java

• Instant for things that happened. LocalDate for dates. ZonedDateTime for scheduling. OffsetDateTime at the JDBC boundary.
• LocalDateTime is not a point in time. Treat every use as a question to answer, not an answer.
• Never accept zone abbreviations. Full IANA names only.
• plusDays ≠ plus(Duration.ofDays(1)). Know which one your product means.

The seam

• pgJDBC speaks LocalDate/LocalTime/LocalDateTime/OffsetDateTime. Convert Instant explicitly.
• Avoid setTimestamp/getTimestamp — they use the JVM default zone.
• Truncate to microseconds before persisting.
• Don’t wrap indexed timestamp columns in AT TIME ZONE; compute boundary instants instead.

And the one that bites hardest

Java resolves an ambiguous local time to the earlier offset. PostgreSQL picks the later one. Resolve ambiguity in exactly one place, deliberately, and pass instants across the boundary — never local times.

Store the instant, render the local time, and keep the zone rules in exactly one layer. Most datetime bugs are just that rule, broken somewhere.

All examples verified on OpenJDK 21.0.10 (tzdata 2025b) and PostgreSQL 16.13.

Sources

• PostgreSQL: Date/Time Types
• pgJDBC: Using Java 8 Date and Time classes
• Hibernate TimeZoneStorageType Javadoc
• Hibernate 6 migration guide
• Thorben Janssen: TimezoneStorageType

You type gradle build, wait a few seconds, and out comes a JAR. Most Java developers use this pipeline every day without ever looking inside it. But when a build gets slow, a dependency conflict appears, or a NoClassDefFoundError shows up in production at 2 AM, understanding the machinery underneath is the difference between guessing and fixing.

This article walks the full journey: Gradle’s three build phases, the Java plugin’s task graph, how dependency resolution actually works stage by stage, what a JAR file really is, and how the JVM reads and executes it.

Part 1: The Three Phases Every Gradle Build Goes Through

Before a single line of your code is compiled, Gradle itself runs through a fixed lifecycle of three phases. This is true for every build, every plugin, every project.

Phase 1 — Initialization

Gradle reads settings.gradle(.kts) and answers one question: which projects are part of this build? For a single-module app that’s trivial; for a multi-module monorepo this is where include(":core", “:api”, “:app”) gets evaluated and a Project object is created for each module.

Phase 2 — Configuration

Now every build.gradle(.kts) script executes top to bottom. This is the phase people misunderstand most. Your build script is code that runs — and it runs here, on every invocation, regardless of which task you asked for. The output of this phase is the task graph: a directed acyclic graph (DAG) of all tasks and their dependencies. Tasks are registered and wired together, but none of their actions execute yet.

A println at the top level of build.gradle prints during Configuration — even if you run gradle help. Task actions run later. This trips up nearly everyone once.

Phase 3 — Execution

Gradle takes the task you requested, computes the minimal subgraph of tasks needed to produce it, and executes them in dependency order. Tasks whose inputs and outputs haven’t changed since the last run are marked UP-TO-DATE and skipped entirely — this is Gradle’s incremental build engine, and it’s why the second build is always faster than the first.

Part 2: The Java Plugin Task Graph

Applying the java plugin registers a standard chain of tasks. When you run gradle build, this is the graph that gets executed:

The practical shortcuts worth memorizing:

# fastest feedback: compile only
gradle compileJava
# package without running tests
gradle jar
# full build, skip test execution
gradle build -x test
# nuke build/ and start clean
gradle clean build

Part 3: How Gradle Dependency Resolution Actually Works

This is the part of Gradle most developers treat as magic. You write three lines in a dependencies block, and somehow the right JARs appear on your classpath. Here’s the machinery, stage by stage.

Configurations: buckets of dependencies

Every dependency you declare goes into a named configuration — a bucket with specific rules about where those dependencies are visible:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web:3.3.1'
    api 'com.fasterxml.jackson.core:jackson-databind:2.17.1'
    compileOnly 'org.projectlombok:lombok:1.18.32'
    annotationProcessor 'org.projectlombok:lombok:1.18.32'
    runtimeOnly 'org.postgresql:postgresql:42.7.3'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.2'
}

The implementation vs api distinction matters in multi-module builds: implementation dependencies don’t appear on the compile classpath of modules that depend on yours. That means fewer recompilations when they change, and a cleaner API boundary. Default to implementation; reach for api only when a type from that dependency appears in your public method signatures.

The resolution stages

Declared dependencies are just coordinates on paper. Resolution is the process of turning them into actual files, and it happens lazily — only when a task first needs a classpath (typically compileJava during Execution). The stages:

Stage 1 — Graph construction. For each declared coordinate (group:name:version), Gradle queries your repositories in the order they’re declared and downloads only the metadata first: the POM file or Gradle Module Metadata. That metadata lists the dependency’s own dependencies, so Gradle recursively walks outward until the full transitive graph is known. No JARs have been downloaded yet — just descriptors.

Stage 2 — Conflict resolution. Real dependency graphs always contain the same library requested at different versions (your app wants Jackson 2.17, some transitive path wants 2.15). Gradle’s default strategy is highest version wins — unlike Maven, which picks the “nearest” declaration in the tree. This default is usually right, but you can override it:

configurations.all {
    resolutionStrategy {
        // hard-pin a version, overriding everything
        force 'com.fasterxml.jackson.core:jackson-databind:2.17.1'
        // or turn conflicts into build failures
        failOnVersionConflict()
    }
}

Stage 3 — Constraints and rules. Before the graph is finalized, Gradle applies platforms (BOMs), version constraints, exclusions, and dependency substitutions. This is how Spring Boot keeps hundreds of libraries version-aligned with one line:

dependencies {
    implementation platform('org.springframework.boot:spring-boot-dependencies:3.3.1')
    // now version numbers can be omitted — the BOM supplies them
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

Exclusions cut unwanted transitive branches at the declaration site:

implementation('org.springframework.boot:spring-boot-starter-web') {
    exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
}

Stage 4 — Artifact download. Only now, with the final graph settled, does Gradle download the actual JAR files — and only for modules that survived resolution. Everything lands in the shared cache at ~/.gradle/caches/modules-2, keyed by checksum, shared across all projects on your machine. A dependency is downloaded once, ever, per machine (dynamic versions like 1.+ and snapshots get re-checked periodically).

Stage 5 — Classpath assembly. The resolved files are ordered into a classpath and handed to whichever task requested them: compileClasspath to javac, runtimeClasspath to the test JVM, and so on.

Debugging resolution

Two commands answer 90% of “why is this version on my classpath” questions:

# full resolved tree per configuration
gradle dependencies --configuration runtimeClasspath
# trace one library: who pulls it in, which versions were requested,
# and why the winner won
gradle dependencyInsight --dependency jackson-databind

Part 4: What a JAR File Really Is

The output of the jar task is nothing exotic — it’s a ZIP archive with an agreed-upon internal layout. Rename it to .zip and any archive tool will open it:

myapp.jar
├── META-INF/
│   └── MANIFEST.MF          ← metadata
├── com/example/App.class     ← bytecode, path = package name
├── com/example/util/Helper.class
└── application.properties    ← resources sit alongside classes

The manifest is a plain-text key-value file. The line that matters most for a runnable JAR:

Manifest-Version: 1.0
Main-Class: com.example.App

One important caveat: the plain jar task packages only your classes. Your dependencies are not inside. For a self-contained deployable artifact you need a fat JAR — with the Shadow plugin, or Spring Boot’s bootJar, which nests dependency JARs and adds its own launcher.

plugins {
    id 'com.github.johnrengelman.shadow' version '8.1.1'
}
// gradle shadowJar → one JAR containing everything

Part 5: How the JVM Reads Your JAR

You run java -jar myapp.jar. Here’s the sequence, and it’s more interesting than it looks.

Step 1 — The launcher reads the manifest

The java launcher opens the JAR as a ZIP, reads META-INF/MANIFEST.MF, and extracts Main-Class. Note a classic gotcha: with -jar, any -cp argument on the command line is silently ignored. The JAR itself (plus manifest Class-Path entries) becomes the entire application classpath.

Step 2 — The classloader hierarchy

Classes are loaded by a chain of classloaders using parent-first delegation: every load request travels up to the top of the chain first, and only comes back down if no ancestor can satisfy it.

Step 3 — Lazy loading

The JVM does not load every class in the JAR at startup. A class is loaded the first time it’s actively used — instantiated, statically referenced, reflected upon. This is why a missing transitive dependency can let your app boot cleanly and then blow up with NoClassDefFoundError twenty minutes later, the first time a rarely-used code path runs.

Step 4 — Load, Link, Initialize

Per the JVM specification, every class goes through three phases before it’s usable:

1. Loading — the class bytes are read from the JAR, parsed, and a Class object is created in metaspace.
2. Linking — three sub-steps:
   • Verification: the bytecode is checked for structural and type safety (stack shapes, valid jumps, access rules).
   • Preparation: static fields are allocated and set to defaults — 0, null, false. Not your values yet.
   • Resolution: symbolic references to other classes, methods, and fields are resolved to concrete ones (often lazily).
3. Initialization — static initializer blocks and static field assignments run, in source order, exactly once, on first active use. This is the point where static { … } blocks fire.

Step 5 — main() and the JIT

Once Main-Class is loaded, linked, and initialized, the JVM invokes main(String[] args) on the main thread. Execution starts in the interpreter. As methods get hot — called thousands of times — the JIT compiler (tiered: C1 first for fast, lightly-optimized code, then C2 for aggressively optimized code) compiles them to native machine code. That’s why JVM applications famously get faster after warm-up.

The Whole Picture

src/main/java  ──javac──▶  build/classes  ──jar──▶  myapp.jar
                                                        │
                                             java -jar myapp.jar
                                                        │
                       read MANIFEST.MF → find Main-Class
                                                        │
                 classloader delegation (parent-first)
                                                        │
                 Load → Link (verify/prepare/resolve) → Init
                                                        │
                            main() runs, classes load lazily,
                            JIT compiles hot paths as you go

None of this is knowledge you need daily. But the day your build takes four minutes instead of forty seconds, or two versions of the same library fight on your classpath, or a class mysteriously fails to load in production — this is the map you’ll be reading. Better to have seen it before that day arrives.