DEV Community: Rabinarayan Patra

How to Set Up Sanity Studio in Next.js 16 (Embedded Dashboard)

Rabinarayan Patra — Thu, 04 Jun 2026 18:30:00 +0000

The default mental model for a headless CMS is two places: the CMS dashboard lives over there on the vendor domain, and your site lives over here on Vercel. Editors bounce between tabs, you copy environment variables between systems, and somebody always forgets to allowlist a domain in CORS.

Sanity does not require any of that. The Studio is a React app you ship inside your Next.js project. One catch-all route mounts the editor at /studio, your schemas live in TypeScript next to the rest of your code, and the whole thing deploys on the same Vercel push that ships your blog. This post walks through the full setup for Next.js 16: install, config, a real post + author + category schema, querying from a Server Component, the CORS fix every first-time user hits, and the Vercel deploy.

I built this exact integration into a small content site I run, and I will use that as the running example. If you already have a Next.js 16 app and want a working CMS dashboard inside it by the end of the next hour, you are in the right place.

What is Sanity Studio and why embed it in Next.js?

Sanity Studio is the editor UI that ships with Sanity, a hosted content platform that splits cleanly into two pieces: an open-source React app for editors, and a managed document store called the Content Lake. The Studio is the part you customize. The Lake is the part you query.

The reason to embed it in Next.js, instead of running it on the default sanity.studio subdomain, is that almost every project ends up wanting the same three things. Editors should sign in once on the same domain as the site. Schemas should live in TypeScript next to the components that render them. Deploys should be one Vercel push, not two. Embedding gets you all three for the cost of one catch-all route.

The latest stable release is sanity@5.30.0, with the official Next.js toolkit at next-sanity@13.0.11 as of June 2026. Both target the App Router and React 19, and Sanity migrated its own docs platform to Next.js 16 earlier this year, so the integration path is well-trodden.

What do you need before installing Sanity in Next.js 16?

You need a working Next.js 16 App Router project on Node 20 or newer, plus a free Sanity account. That is the entire prerequisite list.

Concretely:

Node 20+. The current Studio package drops support for Node 18 and 19. Check with node -v.
A Next.js 16 app on the App Router. Pages Router works too with a different route file, but this guide assumes App Router because that is what Next.js 16 starters default to.
A free Sanity account at sanity.io. The free tier gives you a project, a dataset, three editor seats, and 10k API requests per month, which is enough for a personal site.
A package manager. I use npm, but pnpm and yarn work without changes.

If you are starting from scratch, the rest of this guide assumes the same shape as a typical Next.js 16 app: a src/app directory, TypeScript on, Tailwind optional. The same steps apply if you keep app at the repo root.

How do you scaffold Sanity Studio inside an existing Next.js app?

Run npx sanity@latest init at the root of your Next.js project, then install the Next.js bridge package separately. The init command creates the Sanity project on the server, writes a starter sanity.config.ts, and adds a sanity/ directory with example schemas.

The full sequence from a clean Next.js 16 repo:

# 1. Provision the project and write starter config
npx sanity@latest init

# 2. Install the Next.js bridge and the image URL helper
npm install next-sanity @sanity/image-url

When sanity init runs, it walks you through a short CLI prompt:

Sign in with email, GitHub, or Google (browser tab opens).
Pick "Create new project" and give it a name.
Pick production as the default dataset.
Choose "Yes" when it asks to add the example schema (you will replace it shortly).
Pick TypeScript and the npm package manager when prompted.

The CLI prints two values at the end: a project ID (an eight-character string) and a dataset name (production). Drop them into .env.local exactly as they are:

# .env.local
NEXT_PUBLIC_SANITY_PROJECT_ID=your_project_id
NEXT_PUBLIC_SANITY_DATASET=production
SANITY_API_READ_TOKEN=optional_for_drafts

The NEXT_PUBLIC_ prefix is required. The Studio runs in the browser and needs to read both values from process.env at build time. The third variable is only needed later if you want the public site to render unpublished drafts for previews.

How do you wire the embedded Studio route at /studio?

Create two files: sanity.config.ts at the project root, and a catch-all route at app/studio/[[...tool]]/page.tsx. The route imports the config and hands it to the NextStudio component, which does the actual rendering.

The config file is where you declare the project ID, dataset, base path, plugins, and your schema list. A minimal version for a blog looks like this:

// sanity.config.ts
import { defineConfig } from 'sanity';
import { structureTool } from 'sanity/structure';
import { visionTool } from '@sanity/vision';
import { schemaTypes } from './sanity/schemaTypes';

export default defineConfig({
  name: 'default',
  title: 'My Blog Studio',
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  basePath: '/studio',
  plugins: [structureTool(), visionTool()],
  schema: { types: schemaTypes },
});

Two things matter here. basePath: '/studio' tells the Studio where it is mounted, so internal links point at /studio/structure/post and not the root. plugins always includes structureTool() (the document list and editor) and, for development, visionTool() (a GROQ query playground).

The route file is short. It imports the config, exports the metadata and viewport that next-sanity already prepared, and renders the Studio:

// app/studio/[[...tool]]/page.tsx
import { NextStudio } from 'next-sanity/studio';
import config from '../../../sanity.config';

export const dynamic = 'force-static';
export { metadata, viewport } from 'next-sanity/studio';

export default function StudioPage() {
  return <NextStudio config={config} />;
}

force-static makes the route itself a static shell. The Studio is a heavy client bundle and there is no benefit to re-rendering the shell on every request. The actual editor work happens client-side once the shell ships.

Once these two files exist, start the dev server with npm run dev and open http://localhost:3000/studio. The Studio loads, asks you to sign in, and then shows the document list. Right now the list is empty because you have not defined any schema types yet.

Source: Sanity Learn: Day one with Sanity Studio

The screenshot above is from the official Sanity learn course, showing the Studio chrome and the document creation menu populated by schema types. Once you add the schemas in the next section, your menu will show Post, Author, and Category in place of those examples.

This three-layer architecture is the part that makes the embedded approach worthwhile. The same browser session talks to two Next.js routes that talk to the same Sanity project, with the editor on the write path and the public pages on the read path:

How do you write a real content schema (post + author + category)?

Create a sanity/schemaTypes/ directory with one file per document type, then export them as an array from sanity/schemaTypes/index.ts. Each file describes the shape of one document using the defineType and defineField helpers from the sanity package.

For a blog you want three documents. A post holds the article. An author holds the person who wrote it. A category groups posts. Posts reference authors and categories, so editors fill in those fields with a dropdown instead of free text.

Start with post.ts:

// sanity/schemaTypes/post.ts
import { defineField, defineType } from 'sanity';

export const post = defineType({
  name: 'post',
  title: 'Post',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      type: 'string',
      validation: (r) => r.required().max(80),
    }),
    defineField({
      name: 'slug',
      type: 'slug',
      options: { source: 'title', maxLength: 96 },
      validation: (r) => r.required(),
    }),
    defineField({ name: 'author', type: 'reference', to: [{ type: 'author' }] }),
    defineField({
      name: 'category',
      type: 'reference',
      to: [{ type: 'category' }],
    }),
    defineField({
      name: 'mainImage',
      type: 'image',
      options: { hotspot: true },
      fields: [{ name: 'alt', type: 'string', title: 'Alt text' }],
    }),
    defineField({ name: 'publishedAt', type: 'datetime' }),
    defineField({ name: 'body', type: 'blockContent' }),
  ],
});

A few choices worth flagging. validation: r => r.required().max(80) runs in the Studio in real time, so editors see the red warning the moment a title is empty or too long. options: { source: 'title' } on the slug field wires up the "Generate" button, which converts the title to a URL slug. options: { hotspot: true } on the image field lets editors pick a focal point so Sanity can crop responsively without cutting off heads.

author.ts and category.ts are smaller:

// sanity/schemaTypes/author.ts
import { defineField, defineType } from 'sanity';

export const author = defineType({
  name: 'author',
  title: 'Author',
  type: 'document',
  fields: [
    defineField({ name: 'name', type: 'string', validation: (r) => r.required() }),
    defineField({
      name: 'slug',
      type: 'slug',
      options: { source: 'name' },
      validation: (r) => r.required(),
    }),
    defineField({ name: 'avatar', type: 'image', options: { hotspot: true } }),
    defineField({ name: 'bio', type: 'text', rows: 3 }),
  ],
});

// sanity/schemaTypes/category.ts
import { defineField, defineType } from 'sanity';

export const category = defineType({
  name: 'category',
  title: 'Category',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string', validation: (r) => r.required() }),
    defineField({
      name: 'slug',
      type: 'slug',
      options: { source: 'title' },
      validation: (r) => r.required(),
    }),
    defineField({ name: 'description', type: 'text', rows: 2 }),
  ],
});

The blockContent type that the post body uses is the portable text format Sanity ships for rich text. It is a one-line export:

// sanity/schemaTypes/blockContent.ts
import { defineType } from 'sanity';

export const blockContent = defineType({
  name: 'blockContent',
  title: 'Block Content',
  type: 'array',
  of: [{ type: 'block' }, { type: 'image', options: { hotspot: true } }],
});

The index file wires them together:

// sanity/schemaTypes/index.ts
import { post } from './post';
import { author } from './author';
import { category } from './category';
import { blockContent } from './blockContent';

export const schemaTypes = [post, author, category, blockContent];

Reload http://localhost:3000/studio. The Studio picks up the new types and the document list now shows Post, Author, and Category. Create one of each. The reference fields will let you link a post to the author and category you just made.

Source: Sanity Learn: Day one with Sanity Studio

This is what the editor looks like for a real document: the list pane on the left, the document with its declared fields on the right, drafts and publish state at the top. With the schema above, your screen looks the same shape, with your post fields in place of the Name shown here.

How do you query Sanity content from a Server Component?

Create a thin client wrapper at lib/sanity/client.ts, then import it from any Server Component that needs to render content. The client uses GROQ, Sanity's query language, which feels like JSON Path with projections.

The wrapper is short:

// lib/sanity/client.ts
import { createClient } from 'next-sanity';

export const sanityClient = createClient({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  apiVersion: '2026-06-01',
  useCdn: true,
});

export const allPostsQuery = `*[_type == "post"] | order(publishedAt desc) {
  _id,
  title,
  "slug": slug.current,
  publishedAt,
  "author": author->name,
  "category": category->title
}`;

A few specifics. apiVersion is a calendar date that pins query behavior, so a Sanity-side change does not silently alter your responses. Update it when you adopt a new feature. useCdn: true reads from the public CDN, which is fast and free for published content. Set it to false for draft previews where you want fresh data.

GROQ itself is compact. *[_type == "post"] filters every document by type. The | pipe sorts. The projection block at the end picks fields and rewrites them: "slug": slug.current flattens the slug object to a string, and "author": author->name follows the reference and pulls the author's name in one query.

A Server Component that lists posts is then just:

// app/blog/page.tsx
import { sanityClient, allPostsQuery } from '@/lib/sanity/client';

type PostRow = {
  _id: string;
  title: string;
  slug: string;
  publishedAt: string;
  author: string;
  category: string;
};

export default async function BlogIndexPage() {
  const posts = await sanityClient.fetch<PostRow[]>(allPostsQuery);
  return (
    <ul>
      {posts.map((p) => (
        <li key={p._id}>
          <a href={`/blog/${p.slug}`}>{p.title}</a>
          <span>
            {' '}
            by {p.author} in {p.category}
          </span>
        </li>
      ))}
    </ul>
  );
}

This is a Server Component, so the query runs at request time on Vercel, not in the browser. The response is HTML by the time it reaches the user. For static caching, swap to Cache Components with 'use cache' and a cacheTag keyed off post, and trigger revalidation from a Sanity webhook on publish.

How do you configure CORS so the Studio talks to your project?

Open manage.sanity.io, pick your project, go to API , scroll to CORS origins , and add every origin where the embedded Studio will run. Each entry needs the "Allow credentials" toggle turned on.

The minimum allowlist for a Vercel-hosted Next.js app is three rows:

Origin	When it matters	Allow credentials
`http://localhost:3000`	Local dev	ON
`https://www.your-domain.com`	Production	ON
`https://preview-*.your-domain.vercel.app`	Vercel preview URLs	ON

The reason "Allow credentials" must be ON is that the embedded Studio sends the Sanity editor session cookie on every API call. Without that toggle, the browser strips the cookie before sending the request, Sanity sees an anonymous call, and you get a blank Studio with a console error like CORS policy: No 'Access-Control-Allow-Credentials' header is present on the requested resource. It is the single most common failure when first setting up the embedded Studio.

Restart npm run dev after adding the localhost entry. The dev server picks up the new CORS allowance on the next page load, and the Studio finishes mounting instead of stalling on the login screen.

How do you deploy the embedded Studio to Vercel?

Add the two NEXT_PUBLIC_SANITY_* env vars to your Vercel project, push the branch, and the embedded Studio is reachable at your-domain.com/studio as soon as the deploy goes green. There is no separate Sanity build step.

The full Vercel checklist:

Environment variables. In the Vercel dashboard, go to your project, then Settings , then Environment Variables. Add NEXT_PUBLIC_SANITY_PROJECT_ID and NEXT_PUBLIC_SANITY_DATASET for all three environments (Production, Preview, Development). Add SANITY_API_READ_TOKEN only if you wired the draft preview flow.
CORS for production and preview URLs. Back in manage.sanity.io, make sure both https://www.your-domain.com and https://*-your-team.vercel.app are in the CORS allowlist with credentials on. Preview URLs change per commit, so the wildcard saves you from re-adding them on every branch.
Push. The next push triggers a Vercel build. The build compiles the Studio bundle as part of the Next.js build and ships it as a static route, so cold starts are not part of the editor experience.
Test the editor. Open https://www.your-domain.com/studio, sign in, create a document, and confirm the content shows up on the public route.

You can skip the hosted sanity.studio deployment entirely. That product is useful when you want the editor on a different domain from the marketing site (for example, when the marketing site is on a different stack), but for a single Next.js app, the embedded route is fewer moving parts.

What are the common pitfalls in a Next.js 16 + Sanity setup?

Most first-run problems come from four places: missing env vars at build time, missing CORS entries, the wrong apiVersion, and treating the Studio as a normal Next.js route.

In order of how often I have hit them:

process.env.NEXT_PUBLIC_SANITY_PROJECT_ID is undefined in production. Vercel does not read .env.local. Set the variables in the dashboard with the NEXT_PUBLIC_ prefix exactly, then redeploy. A redeploy is required for env changes to take effect.
CORS blank screen on preview URLs. Vercel preview URLs change per branch. Add https://*-your-team.vercel.app once instead of one entry per branch.
Stale data after publishing. If you have ISR or Cache Components on the read path, publish events do not invalidate them automatically. Wire a Sanity webhook to a Next.js route that calls revalidateTag or updateTag on publish.
Studio is wrapped in your site layout. The catch-all route under app/studio/[[...tool]]/page.tsx inherits any layout above it. If your root layout adds a navbar or padding, the Studio renders inside it. Wrap the Studio route in its own segment with a layout that returns the children as-is, so the editor takes the full viewport.

If you build the site on the same Next.js 16 stack I write about, you have probably already seen related setups in the proxy.ts post about routing middleware and the docs generator post about content-driven pages. The Sanity Studio embed is the read/write half of the same problem those posts cover from the routing and rendering sides.

What did we just build?

A real CMS dashboard at /studio inside a Next.js 16 app, backed by a typed schema for posts, authors, and categories, queried from Server Components, with CORS configured for local and production, deployed on the same Vercel build as the public site. No extra infrastructure, no second domain, no separate auth flow. The whole thing fits in two config files, one route, and a sanity/ directory.

The next step depends on what you ship next. If editors will write drafts you want to preview before publishing, set up the Presentation tool and a draft-mode route on the Next.js side. If you want to render rich text from the body field, install @portabletext/react and write a custom renderer for your design system. If you want full-text search, add searchTool to the plugins list and you get a search bar in the Studio header for free.

For reference, the primary docs I used while writing this are the official Next.js integration guide, the embedding Sanity Studio doc, the Sanity Studio installation requirements, the next-sanity toolkit on GitHub, and the Sanity platform changelog covering the Next.js 16 migration. The Studio screenshots in this post are from the Day One with Sanity Studio learn course on the Sanity site.

Keep Reading

How to Version REST APIs in Spring Framework 7 (Spring Boot 4)

Rabinarayan Patra — Tue, 02 Jun 2026 18:30:00 +0000

For years, versioning a Spring REST API meant picking your own poison. Custom interceptors, duplicate controllers, or a pile of headers= conditions on every mapping. Spring Framework 7, the core of Spring Boot 4, ends that. Versioning is now a first-class feature baked into request mapping.

I rebuilt a multi-version API on Spring Boot 4 last month and deleted about 300 lines of routing glue in the process. This guide is the playbook I wish I'd had: every strategy, real controller code, a curl trace per approach, and the deprecation headers that tell clients when to move on.

What changed for API versioning in Spring Framework 7?

Spring Framework 7 added a version attribute to @RequestMapping and every shortcut variant, so one path can fan out to multiple handlers by version. Before this, request mapping had no concept of a version at all. You bolted versioning on from the outside with interceptors or separate controller classes per release.

The new model has three moving parts. A resolver pulls the version out of the request. A parser turns that raw string into a comparable semantic version. A strategy matches it against the version declared on each mapping and picks the closest handler. All three are configurable, and the defaults cover the common cases.

Here's the smallest possible example. Same path, two versions, two methods:

@RestController
@RequestMapping("/accounts")
public class AccountController {

    @GetMapping(path = "/{id}", version = "1.0")
    public AccountV1 getAccountV1(@PathVariable Long id) {
        return accountService.findV1(id);
    }

    @GetMapping(path = "/{id}", version = "2.0")
    public AccountV2 getAccountV2(@PathVariable Long id) {
        return accountService.findV2(id);
    }
}

A request for version 1.0 hits the first method. A request for 2.0 hits the second. No if checks, no manual parsing, no shared dispatcher method. The version is part of the mapping, exactly like the path and the HTTP method.

How do you turn on API versioning in Spring Boot 4?

You turn on versioning by implementing WebMvcConfigurer and overriding configureApiVersioning, which hands you an ApiVersionConfigurer. Nothing routes by version until you declare which resolver to use. The version attribute on a mapping is inert without a configured strategy.

@Configuration
public class ApiVersioningConfig implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useRequestHeader("X-API-Version")
                  .addSupportedVersions("1.0", "2.0");
    }
}

That's the entire wiring for header-based versioning. useRequestHeader names the header to read. addSupportedVersions declares the versions you accept, which lets Spring reject anything unknown with a clean 400 instead of a confusing 404.

If you'd rather stay in properties, Spring Boot 4 exposes the same switch:

spring.mvc.apiversion.use.header=X-API-Version

By default a version is required. A request with no version triggers MissingApiVersionException and a 400 response. An unsupported version triggers InvalidApiVersionException, also a 400. You can relax both, and I'll cover that under pitfalls, because the default trips up first-time users.

How does the version attribute route requests?

The version attribute routes a request by comparing the resolved request version against the version declared on each candidate mapping, then choosing the best match. Spring parses both sides with SemanticApiVersionParser, which reads major.minor.patch and fills missing parts with zero. So "1" becomes 1.0.0 and "1.2" becomes 1.2.0.

Matching is not a naive string equality. If a request asks for 1.5 and your handlers declare 1.0 and 2.0, the request resolves to the highest version less than or equal to 1.5, which is 1.0. That single rule is what makes baseline versioning work, and it's why you don't need a handler for every point release.

The flow is the same no matter which strategy you choose. Only the first box, the resolver, changes. Pick where the version lives in the request and the rest of the pipeline stays identical.

Which versioning strategy should you pick?

Spring Framework 7 ships four resolver strategies, and you choose one with a single method on ApiVersionConfigurer. Each reads the version from a different place in the request. The handler code never changes. Only the config line and the way clients call you differ.

Request header

Header versioning keeps the URL clean and puts the version in a custom header. This is my default for service-to-service APIs.

configurer.useRequestHeader("X-API-Version")
          .addSupportedVersions("1.0", "2.0");

curl -H "X-API-Version: 2.0" http://localhost:8080/accounts/42

Path segment

Path-segment versioning puts the version directly in the URL, which makes it visible, bookmarkable, and easy to route at a proxy. You declare which segment holds the version by index and add a URI variable for it in the mapping.

configurer.usePathSegment(1)
          .addSupportedVersions("1.0", "2.0");

@GetMapping(path = "/api/{version}/accounts/{id}", version = "2.0")
public AccountV2 getAccount(@PathVariable Long id) {
    return accountService.findV2(id);
}

curl http://localhost:8080/api/2.0/accounts/42

Segment index is zero-based against the path. In /api/2.0/accounts/42 the segments are api, 2.0, accounts, 42, so the version sits at index 1.

Query parameter

Query-parameter versioning reads the version from the query string. It's trivial to test in a browser and trivial to forget in a cache key, so weigh that tradeoff.

configurer.useQueryParam("version")
          .addSupportedVersions("1.0", "2.0");

curl "http://localhost:8080/accounts/42?version=2.0"

Media type

Media-type versioning reads a parameter off the Accept header, which is the most REST-purist option and the hardest for casual clients to send.

configurer.useMediaTypeParameter(MediaType.APPLICATION_JSON, "version")
          .addSupportedVersions("1.0", "2.0");

curl -H "Accept: application/json;version=2.0" http://localhost:8080/accounts/42

My rule of thumb: header for internal APIs, path segment for public APIs where humans read the URLs, and skip query and media type unless you have a specific reason. The worst choice is no choice, where different endpoints use different strategies and clients can't predict which one applies.

What's the difference between fixed and baseline versions?

A fixed version matches one exact version, while a baseline version matches that version and everything above it until a higher handler takes over. You write a fixed version as "1.2" and a baseline version with a trailing plus, "1.2+". The difference is how many releases a single handler is responsible for.

Picture an endpoint that hasn't changed since 1.0 and another that got a new shape in 2.0:

@RestController
@RequestMapping("/accounts")
public class AccountController {

    @GetMapping(path = "/{id}", version = "1.0+")
    public AccountV1 getAccount(@PathVariable Long id) {
        return accountService.findV1(id);
    }

    @PostMapping(version = "2.0+")
    public AccountV2 createAccount(@RequestBody CreateAccount body) {
        return accountService.createV2(body);
    }
}

The GET handler answers 1.0, 1.5, 1.9, and anything up to the next declared version. The POST handler owns 2.0 and up. You only write a new method when the contract actually changes, not on every version bump. That's the whole point of baseline matching, and it's why a real API with ten releases might have three or four handlers per route instead of ten.

Fixed versions still matter. Use them when a single release introduced a breaking change you want pinned to one exact handler, so a typo in a client's version string fails loudly instead of silently falling through to an older shape.

How do you deprecate an API version with Sunset headers?

You deprecate a version by registering a StandardApiVersionDeprecationHandler and configuring a deprecation date, a sunset date, and a migration link per version. Spring then attaches three response headers to every matching request: Deprecation from RFC 9745, Sunset from RFC 8594, and a Link pointing at your migration docs. Clients that watch for these headers learn a version is going away without reading your changelog.

@Configuration
public class ApiVersioningConfig implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        StandardApiVersionDeprecationHandler handler =
                new StandardApiVersionDeprecationHandler();

        handler.configureVersion("1.0")
               .setDeprecationDate(ZonedDateTime.parse("2026-06-01T00:00:00Z"))
               .setSunsetDate(ZonedDateTime.parse("2026-12-01T00:00:00Z"))
               .setSunsetLink(URI.create("https://api.example.com/docs/migrate-to-2.0"));

        configurer.useRequestHeader("X-API-Version")
                  .addSupportedVersions("1.0", "2.0")
                  .setDeprecationHandler(handler);
    }
}

Now a call to the deprecated version carries the warning in its response:

curl -i -H "X-API-Version: 1.0" http://localhost:8080/accounts/42

HTTP/1.1 200 OK
Deprecation: Mon, 01 Jun 2026 00:00:00 GMT
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://api.example.com/docs/migrate-to-2.0>; rel="sunset"
Content-Type: application/json

The version still works. Deprecation is a signal, not a shutdown. When the sunset date passes and you're confident traffic has moved, you drop the 1.0 handler and remove "1.0" from the supported versions. Clients that ignored the headers get a clean 400, and you have the access logs to prove you warned them.

How was this done before Spring 7?

Before Spring 7 you versioned by hand, and every approach had a sharp edge. The most common pattern was duplicate controllers, one class per version, wired to different base paths:

@RestController
@RequestMapping("/v1/accounts")
public class AccountControllerV1 { /* ... */ }

@RestController
@RequestMapping("/v2/accounts")
public class AccountControllerV2 { /* ... */ }

That works until you have twenty endpoints across four versions and a bug fix has to land in three of them. The other common hack abused the headers condition on a mapping:

@GetMapping(path = "/accounts/{id}", headers = "X-API-Version=1")
public AccountV1 getV1(@PathVariable Long id) { /* ... */ }

String equality only. No 1.0 versus 1 normalization, no baseline ranges, no 1.5 falling back to 1.0. You hand-rolled every comparison. Teams that wanted real semantics wrote a custom HandlerInterceptor to parse and validate versions, then threaded the result through ThreadLocal or request attributes. It was a lot of code to maintain, and it lived nowhere near the mappings it controlled.

The built-in approach wins on every axis I care about. Versioning lives on the mapping where you can see it, comparison is semantic, baseline matching cuts handler count, and deprecation headers come free. The 300 lines I deleted were exactly this kind of glue.

What pitfalls should you watch for?

The first pitfall is the required-version default, which surprises everyone. A request with no version returns a 400, not your newest handler. If you want missing versions to fall back instead of failing, set a default and mark versions optional:

configurer.useRequestHeader("X-API-Version")
          .addSupportedVersions("1.0", "2.0")
          .setVersionRequired(false)
          .setDefaultVersion("2.0");

With setVersionRequired(false) and no default, Spring falls back to the most recent supported version, which may not be what you want during a migration. Always pair optional versions with an explicit setDefaultVersion so the fallback is a decision, not an accident.

The second pitfall is supported-version detection. By default Spring initializes the supported set from the versions it finds on your controller mappings, so a typo like version = "20" silently becomes a supported version. If you want a locked allowlist, call detectSupportedVersions(false) and declare every version with addSupportedVersions yourself. I do this on public APIs so nothing ships a version by accident.

The third pitfall is OpenAPI tooling. As of mid-2026, springdoc support for the new version attribute is still catching up, so two handlers on the same path can confuse schema generation. Until your springdoc version understands the version dimension, group your docs per version or document the version header manually in your OpenAPI config. Test your generated spec before you assume it rendered both versions.

The last one is strategy drift. Once you pick a resolver, every endpoint must use it. A header-versioned API with one path-versioned endpoint will route inconsistently and break client SDKs that assume one scheme. Decide the strategy at the start of the project and enforce it in review.

Is built-in versioning worth migrating to?

Yes, and it changes how you think about API evolution, not just how you wire it. When adding a version is one attribute and one method, you stop dreading breaking changes and start shipping them cleanly, because the cost of carrying an old contract next to a new one dropped to almost nothing. That's the real shift in Spring Framework 7. The mechanics are simple. The freedom they buy is the point.

Start with header versioning and a required version on a single endpoint. Add a 2.0 handler with a baseline range. Wire a deprecation handler with a sunset date six months out. Once that loop feels natural, you'll version everything this way and wonder how you tolerated the interceptor era.

For the authoritative details, read the official Spring blog announcement on API versioning and the Spring Framework reference on MVC API versioning. For the header semantics, see RFC 9745 (Deprecation) and RFC 8594 (Sunset).

Keep Reading

How to Configure CORS in Spring Boot. Get cross-origin headers right before you expose a versioned API.
How to Test Spring Boot with Testcontainers. Write integration tests that exercise each API version against a real database.
Spring Security's Component Revolution. Secure the versioned endpoints you just built.
Modern Java with Spring Boot. The language features that make Spring Boot 4 controllers cleaner.

How to Set Up an SSH Tunnel for Local Database Access

Rabinarayan Patra — Thu, 28 May 2026 18:30:00 +0000

The single fastest way to wake up to a ransom note is to expose your Postgres port directly to the public internet. The second fastest is to think you can secure it with a strong password and call it a day.

I have run point on database access for production systems at three different companies. Every single one of them had at least one engineer at some point ask if we could "just open 5432 to my IP" so they could pull a quick report from DBeaver. The answer is always no. The right answer is an SSH tunnel, and once you have done it twice, it takes about 15 seconds to set up.

This post is the practical guide I wish I had given that engineer the first time. We will cover the command, the GUI client setup for the four databases I touch most often, the autossh recipe that keeps the tunnel alive through laptop sleeps and network changes, and the small set of mistakes that bite people in production. If you want the deeper context on why exposing database ports is bad even with strong auth, I covered that in my zero-trust microservices post, and the connection pooling tradeoffs once you are inside the tunnel show up in my pgbouncer survival guide.

What is an SSH tunnel and why use it for database access?

An SSH tunnel for database access forwards a local TCP port on your laptop through an authenticated SSH session to a remote host, which then opens a connection to the actual database. Your database client connects to localhost and never knows anything else exists. All traffic rides inside the encrypted SSH channel.

The shape of it looks like this.

This pattern wins on five things at once.

No exposed database port. The database listens only on its private network. The bastion is the only thing on the public internet, and it only speaks SSH.

No firewall holes per developer. Every engineer goes through the same bastion. You add or remove access by adding or removing SSH keys, not by editing security group rules.

Audit trail. Every connection logs through SSH and through the bastion's auth.log. You know who connected, from where, when.

Works with every client. psql, DBeaver, TablePlus, DataGrip, mysql, redis-cli, mongosh. They all just see localhost. No driver-level config needed.

Encrypted in transit by default. Even if your database speaks plaintext on the wire (looking at you, Redis), the tunnel carries it under SSH.

The one thing it does not give you is high availability. The tunnel is a long-lived TCP connection between exactly two hosts. If your bastion goes down, your tunnel goes with it. That is fine for ad-hoc developer access. It is not fine for application traffic. Application traffic belongs on a private network or a managed bastion service like AWS Session Manager.

How do you set up a local port forward to a remote Postgres?

The full command is one line.

ssh -L 5433:dbhost.internal:5432 ec2-user@bastion.example.com

Read it left to right.

-L 5433:dbhost.internal:5432 says forward local port 5433 on this laptop, through the SSH connection, to dbhost.internal:5432 resolved from the bastion's perspective.
ec2-user@bastion.example.com is the SSH connection itself.

While that command is running, anything on your laptop that connects to localhost:5433 ends up talking to the Postgres on dbhost.internal:5432. Close the terminal or hit Ctrl+C and the tunnel dies.

I deliberately use 5433 on the local side instead of 5432. If you happen to have Postgres running locally for development, you do not want to clobber it. Pick a high port that does not collide.

To test the tunnel works without firing up a GUI, use psql from another terminal.

psql -h localhost -p 5433 -U app_user -d production

That -h localhost is the key. Without it, psql tries to connect via Unix socket and skips the tunnel entirely. I have lost 20 minutes to this twice.

Running the tunnel in the background

If you do not want a terminal sitting open, add -f -N and the command returns immediately while the tunnel keeps running.

ssh -f -N -L 5433:dbhost.internal:5432 ec2-user@bastion.example.com

-N means do not execute a remote command (we only want the forward).
-f means fork into the background after authentication.

To kill it later, find and stop the process.

pgrep -af "ssh.*5433:dbhost.internal"
kill <pid>

A tidier setup with `~/.ssh/config`

Typing that command every time gets old. Stash the whole thing in your SSH config.

# ~/.ssh/config
Host pg-prod
    HostName bastion.example.com
    User ec2-user
    IdentityFile ~/.ssh/keys/prod-bastion.pem
    LocalForward 5433 dbhost.internal:5432
    ServerAliveInterval 30
    ServerAliveCountMax 3
    ExitOnForwardFailure yes

Now the command is just ssh pg-prod, and you get a few useful behaviors for free.

ServerAliveInterval 30 sends a keepalive every 30 seconds so the tunnel does not die when your home router decides to drop idle connections.
ExitOnForwardFailure yes makes ssh fail fast if the forward cannot bind, instead of leaving you with a dead tunnel and no error.

For the background form, ssh -f -N pg-prod still works. The config entry is purely additive.

How do you connect from your GUI client through the tunnel?

With the tunnel running, every GUI client connects to localhost on the forwarded port. The only field that matters is the host. Everything else (username, password, database name) is the same as you would use against the real database.

In DBeaver, create a new Postgres connection and fill in:

Host: localhost
Port: 5433
Database: production
Username: app_user
Password: <your db password>

Hit Test Connection. If it works, you are good.

In TablePlus, same idea. Host is localhost, port is 5433.

In DataGrip, same. The driver does not know the tunnel exists, which is exactly the point.

DBeaver and DataGrip both have a built-in SSH tunnel option in their connection dialog. That works too. The advantage of using ssh on the command line instead is that you can share one tunnel across psql, DBeaver, a script, and a notebook at the same time. The advantage of the GUI option is that it dies cleanly when you close the client.

I default to the command line approach because I almost always have multiple things hitting the same database. Pick what fits your workflow.

How do you do the same for MySQL, Redis, and MongoDB?

The flag is identical. Only the port changes.

# MySQL
ssh -L 3307:dbhost.internal:3306 user@bastion

# Redis
ssh -L 6380:cache.internal:6379 user@bastion

# MongoDB
ssh -L 27018:mongohost.internal:27017 user@bastion

Then connect each client to localhost on the forwarded port.

mysql -h 127.0.0.1 -P 3307 -u app_user -p
redis-cli -h 127.0.0.1 -p 6380
mongosh "mongodb://app_user:secret@127.0.0.1:27018/production"

A few client-specific notes that catch people.

MySQL needs 127.0.0.1, not localhost. The mysql client tries to connect via Unix socket when you say localhost, just like psql does. Use the IP literal and you skip that.

Redis tunnels work great for debugging, badly for sustained throughput. Every command round-trips through the SSH session. Latency goes from 0.2 ms to 8-30 ms depending on your link. Fine for redis-cli MONITOR or one-off lookups. Wrong tool for ETL.

Mongo replica sets need extra care. A standalone mongod tunnels fine. A replica set will hand you back the internal hostnames of the other replicas during connection negotiation, and your client will then try to connect to those names directly. Either tunnel each replica on its own port and add them to your connection string, or set directConnection=true in the URI to disable replica discovery.

How do you keep the tunnel alive with autossh and systemd?

ssh -f -N works until your laptop goes to sleep, your wifi switches, or the bastion restarts. Then the tunnel dies silently and your next connection just hangs. The fix is autossh, which is a tiny wrapper that monitors the SSH process and restarts it when it drops.

Install it.

# macOS
brew install autossh

# Ubuntu / Debian
sudo apt install autossh

# Fedora / Rocky
sudo dnf install autossh

Run it the same way you ran ssh, with one extra port for autossh's own health check.

AUTOSSH_GATETIME=0 \
autossh -M 0 -f -N \
  -o "ServerAliveInterval 30" \
  -o "ServerAliveCountMax 3" \
  -o "ExitOnForwardFailure yes" \
  -L 5433:dbhost.internal:5432 \
  ec2-user@bastion.example.com

A few details that matter.

AUTOSSH_GATETIME=0 makes autossh restart immediately even if the first connection failed. Without it, autossh waits 30 seconds before retrying, which is annoying when you mis-typed the host.
-M 0 disables autossh's old monitoring port mechanism. We use the ServerAlive* SSH options instead, which work better through NATs and modern firewalls.

That command stays up through sleep, wake, and network changes. But it does not survive a reboot. For that, wrap it in a systemd user service.

The systemd user service

Create ~/.config/systemd/user/pg-tunnel.service.

[Unit]
Description=Autossh tunnel to production Postgres
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
Environment=AUTOSSH_GATETIME=0
ExecStart=/usr/bin/autossh -M 0 -N \
  -o "ServerAliveInterval 30" \
  -o "ServerAliveCountMax 3" \
  -o "ExitOnForwardFailure yes" \
  -o "ConnectTimeout 10" \
  -i /home/rabi/.ssh/keys/prod-bastion.pem \
  -L 5433:dbhost.internal:5432 \
  ec2-user@bastion.example.com
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

Notice the ExecStart does not use -f here. Systemd wants the process in the foreground so it can supervise it. The Restart=always line takes over from the -f background behavior.

Enable and start.

systemctl --user daemon-reload
systemctl --user enable --now pg-tunnel.service
systemctl --user status pg-tunnel.service

That last command should show active (running). If you want the service to start at boot (not just at login), enable user lingering once.

sudo loginctl enable-linger $USER

Logs are in journalctl.

journalctl --user -u pg-tunnel.service -f

On macOS, the same job goes into a launchd plist at ~/Library/LaunchAgents/com.rabi.pg-tunnel.plist. The shape is similar enough that I will skip the full XML, but the key entries are KeepAlive set to true and a ProgramArguments array that mirrors the autossh command above.

What are the common SSH tunnel mistakes to avoid?

I have made every one of these. So has everyone I have onboarded.

Binding the forward to 0.0.0.0 instead of 127.0.0.1. The default -L 5433:dbhost:5432 binds to localhost only. If you write -L *:5433:dbhost:5432, you have just opened your laptop's port 5433 to anyone on the same wifi network as you. They can now talk to your production Postgres. Do not do this. The local bind defaults to localhost for a reason.

Hardcoding production credentials in ~/.ssh/config. SSH config has no concept of secrets management. If you check your config into a dotfiles repo, that key path goes with it. Keep production keys outside the config-tracked area and reference them by absolute path from a directory that is gitignored.

Forgetting that ServerAliveInterval is client-side only. This tells your laptop to send keepalives. The bastion can still close the connection on its own idle timeout. If your bastion is AWS Systems Manager based or sits behind a corporate load balancer with a short idle, you also need to set keepalives at the server level (ClientAliveInterval in sshd_config). Otherwise your tunnel drops every five minutes and you do not know why.

Trusting the tunnel to give you encryption end-to-end. SSH encrypts the laptop-to-bastion segment. The bastion-to-database segment is in cleartext on your private network. For most production setups, that is fine because the private network is trusted. For sensitive workloads with stricter compliance requirements (PCI, HIPAA), insist on TLS on the database side too, even inside the VPC.

Tunneling through your jump host as root. The bastion is a public-facing box. The account that holds your tunnel should not also be the one with sudo rights. Use a dedicated low-privilege user for tunneling. Restrict it to command="false",no-shell in authorized_keys if you want to be paranoid, with a PermitOpen directive that limits which host:port combos this key can forward to.

The hardened authorized_keys line looks like this.

command="echo 'no shell',no-pty,no-agent-forwarding,no-X11-forwarding,permitopen="dbhost.internal:5432" ssh-ed25519 AAAA... rabi@laptop

That key can open exactly one forward, to exactly one host:port, and cannot execute a shell. If the key leaks, the attacker gets a tunnel to one database, not a shell on your bastion.

Letting the tunnel persist across job changes. This one is process, not technical. When an engineer leaves the team, their SSH keys come out of every bastion's authorized_keys. The keys are in your secrets manager and config-managed. Right? Right.

Using the same bastion for staging and production. I have seen this break twice. A misconfigured LocalForward ends up pointing your TablePlus at production while you think you are on staging. Use separate bastions, separate config entries with distinct host names like pg-prod and pg-stage, and color-code the connections in your client so you cannot confuse them visually.

What does the whole setup look like in 30 seconds?

For the reader who skipped to the end, here is the compressed version.

# One-off
ssh -f -N -L 5433:dbhost.internal:5432 user@bastion
psql -h localhost -p 5433 -U app_user -d production

# Persistent, survives sleep and network changes
brew install autossh
AUTOSSH_GATETIME=0 autossh -M 0 -f -N \
  -o "ServerAliveInterval 30" \
  -L 5433:dbhost.internal:5432 user@bastion

# Persistent, survives reboot (Linux)
# Drop the autossh command into ~/.config/systemd/user/pg-tunnel.service
# and run: systemctl --user enable --now pg-tunnel.service

That is genuinely all you need for 95% of the database access situations a developer hits.

The whole reason this pattern works is that SSH is older than most of the protocols we layer on top of it, and the port-forwarding feature has been battle-tested for three decades. Use it. Stop opening database ports to the internet. Your future self will thank you the next time a Shodan-driven exploit campaign sweeps the internet looking for misconfigured Postgres instances, which is approximately every Tuesday.

For more on the protocol, see the OpenSSH manual page for ssh(1), the autossh project page, and RFC 4254 for the SSH connection protocol spec that defines port forwarding.

Keep Reading

Postgres Connection Pool: A pgbouncer Survival Guide: once you can reach the database, the next question is how many connections you can hold open without melting it.
Zero-Trust Microservices with Spring Security: the bigger frame for why exposing internal ports is the wrong default, even inside a private network.

Spring AI 2.0 MCP Annotations: From Tool to Production

Rabinarayan Patra — Tue, 26 May 2026 18:30:00 +0000

Spring AI 2.0.0-M6 dropped on May 8, 2026. Buried in the release notes was the thing I had been waiting for since I first wired an MCP server in Java six months ago: native annotations. @McpTool, @McpResource, @McpPrompt, @McpComplete. All in core. All auto-registered.

If you've written an MCP server with the older Spring AI ToolCallback API, you remember the ritual. Build descriptors, register callbacks, wire up the transport manually, handle JSON schema by hand. The annotation API replaces all of it with a single annotation on a method. Spring AI generates the schema. Auto-configuration handles registration. You write the business logic.

This tutorial walks the full path: building a production MCP server, exposing tools and resources, handling async work with progress reporting, picking a transport, registering with Claude Code, and the gotchas I've hit that nobody mentions on the docs.

What changed in Spring AI 2.0 MCP annotations?

Spring AI 2.0 collapses MCP server and client wiring into a small set of annotations that Spring Boot auto-configuration picks up at startup. The annotated beans become the MCP surface for your Spring Boot app.

The core server annotations are:

@McpTool marks a method as an MCP tool. Spring AI builds the JSON schema from your method parameters.
@McpResource exposes a resource via a URI template.
@McpPrompt exposes a prompt template that clients can fetch.
@McpComplete provides auto-completion for prompt or resource arguments.

The auto-configuration also injects special context parameters like McpSyncRequestContext and McpAsyncRequestContext, which give your method access to logging, progress reporting, sampling, and elicitation without polluting the JSON schema.

For a Spring shop, this is the kind of API change that flips a project's complexity. Before, every team building an MCP server wrote the same plumbing. Now the plumbing is gone.

How do you build an MCP server with @McpTool?

Start with a Spring Boot 3.5+ project on Java 21 or higher. Add the MCP server starter to your pom.xml. There are three flavors: stdio/SSE default, WebMVC, and WebFlux. For production HTTP transport, pick WebMVC or WebFlux based on whether you want blocking or reactive code.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>2.0.0-M6</version>
</dependency>

Spring AI 2.0 milestones live in the Spring milestone repository, so add it if you haven't:

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

Now write a tool. The example everyone reaches for first is a calculator, but let's do something a real MCP client would actually want: fetching a user record from your database.

import org.springframework.ai.mcp.server.annotation.McpTool;
import org.springframework.ai.mcp.server.annotation.McpToolParam;
import org.springframework.stereotype.Component;

@Component
public class UserTools {

    private final UserRepository users;

    public UserTools(UserRepository users) {
        this.users = users;
    }

    @McpTool(
        name = "get_user",
        description = "Fetch a user record by ID. Returns name, email, and signup date."
    )
    public UserDto getUser(
        @McpToolParam(description = "Numeric user ID", required = true) long userId
    ) {
        return users.findById(userId)
            .map(UserDto::from)
            .orElseThrow(() -> new IllegalArgumentException("User not found: " + userId));
    }
}

That's the whole tool. Spring AI does a few things automatically when it scans this bean:

It builds a JSON schema for the userId parameter using the @McpToolParam description and the Java type. The MCP client sees the schema and shows it as a typed input.

It registers the method with the MCP server runtime under the name get_user. The MCP tools/list request returns it. The tools/call request invokes it.

It serializes the return type using Jackson. UserDto becomes a JSON object in the tool result.

You can also use Map<String, Object> if you want loose typing, or a record class if you want strict typing with deserialization on the client side. Records are my default. The serialization is predictable, the schema is implicit, and the code is less than a Lombok annotation pile would be.

How do you handle progress and async work?

The most common reason a tool feels broken in production is that it does real work without telling the client. The client sits there. The user sits there. Eventually something times out. Spring AI 2.0 fixes this with a request context that exposes a progress channel.

import org.springframework.ai.mcp.server.annotation.McpTool;
import org.springframework.ai.mcp.server.context.McpSyncRequestContext;
import org.springframework.stereotype.Component;

@Component
public class ReportTools {

    private final ReportService reports;

    public ReportTools(ReportService reports) {
        this.reports = reports;
    }

    @McpTool(
        name = "generate_quarterly_report",
        description = "Generate the quarterly revenue report. Takes a few seconds."
    )
    public ReportResult generateReport(
        McpSyncRequestContext ctx,
        @McpToolParam(description = "Quarter, e.g. 2026-Q1", required = true) String quarter
    ) {
        ctx.logging().info("Loading transactions for " + quarter);
        ctx.progress().report(0.1, "Loading transactions");

        var transactions = reports.loadTransactions(quarter);
        ctx.progress().report(0.5, "Aggregating");

        var aggregated = reports.aggregate(transactions);
        ctx.progress().report(0.9, "Rendering");

        return reports.render(aggregated);
    }
}

McpSyncRequestContext does not appear in the JSON schema. Spring AI knows it's a framework parameter and excludes it. The user-facing parameters stay clean. Inside the method you get logging(), progress(), sampling(), and elicitation() channels, all wired to the MCP client transport.

For reactive code, use McpAsyncRequestContext and return a Mono or Flux. The progress channel returns Reactor types so you can compose progress reporting into a reactive chain.

@McpTool(name = "async_report", description = "Generate report asynchronously.")
public Mono<ReportResult> asyncReport(
    McpAsyncRequestContext ctx,
    @McpToolParam(description = "Quarter") String quarter
) {
    return reports.loadAsync(quarter)
        .doOnNext(_ -> ctx.progress().report(0.5, "Aggregated").subscribe())
        .flatMap(reports::renderAsync);
}

One thing to flag: the progress channel is not the same thing as streaming results. Progress is metadata. The result is still a single return value. If you want token-by-token streaming, you want sampling, not tools.

How do you expose prompts and resources?

Tools are the most-used MCP primitive, but prompts and resources are what turn a tool collection into a workspace. Prompts let the client request a prefilled prompt template. Resources let the client browse data your server exposes by URI.

A prompt looks like this:

@Component
public class IncidentPrompts {

    @McpPrompt(
        name = "incident_summary",
        description = "Generate an incident summary from a Jira ticket ID."
    )
    public String incidentSummary(
        @McpToolParam(description = "Jira ticket ID, e.g. INC-1234") String ticketId
    ) {
        return """
            Summarize the incident in ticket %s for an executive audience.
            Include: timeline, root cause, customer impact, and remediation.
            """.formatted(ticketId);
    }
}

When the client asks for the incident_summary prompt with INC-1234, the server returns the rendered string. The client passes it to its model.

Resources are different. They expose data the server holds, keyed by URI:

@Component
public class CustomerResources {

    private final CustomerRepository customers;

    public CustomerResources(CustomerRepository customers) {
        this.customers = customers;
    }

    @McpResource(
        uri = "customer://{customerId}/profile",
        description = "Customer profile data including billing address and tier."
    )
    public CustomerProfile profile(String customerId) {
        return customers.profileFor(customerId);
    }
}

The client can list resources, pick one, and read it. The URI template is matched on the path variable. Spring AI extracts the customerId and passes it to the method.

The combination of tools, prompts, and resources is what makes MCP feel like an actual application surface rather than a function bag. Tools do work. Prompts give the client wording. Resources expose state.

How do you choose between transports (stdio, SSE, Streamable HTTP)?

Spring AI supports four transports, and the choice matters more than the docs make it sound.

stdio is for local single-process tools. Claude Code spawns your server as a child process and talks to it over stdin and stdout. Fine for personal tooling. Bad for anything multi-user, multi-tenant, or networked.

SSE was the original HTTP transport for MCP. It's being phased out. Spring AI still ships it for backward compatibility, but new servers should not start there.

Streamable HTTP is the current MCP HTTP transport. Stateful, supports bidirectional notifications, works behind reverse proxies, fits production environments. Use this for any server that isn't strictly local.

Stateless Streamable HTTP is the new variant designed for serverless and horizontally scaled deployments. No session affinity required. The tradeoff is that any context that would have lived in the server session has to come back through the request from the client. If you're deploying to Vercel, Cloud Run, or any autoscaled platform, this is your transport.

For Streamable HTTP with WebMVC, the auto-config wires it up at /mcp by default. You can change the path:

spring:
  ai:
    mcp:
      server:
        transport: streamable-http
        path: /api/mcp
        name: my-spring-server
        version: 1.0.0

The name and version show up in the MCP initialize response. Set them to something recognizable. Default Spring AI names look generic in client UIs.

How do you register and test the server with Claude Code?

Once your Spring Boot app runs and exposes Streamable HTTP at /mcp, register it with Claude Code. The config lives in ~/.config/claude/mcp.json on macOS and Linux, or via the claude mcp CLI.

{
  "mcpServers": {
    "my-spring-server": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Restart Claude Code. Run /mcp inside a session. You should see your tools, prompts, and resources listed. Try calling one. If the call returns and the result shows up in your transcript, the loop is alive.

For local stdio testing, swap the JSON to type stdio and point command at your packaged jar:

{
  "mcpServers": {
    "my-spring-server": {
      "type": "stdio",
      "command": "java",
      "args": ["-jar", "/path/to/server.jar"]
    }
  }
}

Claude Code will spawn the JVM, talk over stdin and stdout, and shut it down when the session ends. The startup cost is real, somewhere between 2 and 5 seconds depending on your dependencies. For HTTP transport, Spring Boot stays running and connections are cheap.

What are the production-readiness gotchas?

The annotation API hides the complexity. That's a feature for most cases, but it also means a few production concerns aren't obvious until they bite.

Error handling. If your @McpTool method throws, Spring AI wraps the exception and returns an MCP error to the client. Good. But the default error mapping returns the exception message verbatim, which can leak internal details. Customize the error handling with a McpExceptionHandler bean if you're exposing the server to untrusted clients.

Schema generation. Records and POJOs work. Generic collections work. Nested polymorphic types are where the generator gets cranky. If your tool returns a List<Animal> where Animal is an interface, expect the schema to be vague. Prefer concrete types for tool return values. Save the polymorphism for internal layers.

Auth. Spring AI does not ship MCP-specific auth. You wire it through normal Spring Security. For Streamable HTTP, add a security filter chain matching /mcp and validate bearer tokens or API keys there. The Stateless Streamable HTTP transport makes this easier because there's no session to protect, only requests.

Long-running tools. MCP clients have timeouts. Claude Code's default is generous but not infinite. If your tool runs longer than 30 seconds, use the progress channel aggressively, and consider returning a job handle and exposing a second tool to poll status. Trying to hold open a 5-minute synchronous tool call will end in tears.

Scaling. Streamable HTTP is stateful per session. Sticky sessions or a shared session store are needed if you scale horizontally. If you want stateless scaling, use the Stateless Streamable HTTP transport and design your tools to be self-contained on each request.

Tool naming. MCP tool names show up in the client UI. Pick verbs. get_user reads better than userQuery. Consistency matters more than cleverness.

Conclusion

The Spring AI 2.0 MCP annotation API is the kind of upgrade you only notice fully when you look back at the old way. The boilerplate is gone. The schema generation is automatic. The transports are real. The progress and async story is sane.

The part I want more Spring teams to internalize: MCP is no longer an experiment. Every major coding agent speaks it. Every Spring service in your fleet is a potential MCP surface. The cost of exposing your internal APIs to an agent has dropped to almost nothing. Whether that's a good idea is a different conversation, but the technical barrier is now low enough that you should decide on purpose, not by default.

For more on Spring AI MCP, see the Spring AI MCP annotations docs, the Spring AI 2.0.0-M6 release post, and the official MCP spec.

Keep Reading

Claude Skills vs MCP vs Projects. When to reach for an MCP server vs a skill or a project.
Claude Code Routines for CI Automation. Wiring agents into CI once your MCP server is live.
Modern Java + Spring Boot. The Spring Boot 3.x baseline you need before Spring AI 2.0.

Why MCP 2026-07-28 Spec Drops Sessions and Goes Stateless

Rabinarayan Patra — Sun, 24 May 2026 18:30:00 +0000

The MCP team locked the 2026-07-28 spec release candidate on May 21. It is the largest revision since launch and yes, it breaks things. If you are running an MCP server today, you need to understand what changes before July 28 finalizes the spec.

I keep seeing people on X call this "MCP 2.0". It is not. The spec uses date versions, not semver. The official name is the 2026-07-28 specification, and it sits as a release candidate until the final freeze on July 28 2026. The ten-week window between now and then is for SDK maintainers and server authors to validate against real workloads.

The big shift is that MCP is going stateless. The current 2025-11-25 spec treats every client-server connection as a session with handshake, identifier, and lifecycle. The new spec rips most of that out at the protocol layer. Below I walk through what changed, what broke, and whether you should rush your migration or wait.

What is the MCP 2026-07-28 spec release candidate?

The 2026-07-28 release candidate is the next major version of the Model Context Protocol, locked on May 21 2026 and finalizing on July 28 2026. It introduces a stateless protocol core, a formal Extensions framework, the Tasks extension for long-running work, MCP Apps for server-rendered UIs, and OAuth-aligned authorization.

The official MCP roadmap calls this revision "the largest revision of the protocol since launch". Tier 1 SDK maintainers (the official Anthropic-maintained Python and TypeScript SDKs) are expected to ship support within the ten-week validation window. If you maintain a server or build agent infrastructure on top of MCP, this is the version you target next.

A subtle but useful detail: the MCP team shifted its 2026 roadmap from release-milestone organization to priority-area focus. Four priority areas drive the spec now: Transport Evolution and Scalability, Agent Communication, Governance Maturation, and Enterprise Readiness. Almost every concrete change in the 2026-07-28 spec maps directly to one of those four. That alignment matters because it tells you what to expect in the next spec drop too.

Why was the 2025-11-25 stateful protocol hard to scale?

The 2025-11-25 spec required every connection to start with an initialize/initialized handshake. The server returned a session identifier in an Mcp-Session-Id response header, and every subsequent request from that client had to carry the same header so the server could route it back to its session state.

That design is fine for a single-process MCP server running on a developer laptop. It is painful in production. The MCP roadmap calls the problem out directly: "Stateful sessions fight with load balancers, horizontal scaling requires workarounds." When you put a load balancer in front of stateful MCP servers you have three bad options.

You can run sticky sessions, which fail open whenever an instance restarts or scales down. You can share session state in Redis or a similar store, which adds a network hop and a single point of failure to every tool call. Or you can do deep packet inspection at the gateway, reading Mcp-Session-Id out of the header to manually route traffic, which forces every MCP client to know your private cluster topology.

In my own work running an MCP server behind a Vercel Function I hit this within a week. Functions are stateless by design. The first attempt to add MCP routing died on cold starts because the next invocation had no idea what session-id the client was carrying. Working around it meant pushing every session into Upstash Redis and eating the round trip on every tools/list call. Not fun.

The pattern is the same for any horizontally scaled deployment. Cloud Run, AWS Lambda, Kubernetes with HPA, even traditional VMs behind an L7 load balancer all run into the same wall. The old spec quietly assumed long-lived processes with shared memory. The new spec assumes nothing.

How does the stateless protocol core actually work?

The new spec removes the initialize/initialized handshake and the Mcp-Session-Id header from the base protocol. Each MCP request now carries everything the server needs to route it independently, and clients explicitly thread any state across calls themselves.

The headline change for ops folks: a stateless MCP server can sit behind a plain round-robin load balancer with no sticky sessions and no shared session store. According to the release notes, gateways can route traffic on the new Mcp-Method header instead of inspecting payloads, and clients can cache tools/list responses for as long as the server's ttlMs field permits. That last part matters because in production a tools/list call on a busy server can dominate the latency budget.

Here is the shape of the change in terms of request flow.

Before (2025-11-25):
client -> initialize -> server -> 200 + Mcp-Session-Id: abc
client -> tools/list (Mcp-Session-Id: abc) -> server (must own session abc)
client -> tools/call (Mcp-Session-Id: abc) -> same server instance

After (2026-07-28):
client -> tools/list -> load balancer -> server A (returns list + ttlMs)
client -> tools/call -> load balancer -> server B (different instance, same result)

You no longer need the same physical instance to handle both calls. That is the entire ballgame. In practice it means three things for your infrastructure: you can drop sticky session config from your load balancer, you can remove any shared Redis-based session store, and you can stop sending Mcp-Session-Id from your gateway routing rules.

The new Mcp-Method header is the small detail that pays off for gateway authors. Instead of parsing the JSON-RPC body to know whether a request is tools/list or tools/call, the gateway can read a single header and route by method. That lets you split tools/list (cacheable, idempotent) onto edge nodes and tools/call (mutating, sometimes expensive) onto warm origin nodes.

What do Extensions, Tasks, and MCP Apps add?

The 2026-07-28 spec formalizes Extensions as the way new capabilities ship outside the core protocol. The MCP team calls out Extensions as a deliberate move to keep the core small while still letting the ecosystem experiment. New capabilities propose themselves as Extensions first, prove production value, and only graduate into the base spec on the next date-stamped revision.

Two extensions matter most for new servers right now. The Tasks extension is built for long-running operations that need retries, expiry, and lifecycle tracking. If you have ever tried to wrap a 3-minute search index build inside a single MCP tool call and watched the client time out, Tasks fix that. The roadmap explicitly mentions "Tasks lifecycle refinement (retries, expiry policies)" as a priority for 2026.

The Tasks model looks roughly like this. Your tool call returns a task handle instead of a result. The client polls or subscribes to the task by id. The server keeps the task's state in whatever store you like (Redis, Postgres, S3), and the client decides how long it is willing to wait. The client and server never need to be in the same process for this to work. A different server instance can resume a task from its persistent state because the task id is the carrier, not a session.

MCP Apps are the second new extension. They let a server return server-rendered UI components instead of plain text or JSON payloads. The idea is that an MCP server for, say, a payments API can return a real card UI that the host renders inline. This is the closest MCP has come to giving servers presentation control, and it pulls the protocol closer to where Anthropic's Claude Skills and Claude Apps already live.

Both Extensions and Tasks shipped first as experimental features so the team could collect real-world feedback before locking them into a final spec. Treat them as production-ready in the RC window, but expect minor field renames before July 28.

What changes in authorization and error handling?

The new spec aligns authorization more closely with OAuth and OpenID Connect. The earlier spec left auth largely as an implementation detail, which meant every enterprise MCP deployment built its own bearer-token flow. The 2026-07-28 spec defines how OAuth flows interact with MCP transport so a single enterprise SSO setup covers all your MCP servers.

The roadmap lists "Governance Maturation" and "Enterprise Readiness" as priority areas, with audit trails, SSO auth, and gateway behavior as concrete deliverables. If you have been blocked on MCP rollout because security teams could not approve a custom auth flow, this is the change that unblocks you.

Error handling also tightens up. The error code for missing resources shifts from the proprietary -32002 to the JSON-RPC standard -32602. Looks like a small change. In practice it means any client that hard-coded -32002 in retry logic now silently swallows the error and retries forever on legitimate not-found responses. I have already seen this fail in a private SDK that hardcoded the old code. Catch both for the next year of mixed deployments.

A nice secondary effect is that monitoring tools that already understand JSON-RPC standard codes (and there are a lot of them) suddenly understand MCP traffic for free. You lose a small amount of MCP-specific signal in exchange for free integration with every JSON-RPC tracing tool out there. That is a good trade.

Which existing code breaks when you upgrade?

The breaking surface is small in lines of code but wide in impact. Here is what I am tracking across my own servers.

Anywhere your code asserts on Mcp-Session-Id will break. The header is no longer guaranteed and any session-based routing logic needs to come out of your gateway and your client. If you are running NGINX or an Envoy sidecar with rules on Mcp-Session-Id, those rules now do nothing. Worse, they may silently route ALL traffic to one origin because the default fallthrough rule kicks in.

Anywhere your client uses session state implicitly via the handshake will break. The new spec asks you to thread identifiers explicitly between tool calls. If you call tools/list and store the result keyed by session, you need to switch to keying by server URL plus ttlMs.

Anywhere your retry logic catches -32002 will silently misbehave. Change it to -32602 or, better, catch both for the next year of mixed deployments while clients catch up.

Anywhere your gateway does deep packet inspection on the body to route requests will break in a more positive direction. You can rip that logic out and rely on the new Mcp-Method header for routing decisions. Code you delete is code that cannot break in production.

If you are using a Tier 1 SDK (the Anthropic-maintained Python and TypeScript SDKs), the SDK will hide most of these changes from you within the ten-week validation window. If you are on a community SDK, check whether your maintainer is in the Tier 1 list before you plan a migration date. The SDK tier system is itself new to MCP and tells you which SDKs the spec maintainers actively coordinate with on breaking changes.

Should you migrate before July 28 or after?

It depends on whether you control both the client and the server. If you do, migrate as soon as the SDK you depend on ships RC support, which for Tier 1 should land within four to six weeks. The new protocol is friendlier to the production patterns you already want anyway.

If you ship a public MCP server consumed by clients you do not control, hold until July 28 and ship support for both spec versions on the same endpoint for at least a quarter. The spec's deprecation policy and the SDK tier system make dual support cheaper than it sounds, since both protocols can share the same handler code with a thin compatibility layer that reads the request and returns either a session-id (for old clients) or no session (for new ones).

The one case where you should rush is if you are running MCP in a Kubernetes deployment behind an L7 load balancer. The current setup probably has at least one band-aid (sticky sessions, Redis session store, deep packet inspection) that exists only because of the stateful protocol. Migrating lets you delete that code, and code you delete is code that cannot break in production.

There is also a clear case where you should wait. If your MCP server depends on a community SDK that is not in the Tier 1 list, you do not have a guarantee that the SDK will ship 2026-07-28 support before July 28 itself. Plan a quarter of slack. Do not promise a migration date until the SDK author publishes their own.

What does this mean for your MCP servers?

The 2026-07-28 spec is a clean win for anyone running MCP in production. The stateless core removes the awkward fit between MCP and modern serverless or horizontally scaled deployments, and the Tasks and MCP Apps extensions plug gaps that every real deployment has been working around with custom code.

The bigger lesson, though, is that MCP is starting to act like an open protocol with real production users, not a research experiment from Anthropic. Date-stamped versioned specs, an SEP process, formal SDK tiers, and a published roadmap with priority areas all push it in the direction of HTTP or LSP, not a vendor SDK. That is a healthy sign even if the immediate migration is annoying.

If you are starting a new MCP server this week, target the 2026-07-28 RC directly. If you have an existing one, start with deleting your Mcp-Session-Id routing rules and your shared session store. Most teams will find that the migration shrinks their MCP stack rather than grows it, which is the right direction for a protocol that is supposed to be the lowest-friction way to give an LLM access to tools.

For more on the new spec, see the official 2026-07-28 Release Candidate announcement, the 2026 MCP Roadmap, and the current 2025-11-25 specification for the baseline you are migrating from.

Keep Reading

How to Build a Stateless MCP Server for the 2026-07-28 Spec. The applied tutorial that ships with code once you understand the protocol shift this post covers.
Spring AI 2.0 MCP Annotations: From Tool to Production. How the Spring AI 2.0 abstractions sit on top of MCP and what they hide from you.
Claude Skills vs MCP vs Projects: Which One Should You Use?. When to pick MCP at all, given the other ways Claude exposes capabilities to agents.

PostgreSQL 18 Temporal Foreign Keys with Spring Boot JPA

Rabinarayan Patra — Thu, 21 May 2026 18:30:00 +0000

PostgreSQL 18 shipped temporal foreign keys. The kind of feature SQL standards committees promised back in SQL:2011 and most database vendors quietly ignored. Now it's in mainline PG and the Java ecosystem has almost no tutorials on how to use it from Spring Boot.

I went looking for "Spring Boot temporal foreign key" guides last week. The top results were 2018 Baeldung posts on hand-rolled validFrom/validTo columns with zero database-level constraints. Plenty of BETWEEN queries. Plenty of "remember to add an index". No one talks about PG18 yet. So I built a working example, hit every gotcha, and wrote it up.

This post walks the full path: what temporal FKs actually solve, the PostgreSQL 18 syntax, how to map range columns in Hibernate, the Spring Data repository patterns that work, and the ON DELETE behavior that will absolutely surprise you if you skip the docs.

What problem do temporal foreign keys solve?

A temporal foreign key enforces that a child row's time range fits entirely inside its parent row's time range, at the database level, on every insert and update. That's the part regular foreign keys can't do.

Take a classic example. An employee changes departments three times in five years. A project assignment references the employee. The business rule is: a project assignment can only exist during a period when the employee was actually employed.

The hand-rolled approach looks like this:

CREATE TABLE employees (
    emp_id BIGINT,
    valid_from DATE NOT NULL,
    valid_to DATE,
    PRIMARY KEY (emp_id, valid_from)
);

CREATE TABLE project_assignments (
    assignment_id BIGINT PRIMARY KEY,
    emp_id BIGINT NOT NULL,
    assignment_start DATE NOT NULL,
    assignment_end DATE,
    FOREIGN KEY (emp_id) REFERENCES employees(emp_id)
);

Every Spring shop I've worked at had a variation of this. And every one of them had bugs. Project assignments referencing employee IDs whose valid period ended six months ago. Manual BETWEEN checks in service layers that someone forgot to update. Audit failures during quarterly reviews. The data model lied about what it was.

PG18 fixes this at the constraint level. The constraint is the truth, not a service-layer hope.

How does PostgreSQL 18 implement WITHOUT OVERLAPS and PERIOD?

PG18 introduces two new clauses: WITHOUT OVERLAPS for primary and unique keys, and PERIOD for foreign keys. Both rely on range types and GiST indexes under the hood.

Here's the employees table redone the right way:

CREATE EXTENSION IF NOT EXISTS btree_gist;

CREATE TABLE employees (
    emp_id BIGINT NOT NULL,
    name VARCHAR(100) NOT NULL,
    department VARCHAR(50) NOT NULL,
    salary NUMERIC(10,2) NOT NULL,
    valid_period daterange NOT NULL,
    PRIMARY KEY (emp_id, valid_period WITHOUT OVERLAPS)
);

A few things worth pointing out.

The btree_gist extension is required because the primary key mixes a regular BIGINT column with a range column. PG needs a GiST index that can handle both, and btree_gist provides the btree operator support inside GiST. If you forget it, the CREATE TABLE will fail with a confusing operator error.

The valid_period column uses daterange, one of PostgreSQL's built-in range types. You can also use tstzrange for timestamp ranges or int4range for numeric ranges. The constraint creates a GiST index automatically. Try to insert two rows for the same emp_id with overlapping valid_period values and PG rejects it.

Now the project assignments table with a real temporal FK:

CREATE TABLE project_assignments (
    assignment_id BIGSERIAL PRIMARY KEY,
    emp_id BIGINT NOT NULL,
    project_name VARCHAR(100) NOT NULL,
    assignment_period daterange NOT NULL,

    FOREIGN KEY (emp_id, PERIOD assignment_period)
        REFERENCES employees (emp_id, PERIOD valid_period)
);

The PERIOD keyword tells PG that the last column is a range. The check is not equality. The check is containment: the parent's matching rows must, in combination, fully cover the child's range. If the employee's valid_period ends June 1 2024 and the project assignment runs March 1 to August 1 2024, the insert fails because June 1 to August 1 has no parent row covering it.

You can verify this with a deliberate bad insert:

INSERT INTO employees (emp_id, name, department, salary, valid_period)
VALUES (1, 'Alice', 'Engineering', 80000, daterange('2024-01-01', '2024-06-01'));

INSERT INTO project_assignments (emp_id, project_name, assignment_period)
VALUES (1, 'Migration', daterange('2024-03-01', '2024-08-01'));
-- ERROR: insert or update on table "project_assignments" violates foreign key constraint

The constraint catches it. No service code needed.

How do you map daterange columns in Hibernate?

Hibernate 6 added native support for PostgreSQL range types through PostgreSQLRangeJdbcType, but the cleanest path for a Spring Boot app is still the hypersistence-utils library. It's the rebranded version of what most of us used as hibernate-types-52 for years, maintained by Vlad Mihalcea.

Add the dependency to your pom.xml:

<dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-63</artifactId>
    <version>3.10.7</version>
</dependency>

If you're on Spring Boot 3.5+, you'll be on Hibernate 6.6, so use the hypersistence-utils-hibernate-63 artifact. Older Spring Boot 3.x versions use -62. The version numbers track Hibernate ORM, not Spring Boot.

Now the entity:

import io.hypersistence.utils.hibernate.type.range.Range;
import io.hypersistence.utils.hibernate.type.range.PostgreSQLRangeType;
import jakarta.persistence.*;
import org.hibernate.annotations.Type;

import java.math.BigDecimal;
import java.time.LocalDate;

@Entity
@Table(name = "employees")
@IdClass(EmployeeId.class)
public class Employee {

    @Id
    @Column(name = "emp_id")
    private Long empId;

    @Id
    @Type(PostgreSQLRangeType.class)
    @Column(name = "valid_period", columnDefinition = "daterange")
    private Range<LocalDate> validPeriod;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false)
    private String department;

    @Column(nullable = false)
    private BigDecimal salary;

    // getters, setters, constructors
}

A few things to flag.

The @IdClass(EmployeeId.class) is needed because the primary key is composite. The EmployeeId class is a plain Java record or class with the two ID fields and equals/hashCode.

public record EmployeeId(Long empId, Range<LocalDate> validPeriod) implements Serializable {}

The @Type(PostgreSQLRangeType.class) annotation is what makes Hibernate emit and read daterange correctly. The columnDefinition = "daterange" part is what makes JPA's schema generation produce the right column type if you let JPA create the schema. In production, you should use Flyway or Liquibase, not JPA schema generation, but it's worth being explicit either way.

You construct ranges like this:

Range<LocalDate> period = Range.closedOpen(
    LocalDate.of(2024, 1, 1),
    LocalDate.of(2024, 6, 1)
);

closedOpen matches PostgreSQL's [) notation, which is the most common range form for temporal data. Half-open intervals make adjacent ranges easy to reason about: [Jan 1, Jun 1) and [Jun 1, Dec 1) are adjacent, not overlapping.

through hypersistence-utils to PostgreSQL daterange" width="799" height="452">

How do you write the entity and repository?

Spring Data JPA does most of the work, but you need a custom query for the overlap check at the application level. Database constraints catch invalid inserts, but the app still needs to ask "who was employed during this period?"

The repository:

public interface EmployeeRepository extends JpaRepository<Employee, EmployeeId> {

    @Query(value = """
        SELECT *
        FROM employees
        WHERE emp_id = :empId
          AND valid_period && :period
        """, nativeQuery = true)
    List<Employee> findOverlapping(
        @Param("empId") Long empId,
        @Param("period") String period
    );
}

The && operator is PostgreSQL's range-overlap operator. You pass the range as a string in PG range literal form: [2024-01-01,2024-06-01). JPA doesn't have a native range-binding mechanism, so the string approach is the pragmatic move. If you want strong typing, Vlad's library offers Range.toString() which formats correctly.

Here's a service method that finds the employee record valid for a given date:

@Service
public class EmploymentService {

    private final EmployeeRepository repo;

    public EmploymentService(EmployeeRepository repo) {
        this.repo = repo;
    }

    public Optional<Employee> findAt(Long empId, LocalDate at) {
        String singleDay = String.format("[%s,%s]", at, at);
        return repo.findOverlapping(empId, singleDay).stream().findFirst();
    }
}

For the project assignment side, the insert just works. Hibernate sends the daterange, PG checks the temporal FK, and if the assignment period isn't fully covered by some employee period, the transaction rolls back.

@Transactional
public ProjectAssignment assign(Long empId, String projectName, Range<LocalDate> period) {
    ProjectAssignment pa = new ProjectAssignment();
    pa.setEmpId(empId);
    pa.setProjectName(projectName);
    pa.setAssignmentPeriod(period);
    return assignmentRepo.save(pa);
}

If the period extends past the employee's validity, you get a DataIntegrityViolationException wrapping the PG error. Catch it where your error handling needs it.

What are the gotchas with ON DELETE and temporal foreign keys?

This is the one that will burn you if you skip the docs. PostgreSQL 18 does not support CASCADE, RESTRICT, SET NULL, or SET DEFAULT referential actions on temporal foreign keys. Only NO ACTION is allowed.

From the official PG18 CREATE TABLE docs: "In a temporal foreign key, this option is not supported." That sentence appears under every action except NO ACTION.

What does this mean in practice? If you delete an employee row that has dependent project assignments, PG raises a foreign key violation. You have to delete the assignments first, manually, in application code or in a database trigger you write yourself.

-- This will fail at the second statement
DELETE FROM employees WHERE emp_id = 1;
-- ERROR: update or delete on table "employees" violates foreign key constraint

The workaround patterns I've seen:

The first is application-level deletion. Spring service methods that delete child rows before parent rows, wrapped in a @Transactional boundary. This is fine for small graphs, but it doesn't scale to deep hierarchies.

The second is soft delete on the parent. Add a deleted_at column, never actually delete rows, and let the temporal FK stay intact forever. Most enterprise systems do this anyway for audit reasons.

The third is to flip the model: instead of deleting the parent, you close the parent's period by updating valid_period to end at today's date. Future child inserts will fail. Existing child rows stay valid because their periods were covered when they were created.

The third approach is closest to the spirit of temporal modeling. You don't lose history. You just declare "this record stopped being valid at this point" and let the constraints enforce that going forward.

If you absolutely need cascading deletes, you can write a trigger that does the deletion manually before the parent delete fires. But at that point you're rebuilding what the standard wanted to give you, and the SQL spec authors decided cascade semantics on overlapping periods were too ambiguous to specify. They might be right.

When should you NOT use temporal foreign keys?

Temporal foreign keys are powerful, and like most powerful features they're easy to overuse. I've seen teams reach for them in places where regular FKs would be simpler and just as correct.

Skip temporal FKs when:

You only need audit history. If the question is "what changed when?" and not "what was the state of the world on date X?", a separate audit log table with regular FKs is simpler. Frameworks like Hibernate Envers handle this well.

The child rows don't have an independent time dimension. If a project assignment is just "associated with employee 1 forever", you don't need temporal FKs. A regular FK with a created_at timestamp is fine.

You're modeling a single current state. CRUD apps where the latest row is the only thing that matters don't need temporal modeling. Add a valid_period column and you've created complexity you'll have to pay for in every query.

You can't pay the GiST index cost. GiST indexes are slower for point lookups than btree indexes. For high-throughput single-row reads, you'll feel it. Benchmark first.

When the model genuinely is temporal, the constraint-enforced version is a huge improvement over the hand-rolled version. The number of bugs you avoid by having PG check every insert is real. The cost of writing the queries against ranges instead of timestamps is real too, but it's a one-time cost. The bugs are forever.

Conclusion

PostgreSQL 18 temporal foreign keys are one of the most under-discussed major-version features I've seen in a while. The Spring Boot ecosystem has barely caught up. If you're modeling employment, contracts, pricing tiers, policies, or anything else where state has duration, the new WITHOUT OVERLAPS and PERIOD clauses are worth learning even if you don't ship them tomorrow.

The piece I want more people to understand: this changes what your database can be the source of truth for. Before PG18, "this assignment must fall inside an employment period" was a service-layer concern that drifted out of sync. Now it's a constraint. The database tells the truth.

For more on the PG18 release, see the PostgreSQL 18.0 release notes, the Neon writeup on temporal constraints, and the CREATE TABLE syntax docs.

Keep Reading

Spring Boot Testcontainers Guide. Real PG18 in tests beats mocked databases for catching constraint bugs early.
Hibernate Lazy Init Guide. The other Hibernate gotcha that bites every Spring team.
PgBouncer Survival Guide. Connection pooling matters more when GiST indexes are doing real work.

Next.js 16.2 AGENTS.md and next-browser: A Hands-On Guide

Rabinarayan Patra — Tue, 28 Apr 2026 18:30:00 +0000

I run Claude Code on my Next.js portfolio every day. For the last year my routine has been the same: paste the relevant Next.js 16 doc into chat, watch the agent write something that worked in Next.js 13, correct it, paste another doc, repeat. The agent's training data was stale, the context window was precious, and I was the middleman.

Next.js 16.2 quietly killed that routine. Shipped on March 18, 2026 by Jude Gao, Jimmy Lai, Tim Neutkens and the rest of the Next.js team, the release ships AGENTS.md by default, bundles the entire Next.js docs as plain Markdown inside node_modules/next/dist/docs/, and adds an experimental @vercel/next-browser CLI that lets agents inspect a running app through shell commands. Vercel ran their internal evals and saw 100% pass rate with AGENTS.md vs 79% with the best skill-based setup. That is a big enough gap to change how I scaffold projects.

This post walks through what actually shipped, how to add it to an existing project, and what I changed in my own workflow after upgrading rabinarayanpatra.com to 16.2.

What is AGENTS.md in Next.js 16.2?

AGENTS.md is a Markdown file at the root of a Next.js project that tells AI coding agents to read the version-matched docs bundled inside node_modules/next/dist/docs/ before writing any code. It is not a skill, it is not a plugin, and it is not loaded on demand. It is always-on context that any agent respecting the AGENTS.md convention will pick up at the start of every turn.

The default file that create-next-app generates is small. Here is the shape of it:

<!-- BEGIN:nextjs-agent-rules -->

# Next.js: ALWAYS read docs before coding

Before any Next.js work, find and read the relevant doc in `node_modules/next/dist/docs/`. Your training data is outdated. The docs are the source of truth.

<!-- END:nextjs-agent-rules -->

The BEGIN and END comment markers delimit the Next.js-managed section. Future codemods will only rewrite what is inside those markers, so anything you add outside stays yours. That is a small design choice with a big payoff, because it means you can keep your own agent rules next to the framework's without fighting merge conflicts.

The second piece is the bundled docs themselves. The next npm package now ships the full doc tree as plain Markdown files. Open node_modules/next/dist/docs/ in your editor and you will see the same content as nextjs.org, organized by section. A compressed index file is also shipped at around 8 KB, an 80% reduction from the raw 40 KB of full docs, which is what the agent reads first to find the right file to pull into context.

Third, on projects already set up for Claude Code, there is a tiny convention link:

@AGENTS.md

The @ directive tells Claude Code to include the contents of AGENTS.md whenever it loads CLAUDE.md. So the bootstrap chain becomes CLAUDE.md pulls in AGENTS.md, AGENTS.md tells the agent to read node_modules/next/dist/docs/ whenever Next.js work is happening, and the agent writes code against the real 16.2 API rather than a memory of Next.js 13.

How do you add AGENTS.md to an existing Next.js project?

On Next.js 16.2 or later, you already have the docs on disk. You just need to create the two files yourself or let the codemod do it. The codemod is the faster path:

npx @next/codemod@latest agents-md

That scaffolds AGENTS.md with the managed directive block and creates or updates CLAUDE.md with the @AGENTS.md include. I ran it on the portfolio and it was a one-second change plus two new files in the diff.

If you are on an older version of Next.js, upgrade first:

npx @next/codemod@canary upgrade latest

Then re-run the agents-md codemod. The upgrade is where the doc bundle actually lands on disk, so you need 16.2 for the whole flow to work.

The part I liked most is the escape hatch. If your project already has a sprawling AGENTS.md with your own conventions, you can drop the managed block into it and keep everything else. The codemod respects existing files and only touches what is inside the markers. That matters for teams who have been writing their own agent rules for months.

One pitfall I hit on my first attempt: my .gitignore had node_modules/ ignored (obviously), but Claude Code was still happy to read from it, since it is a local file read, not a git operation. So you do not need to commit the docs, you just need the package installed. CI builds, however, need to run npm install before an agent can use the docs, which is the usual order anyway.

What does the @vercel/next-browser CLI actually do?

@vercel/next-browser is an experimental CLI that wraps a persistent Chromium instance with React DevTools pre-loaded and exposes browser data through shell commands. Instead of an agent trying to understand a DevTools panel it cannot see, the agent runs a shell command, gets back structured text, and reasons about the output.

You install it as a skill:

npx skills add vercel-labs/next-browser

Then trigger it inside an agent that supports skills by typing /next-browser. Claude Code and Cursor both work. The first run boots a Chromium instance you do not see, loads React DevTools into it, and holds the session open across commands.

At release the feature set covers five buckets. Component trees with props, hooks, state, and source-mapped file locations. PPR shell analysis, which identifies what is static and what is blocking. Errors and logs from the dev server. Network activity since the last navigation, including server actions. And visual capture with screenshots or loading filmstrips.

The concrete example in the release post is my favorite, because it shows the workflow end-to-end. You have a blog post page with a visitor counter:

export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);
  const views = await getVisitorCount(params.slug); // per-request

  return (
    <article>
      <h1>{post.title}</h1>
      <span>{views} views</span>
      <div>{post.content}</div>
    </article>
  );
}

Every slug is enumerated ahead of time, so the post content should prerender at build. But getVisitorCount runs on every request and sits at the top level, which drags the entire page out of the static shell. The user sees a loading skeleton instead of the post content streaming in.

An agent can diagnose this by locking PPR mode and inspecting the shell:

next-browser ppr lock
next-browser goto /blog/hello

With PPR locked, only the static shell renders. In this case the shell is the loading skeleton, because nothing from the page made it in. Running ppr unlock gives the agent a structured report:

# PPR Shell Analysis
# 1 dynamic hole, 1 static

blocked by:
  - getVisitorCount (server-fetch)
    owner: BlogPost at app/blog/[slug]/page.tsx:5
    next step: Push the fetch into a smaller Suspense leaf

The agent now knows what the blocker is, where it lives, and what to do. It wraps the counter in a Suspense boundary:

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <Suspense fallback={<span>... views</span>}>
        <VisitorCount slug={params.slug} />
      </Suspense>
      <div>{post.content}</div>
    </article>
  );
}

Run ppr lock again and the shell has grown. The post content prerenders instantly, and only the view count falls back to the Suspense placeholder. The agent did that without ever opening a browser window.

The thing I keep coming back to is that the CLI is designed around one-shot commands against a persistent session. That matches how LLM tool-calling works today. The agent does not manage browser state, the CLI does. The agent just asks questions and parses replies, which is exactly the interaction pattern that works for a model.

How does the dev server lock file help AI agents?

Next.js 16.2 writes the running dev server's PID, port, and URL into .next/dev/lock. When a second next dev starts in the same directory, Next.js reads the lock file and prints an actionable error instead of a generic port-conflict message:

Error: Another next dev server is already running.

- Local: http://localhost:3000
- PID: 12345
- Dir: /path/to/project
- Log: .next/dev/logs/next-development.log

Run kill 12345 to stop it.

On paper this is quality-of-life for humans. In practice, this is the single change that saves me the most time with Claude Code.

Before 16.2, my workflow was: I start the dev server in a pane, Claude Code spawns its own next dev to check something, the command hangs because port 3000 is taken, Claude Code retries on another port, I get a second server I do not want. Now the agent gets a clean error, a PID to kill, a URL to connect to, and a log path to tail. It makes the right call the first time.

The lock file also prevents two next build processes from running at once, which could otherwise corrupt build artifacts. That is a genuine bug I have seen in CI where a re-run was queued before the first finished. Now the second run refuses to start.

How do you forward browser logs to the terminal?

By default, Next.js 16.2 forwards browser errors to the dev terminal. You do not have to switch to the browser console to see client-side errors, which is another quality-of-life win for agents who cannot open a DevTools panel at all.

The level is configurable:

const nextConfig = {
  logging: {
    browserToTerminal: true,
    // 'error': errors only (default)
    // 'warn': warnings and errors
    // true: all console output
    // false: disabled
  },
};

export default nextConfig;

I ran this at true for a week and it was too noisy for a typical debugging session. I rolled it back to 'warn' which is the right default for me. Errors alone is usually too narrow, because half the client-side issues I chase start as warnings that the agent would have caught earlier with a wider filter.

Pairing this with the agent DevTools is the real win. The agent gets errors in the terminal, runs next-browser for a closer look, fixes the code, and moves on. No browser console, no screenshots to interpret, no back-and-forth with me asking what the page looked like.

Why does Vercel say AGENTS.md beat skills in their evals?

The numbers from Vercel's internal eval are worth quoting straight. They tested four configurations against a suite of Next.js 16 APIs that did not exist in model training data, like 'use cache', cacheTag(), forbidden(), and proxy.ts:

Configuration	Pass rate
Baseline (no docs)	53%
Skill (default invocation)	53%
Skill with explicit instructions	79%
AGENTS.md docs index	100%

The skill with default invocation matched baseline exactly. Vercel's explanation for that is brutal: "In 56% of eval cases, the skill was never invoked." The agent did not know it needed to look something up, so it did not.

Explicit instructions pushed skills to 79%, which is a real improvement, but it took careful prompt wording to get there. Phrasing like "You MUST invoke" caused agents to anchor on the docs and miss project context. "Explore project first, then invoke skill" was better. That kind of prompt sensitivity is not something I want to maintain for a team.

AGENTS.md hit 100% across build, lint, and test eval categories. The authors called out the mental model: the goal is to shift agents "from pre-training-led reasoning to retrieval-led reasoning." Always-on context wins over on-demand retrieval because there is no decision point the agent can get wrong.

That matches my experience. The moments I lost the most time with Claude Code were the moments it was confidently wrong, using old APIs it remembered from training. It did not ping the docs because it did not know it needed to. AGENTS.md removes that failure mode by making the docs non-negotiable.

What changes did Next.js 16.2 make to rendering performance?

The agent story is the headline, but 16.2 also ships a big performance jump that is easy to miss. The team landed a change in React (PR #35776) that replaces JSON.parse with a reviver callback with JSON.parse followed by a recursive walk in pure JavaScript. The result is up to 350% faster RSC payload deserialization and 25% to 60% faster real-world server rendering.

The root cause is a V8 quirk. JSON.parse with a reviver crosses the C++/JavaScript boundary once per key-value pair, and even a no-op reviver makes parsing around 4x slower than without one. Replacing that with a two-step parse-then-walk eliminates the per-key cost.

The measured numbers are the kind of data I trust because they come from real apps:

Workload	Before	After	Speedup
1000-item Server Component table	19ms	15ms	26%
Server Component with nested Suspense	80ms	60ms	33%
Payload CMS homepage	43ms	32ms	34%
Payload CMS with rich text	52ms	33ms	60%

You do not need to change any code. Upgrade to 16.2 and react@latest and the speedup lands. The heavier your RSC payload, the bigger the win, which is why the rich-text case hits 60%.

Next.js 16.2 also makes ImageResponse 2x faster for basic images and up to 20x faster for complex ones, with the default font switched from Noto Sans to Geist Sans. Dev startup is around 87% faster than 16.1 on the default application, so the time between next dev and a ready localhost shrank noticeably on my machine.

Does AGENTS.md replace Claude Code skills entirely?

No, and I do not think it should. AGENTS.md and skills solve different problems.

AGENTS.md is for always-on framework context. Your agent needs to know Next.js 16 every time it writes a Next.js component. That is not an on-demand concern, it is a default concern. Putting it in AGENTS.md removes the decision point about whether to fetch the docs, which is exactly the decision agents are bad at.

Skills are for scoped, opt-in capabilities. A skill that runs a specific CLI, calls a private API, or triggers a deploy is something you want the agent to invoke deliberately. The decision point is the feature. You do not want the agent triggering your prod deploy on every turn.

The Vercel team made the right call putting framework docs into AGENTS.md and keeping the next-browser debugger as a skill you trigger with /next-browser. The debugger is a scoped capability. The framework docs are ambient context. Matching each tool to the right mechanism is the actual lesson here.

My working rule, after a week of running both on the portfolio: if your agent should consult it every time, put it in AGENTS.md. If your agent should consult it sometimes, make it a skill.

What does this mean for the next year of framework design?

Next.js 16.2 is the first mainstream framework release where the primary design target is an AI coding agent, not a human developer. The default scaffolding exports a file the human may never read. The docs are shipped as Markdown because that is what parses cleanly for a model. The dev server writes a lock file so another process can recover without a human. The experimental DevTools are a shell command interface because that is what LLMs can drive.

This is not a future-looking take. It is already in create-next-app@latest. And the concrete UX win for me was small but sharp: I stopped pasting docs into chat. That one behavior change saved me an hour a week. Scaled across a team of developers all running agents all day, the time savings compound fast.

The open question is how many frameworks follow. Spring, FastAPI, Rails, Django, Laravel, every major framework has the same training-data-staleness problem Next.js just solved. I expect the next wave of releases to ship their own AGENTS.md conventions, bundled docs, and agent-friendly CLI wrappers. Vercel's eval numbers make the business case too strong to ignore.

For more on this release, see the Next.js 16.2 blog post, the Next.js 16.2 AI Improvements post, and Vercel's AGENTS.md outperforms skills eval writeup. The RSC payload perf change is React PR #35776 if you want to read the actual diff.

Keep Reading

Building a Modern Docs Generator with Next.js 16. Where I first went deep on Next.js 16's App Router and how I think about docs infrastructure.
Hello Proxy in TypeScript and Next.js 16. The middleware/proxy rename that landed in 16.0, relevant background for anything using proxy.ts.
Replacing useEffect Data Fetching with Server Actions. Server-side patterns that pair naturally with the 16.2 rendering improvements.
Vercel AI Gateway Deep Dive. The other side of the Vercel AI story, if you want the provider routing and observability angle.

Amazon S3 Files: AWS Just Turned Object Storage Into a File System

Rabinarayan Patra — Thu, 09 Apr 2026 18:30:00 +0000

I've been running EFS-to-S3 sync jobs for two years. Cron schedules, lifecycle policies, rsync scripts that break every time someone changes a directory structure. All because S3 couldn't speak file system.

That changed this week.

On April 7, 2026, AWS announced Amazon S3 Files, a feature that lets you mount any S3 bucket as a shared NFS file system. No gateway. No third-party tool. No data copies. Your applications read and write files, and S3 stores them. That's it.

And quietly, on April 6, AWS also started disabling SSE-C encryption by default on all new S3 buckets. If you're managing encryption keys manually, that one needs your attention too.

Let me walk through both changes.

What is Amazon S3 Files and how does it work?

Amazon S3 Files gives S3 buckets a fully-featured file system interface using NFS v4.2. You can mount a bucket on EC2, Lambda, EKS, ECS, Fargate, or AWS Batch and interact with your data using standard file operations: open(), read(), write(), ls, cp, mv. No SDK. No API calls. Just a mount point.

Architecture overview of Amazon S3 Files. Source: AWS News Blog

S3 is now the first and only cloud object store that provides native file system access while keeping all data in object storage. Your objects don't move to a separate file system. They stay in S3 with all the durability, lifecycle policies, and access controls you already have.

S3 Files is generally available in 34 AWS Regions as of launch day.

The stage and commit model

This is the part that surprised me. Instead of translating every file write into an immediate S3 PUT, S3 Files batches changes and commits them to S3 roughly every 60 seconds. AWS borrowed this concept from version control.

Here's what that means in practice:

You write a file through the NFS mount
The write lands in a caching layer (built on EFS infrastructure)
S3 Files aggregates writes within a 60-second window
Multiple writes to the same file become a single S3 PUT
The committed object appears in S3 with full consistency

This batching has two practical benefits. First, it cuts your S3 request costs because ten rapid writes to the same file become one PUT, not ten. Second, if you're using S3 versioning, you don't end up with ten versions of a file that changed in under a minute.

But it also means there's a ~60-second lag before file changes are visible on the S3 side. If your workflow needs immediate S3 API visibility of written data, you need to account for that delay.

When there's a conflict (say, someone writes to a file through NFS while another process updates the same object via the S3 API), S3 remains authoritative. The file-side version gets moved to a lost+found directory with metrics for visibility. No silent data loss.

The caching layer under the hood

When you create an S3 Files file system, AWS provisions a caching layer backed by EFS infrastructure. This cache holds three things:

Recently read files : Hot reads come from cache with sub-millisecond latency
Recently written files : Staged writes waiting for the next commit cycle
Metadata : Directory listings, file attributes, timestamps

Small file reads are served entirely from the cache. Large file reads (over 1MB) stream directly from S3 and don't incur S3 Files charges. The aggregate read throughput can reach multiple terabytes per second.

This design is what makes S3 Files cost-effective. You pay file system rates ($0.30/GB-month) only on the data that's actively cached. A petabyte bucket where only 500GB is actively read? You're paying S3 rates for the petabyte and file system rates for the 500GB.

How do you set up S3 Files on an EC2 instance?

The setup is straightforward. Here's the full flow:

# Step 1: Create an S3 Files file system linked to your bucket
aws s3api create-file-system \
  --bucket my-data-bucket \
  --file-system-name my-fs

# Step 2: Get the mount target DNS name
aws s3api describe-file-system \
  --bucket my-data-bucket \
  --file-system-name my-fs \
  --query 'FileSystem.MountTargets[0].DnsName' \
  --output text

# Step 3: Mount on your EC2 instance
sudo mount -t nfs4 \
  -o nfsvers=4.2,rsize=1048576,wsize=1048576 \
  fs-mount-target.efs.us-east-1.amazonaws.com:/ \
  /mnt/s3data

# Step 4: Use it like any filesystem
ls /mnt/s3data
cp local-file.csv /mnt/s3data/uploads/
cat /mnt/s3data/reports/quarterly.json

Once mounted, every application on that instance can access S3 data through normal file I/O. Python scripts, Java apps, shell scripts, legacy C++ binaries. Nothing needs to know it's talking to S3.

For persistent mounts across reboots, add it to /etc/fstab:

# /etc/fstab entry for S3 Files
fs-mount-target.efs.us-east-1.amazonaws.com:/ /mnt/s3data nfs4 nfsvers=4.2,rsize=1048576,wsize=1048576,_netdev 0 0

Where does S3 Files beat EFS (and where does it not)?

This is the question I've been testing all week. S3 Files isn't a drop-in EFS replacement for every workload, but for specific patterns it's clearly better.

S3 Files wins

Scenario	Why S3 Files
Large datasets, small active working set	Pay S3 rates on cold data, file system rates only on hot data
Legacy app migration to S3	Zero code changes needed, just mount and go
AI/ML training data pipelines	Read training data as files, store as S3 objects
Agentic AI workloads	Shared workspace across multiple compute instances
Multi-service data sharing	Multiple EKS pods or Lambda functions reading the same dataset

EFS still wins

Scenario	Why EFS
All data is hot, constant read/write	EFS avoids the commit delay and S3 request overhead
Sub-second write visibility needed	S3 Files has a ~60-second commit lag
Windows workloads (SMB)	S3 Files only supports NFS, no SMB
Hard link requirements	S3 Files doesn't support hard links
Bucket exceeds 50 million objects	AWS warns about performance at this scale

Pricing comparison

The pricing math depends entirely on your access pattern:

S3 Files cached storage : $0.30/GB-month (only for actively cached data)
S3 Files reads (small files): $0.03/GB from cache
S3 Files reads (large files, 1MB+): $0 from S3 Files (standard S3 GET charges apply)
S3 Files writes : $0.06/GB

Compare that to EFS Performance-optimized at $0.30/GB for standard storage and $0.03/GB for reads. The difference shows up at scale: if you have 10TB in a bucket but only touch 200GB regularly, S3 Files costs a fraction of what an equivalent EFS setup would cost.

What are the gotchas you should know before adopting S3 Files?

I ran into a few things during my initial testing that are worth flagging.

The 60-second commit window is real. If you write a file via NFS and immediately try to read it through the S3 API (using aws s3 cp or a direct GET), it won't be there yet. Your application logic needs to handle this. For workflows that do writes via NFS and reads via S3 API, consider adding a short wait or checking for object existence.

NFS file locks don't protect against S3 API access. If you lock a file through NFS, that lock only applies to other NFS clients. Someone using the S3 API directly can still modify the object. This isn't a bug. It's how the boundary between file system and object store works. But it can bite you if mixed access isn't on your radar.

The 50-million object warning is something to watch. AWS recommends caution when a mounted bucket contains more than 50 million objects. Directory listings and metadata operations can slow down at that scale. If you're dealing with buckets that large, consider using S3 prefixes to scope your mount.

No pNFS, Kerberos, or nconnect support. If your NFS setup depends on parallel NFS, Kerberos authentication, NFSv4 data retention, or the nconnect mount option, those aren't available yet at GA. Standard NFS v4.2 features work fine.

SMB is not supported. Windows workloads that need file system access to S3 still need FSx or a gateway solution.

Why did AWS disable SSE-C encryption by default?

This change flew under the radar next to S3 Files, but it affects every new bucket created after April 6, 2026.

SSE-C (Server-Side Encryption with Customer-Provided Keys) lets you bring your own encryption key on every PUT and GET request. S3 encrypts and decrypts using your key but never stores it. The idea is maximum control. The reality is operational risk. Lose the key, lose the data forever. AWS can't recover it for you. There's no "forgot my password" option.

AWS KMS solved this years ago with customer-managed keys (CMKs) that give you full ownership and control, plus key rotation, auditing through CloudTrail, and recovery options. For most workloads, KMS does everything SSE-C does, minus the footgun.

So AWS made SSE-C opt-in instead of opt-out. Here's how the rollout works:

What changes for new buckets

Every new general-purpose S3 bucket created after April 6, 2026 has SSE-C disabled by default. If you try to upload an object with SSE-C headers, you'll get an access denied error unless you explicitly enable SSE-C first.

To enable SSE-C on a new bucket:

# Explicitly allow SSE-C on a new bucket
aws s3api put-bucket-encryption \
  --bucket my-new-bucket \
  --server-side-encryption-configuration '{
    "Rules": [{
      "ApplyServerSideEncryptionByDefault": {
        "SSEAlgorithm": "AES256"
      },
      "BucketKeyEnabled": false
    }],
    "AllowSSEC": true
  }'

What changes for existing buckets

This is the part that might catch people off guard. AWS is also disabling SSE-C on existing buckets that have zero SSE-C encrypted objects. If you created a bucket, never used SSE-C, but your automation code includes SSE-C headers "just in case," those writes will start failing.

Existing buckets that actually contain SSE-C objects? No changes. AWS won't touch those.

Who this affects

If you're using AWS KMS (SSE-KMS) or S3-managed keys (SSE-S3) for encryption, this change does nothing to you. Your buckets already don't use SSE-C.

If you're one of the teams still on SSE-C, you'll want to:

Audit which buckets actually use SSE-C (aws s3api get-bucket-encryption)
Plan a migration to KMS for buckets that don't strictly need SSE-C
Explicitly re-enable SSE-C on new buckets where it's genuinely required

The rollout covers 37 AWS Regions, including GovCloud and China regions, and will complete over the next few weeks.

What do these changes tell us about where S3 is heading?

If I look at S3 Files and the SSE-C default together, they tell the same story: AWS is reducing the reasons you'd reach for anything other than S3.

Need file system access? You used to need EFS plus sync scripts. Now you mount S3 directly. Need encryption with your own keys? You used to reach for SSE-C. Now AWS is steering you toward KMS, which handles key management for you.

S3 now stores over 500 trillion objects and handles roughly 200 million requests per second. It turned 20 years old last month. And instead of letting it coast, AWS gave it the most significant capability upgrade since S3 Intelligent-Tiering launched in 2018.

For my own projects, I'm already replacing two EFS-backed data pipelines with S3 Files mounts. The sync cron jobs are gone. The drift alerts are gone. One mount point, one storage bill, and a 60-second commit window I can easily live with.

If you've been running parallel storage systems just to get file access to your S3 data, this week is a good week to rethink that architecture.

For the full details, see the official S3 Files announcement, the S3 Files product page, and the SSE-C security default announcement.

Keep Reading

AI-Driven Anomaly Detection for Security - How cloud infrastructure and AI work together for real-time threat detection.
Implementing the Outbox Pattern with CDC in Microservices - Storage design patterns that affect reliability in distributed systems.
The Day a React Patch Broke the Internet - Another deep dive into an infrastructure event that caught everyone off guard.

Handling Clock and Timezones Correctly in Java

Rabinarayan Patra — Wed, 07 Jan 2026 18:30:00 +0000

Pop quiz: What is wrong with this code?

@Service
public class TokenService {
    public boolean isExpired(Token token) {
        // ❌ The Villain
        return token.getExpiresAt().isBefore(LocalDateTime.now());
    }
}

It looks innocent. But LocalDateTime.now() is a hidden dependency on the server's system clock.

Testing is a nightmare : How do you test "token expiration" without Thread.sleep()? You can't control now().
Timezones are ignored : If your server is in UTC but LocalDateTime.now() picks up the system default (e.g., EST), your logic breaks.

How does java.time.Clock solve the hidden time dependency?

Since Java 8, we have had a built-in abstraction for time: java.time.Clock.

Instead of asking the System for the time, you ask the Clock. And because the Clock is an object, you can inject it.

Step 1: Define the Bean

In your Spring Boot configuration, define a global Clock bean. best practice is to always force UTC.

@Configuration
public class TimeConfig {

    @Bean
    public Clock clock() {
        return Clock.systemUTC();
    }
}

Step 2: Inject It

Now, refactor your service to depend on the Clock.

@Service
@RequiredArgsConstructor
public class TokenService {

    // ✅ The Hero
    private final Clock clock;

    public boolean isExpired(Token token) {
        // Ask the clock for "now"
        return token.getExpiresAt().isBefore(LocalDateTime.now(clock));
    }
}

Step 3: Testing "Time Travel"

This is where the magic happens. In your tests, you don't use the system clock. You use a Fixed Clock.

class TokenServiceTest {

    @Test
    void shouldFindExpiredToken() {
        // 1. Freeze time at specific date
        Instant fixedInstant = Instant.parse("2023-10-01T10:00:00Z");
        Clock fixedClock = Clock.fixed(fixedInstant, ZoneId.of("UTC"));

        TokenService service = new TokenService(fixedClock);

        // 2. Create a token that expires 1 second BEFORE the fixed time
        Token token = new Token();
        token.setExpiresAt(LocalDateTime.ofInstant(fixedInstant.minusSeconds(1), ZoneId.of("UTC")));

        // 3. Assert (Value is deterministic!)
        assertThat(service.isExpired(token)).isTrue();
    }
}

No Thread.sleep(). No flaky tests. Just pure deterministic logic.

Why should your production architecture always use UTC?

Dealing with users in Tokyo, London, and New York? Follow this golden rule:

Servers, APIs, and Databases always speak UTC.

1. Database

Always use TIMESTAMP WITH TIME ZONE (Postgres) or store as UTC DATETIME. In Java, map this to Instant or OffsetDateTime. Avoid LocalDateTime for storage as it lacks timezone context.

@Entity
public class Order {
    // ✅ Good: unambiguous point in timeline
    private Instant createdAt; 

    // ❌ Bad: ambiguous (Is this 10 AM Tokyo or 10 AM NY?)
    private LocalDateTime deliveryDue; 
}

2. API Layer

Spring Boot (via Jackson) behaves differently depending on configuration. Force it to standard ISO-8601 UTC.

# application.properties
spring.jackson.time-zone=UTC
spring.jackson.serialization.write-dates-as-timestamps=false

Now your JSON will always look like "2023-10-27T10:00:00Z".

3. The Frontend

The Browser knows the user's timezone.

Server sends : 2023-10-27T10:00:00Z
Browser JS : new Date('2023-10-27T10:00:00Z').toString() -> Displays 10:00 PM Tokyo Time.

Conversion happens at the Edge (the user's screen), never in the core logic.

Summary

Never use LocalDateTime.now() in business logic.
Always inject java.time.Clock.
Use Clock.fixed() in tests to time-travel.
Store everything as UTC (Instant).

Time is hard. But with Clock, at least it's testable.

For further reading, see the java.time.Clock Javadoc, the Java Date and Time API tutorial, and the Spring Boot Jackson datetime configuration reference.

Keep Reading

Integration Testing with Testcontainers in Spring Boot — Use Clock.fixed() alongside Testcontainers for fully deterministic integration tests.
10 Essential Java Libraries Beyond Lombok — More libraries that eliminate boilerplate, including testing and utility tools that complement good time handling.

Happy Coding! ⏱️

Sanitizer-Lib is Now Live on Maven Central

Rabinarayan Patra — Mon, 08 Dec 2025 18:30:00 +0000

It's official: Sanitizer-Lib is now available on Maven Central! 🚀

A few months ago, I introduced Sanitizer-Lib, a Java library designed to kill the boilerplate of input sanitization. No more manual .trim() calls, no more scattered string manipulation logic. Just clean, declarative annotations.

Since then, the feedback has been amazing. But there was one friction point: you had to use JitPack or build it locally.

Not anymore.

As of today, you can pull Sanitizer-Lib directly from Maven Central. It's production-ready, signed, and just a copy-paste away.

How do you add Sanitizer-Lib to your Maven or Gradle project?

Maven

Add this to your pom.xml:

<dependency>
    <groupId>io.github.rabinarayanpatra.sanitizer</groupId>
    <artifactId>sanitizer-spring</artifactId>
    <version>1.0.22</version>
</dependency>

Gradle

Add this to your build.gradle:

implementation("io.github.rabinarayanpatra:sanitizer-spring:1.0.22")

What problems does Sanitizer-Lib solve that manual validation doesn't?

If you missed the original deep dive, here is the 30-second pitch:

Instead of writing this validation spaghetti:

public void createUser(UserDto user) {
    if (user.getEmail() != null) {
        user.setEmail(user.getEmail().trim().toLowerCase());
    }
    // ... repeat for 10 other fields
}

You just do this:

public class UserDto {
    @Sanitize(using = {TrimSanitizer.class, LowerCaseSanitizer.class})
    private String email;
}

That's it. Incoming requests are automatically sanitized before they even hit your controller logic.

What changed from JitPack to Maven Central?

Publishing to Maven Central means:

No extra repository configuration — Maven Central is the default repository for every Maven and Gradle project
Signed artifacts — All JARs are GPG-signed, ensuring you're getting the authentic library
Reliable availability — Maven Central has 99.99% uptime, unlike JitPack which can have intermittent issues
Better IDE support — IntelliJ and Eclipse resolve Maven Central dependencies faster

Migration from JitPack

If you were using Sanitizer-Lib via JitPack, here's what to change:

Remove the JitPack repository from your pom.xml or build.gradle
Update the group ID from com.github.rabinarayanpatra to io.github.rabinarayanpatra.sanitizer
Update to the latest version (1.0.22)

The API remains 100% backward compatible — no code changes required.

Where can you learn more about Sanitizer-Lib?

For a full walkthrough of features, custom sanitizers, and Spring Boot integration, check out my detailed guide:

Read the Full Sanitizer-Lib Introduction

Or star the repo on GitHub: github.com/rabinarayanpatra/sanitizer-lib

For more information, see the Maven Central Repository Search and the Sonatype OSSRH Publishing Guide.

Keep Reading

Sanitizer-Lib: The Full Introduction — A complete walkthrough of all features, custom sanitizers, and Spring Boot integration.
10 Essential Java Libraries Beyond Lombok — More libraries that cut boilerplate and improve code quality alongside Sanitizer-Lib.

Happy coding!

DEV Community: Rabinarayan Patra

How to Set Up Sanity Studio in Next.js 16 (Embedded Dashboard)

What is Sanity Studio and why embed it in Next.js?

What do you need before installing Sanity in Next.js 16?

How do you scaffold Sanity Studio inside an existing Next.js app?

How do you wire the embedded Studio route at /studio?

How do you write a real content schema (post + author + category)?

How do you query Sanity content from a Server Component?

How do you configure CORS so the Studio talks to your project?

How do you deploy the embedded Studio to Vercel?

What are the common pitfalls in a Next.js 16 + Sanity setup?

What did we just build?

Keep Reading

How to Version REST APIs in Spring Framework 7 (Spring Boot 4)

What changed for API versioning in Spring Framework 7?

How do you turn on API versioning in Spring Boot 4?

How does the version attribute route requests?

Which versioning strategy should you pick?

Request header

Path segment

Query parameter

Media type

What's the difference between fixed and baseline versions?

How do you deprecate an API version with Sunset headers?

How was this done before Spring 7?

What pitfalls should you watch for?

Is built-in versioning worth migrating to?

Keep Reading

How to Set Up an SSH Tunnel for Local Database Access

What is an SSH tunnel and why use it for database access?

How do you set up a local port forward to a remote Postgres?

Running the tunnel in the background

A tidier setup with ~/.ssh/config

How do you connect from your GUI client through the tunnel?

How do you do the same for MySQL, Redis, and MongoDB?

How do you keep the tunnel alive with autossh and systemd?

The systemd user service

What are the common SSH tunnel mistakes to avoid?

What does the whole setup look like in 30 seconds?

Keep Reading

Spring AI 2.0 MCP Annotations: From Tool to Production

What changed in Spring AI 2.0 MCP annotations?

How do you build an MCP server with @McpTool?

How do you handle progress and async work?

How do you expose prompts and resources?

How do you choose between transports (stdio, SSE, Streamable HTTP)?

How do you register and test the server with Claude Code?

What are the production-readiness gotchas?

Conclusion

Keep Reading

Why MCP 2026-07-28 Spec Drops Sessions and Goes Stateless

What is the MCP 2026-07-28 spec release candidate?

Why was the 2025-11-25 stateful protocol hard to scale?

How does the stateless protocol core actually work?

What do Extensions, Tasks, and MCP Apps add?

What changes in authorization and error handling?

Which existing code breaks when you upgrade?

Should you migrate before July 28 or after?

What does this mean for your MCP servers?

Keep Reading

PostgreSQL 18 Temporal Foreign Keys with Spring Boot JPA

What problem do temporal foreign keys solve?

How does PostgreSQL 18 implement WITHOUT OVERLAPS and PERIOD?

How do you map daterange columns in Hibernate?

How do you write the entity and repository?

What are the gotchas with ON DELETE and temporal foreign keys?

When should you NOT use temporal foreign keys?

Conclusion

Keep Reading

Next.js 16.2 AGENTS.md and next-browser: A Hands-On Guide

What is AGENTS.md in Next.js 16.2?

How do you add AGENTS.md to an existing Next.js project?

What does the @vercel/next-browser CLI actually do?

How does the dev server lock file help AI agents?

How do you forward browser logs to the terminal?

Why does Vercel say AGENTS.md beat skills in their evals?

What changes did Next.js 16.2 make to rendering performance?

Does AGENTS.md replace Claude Code skills entirely?

What does this mean for the next year of framework design?

Keep Reading

A tidier setup with `~/.ssh/config`