diff --git a/.env.example b/.env.example
index baa5572..b1f9ccc 100644
--- a/.env.example
+++ b/.env.example
@@ -28,6 +28,20 @@ ICHAT_DB_URL=jdbc:postgresql://localhost:5432/intellistream_chat
 ICHAT_DB_USERNAME=ichat_role
 ICHAT_DB_PASSWORD=CHANGE-ME
 
+# Optional read replica. Off by default, and off means there is no second pool at all. Enabled,
+# every @Transactional(readOnly = true) is served from the replica, while writes, Flyway and raw
+# JDBC access stay on the primary above.
+#
+# A replica lags, so a read-only transaction may see a slightly older world than the write that
+# just returned. That is fine for history and search, and it is why the Lucene reconcile sweeps
+# stay on the primary. Blank username/password inherit the primary's, which is what a streaming
+# replica normally wants. Size the read pool with SPRING_-style Hikari keys under
+# ichat.datasource.replica.hikari.*; the shipped config sets none, so it is Boot's default of 10.
+# ICHAT_DB_REPLICA_ENABLED=false
+# ICHAT_DB_REPLICA_URL=jdbc:postgresql://replica.internal:5432/intellistream_chat
+# ICHAT_DB_REPLICA_USERNAME=
+# ICHAT_DB_REPLICA_PASSWORD=
+
 # --- Keycloak / OIDC ---
 KEYCLOAK_ISSUER_URI=https://auth.your-domain/realms/ichat-realm
 KEYCLOAK_CLIENT_ID=ichat-client
@@ -239,10 +253,12 @@ ICHAT_ASSETS_UNBUNDLED=false
 # Optional: Vault / OpenBao
 # =============================================================================================
 
-# Credentials only. The processor reads secret/data/${path} and maps exactly five keys —
-# db.username, db.password, keycloak.client-id, keycloak.client-secret, keycloak.issuer-uri —
-# into their Spring property names before anything consumes them. Any other key in the record is
-# ignored on purpose, so tuning stays here in the env file.
+# Connection details and credentials. The processor reads secret/data/${path} and maps exactly ten
+# keys — db.url, db.username, db.password, db.replica-enabled, db.replica-url,
+# db.replica-username, db.replica-password, keycloak.client-id, keycloak.client-secret,
+# keycloak.issuer-uri — into their Spring property names before anything consumes them. Any other
+# key in the record is ignored on purpose, so tuning stays here in the env file. Every one of them
+# is optional: a record holding only db.password overrides only that.
 # ICHAT_VAULT_ENABLED=false
 # ICHAT_VAULT_URI=
 # ICHAT_VAULT_TOKEN=
diff --git a/AGENTS.md b/AGENTS.md
index e7c80cc..dd033dc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -58,6 +58,7 @@ src/main/java/ai/intellistream/chat/
 │                  CallService, TurnCredentialService, CallScheduler, CallSessionListener
 ├── config/        SecurityConfig (two filter chains), WebSocketConfig,
 │                  StompAuthorizationConfig, MultipartConfig, VaultEnvironmentPostProcessor,
+│                  ReadReplicaDataSourceConfig / ReadReplicaProperties (optional replica),
 │                  RegistrationAuthorizationRequestResolver
 ├── domain/        JPA entities — User, Channel, Message, Conversation,
 │                  Attachment / ConversationAttachment, MessageReaction / ConversationReaction,
@@ -108,6 +109,8 @@ Several autoconfigurations that lived inside `spring-boot-autoconfigure` in 3.x
   - A client subscribes once per **joined channel**, not once per rendered sidebar row, so notification coverage cannot narrow when the sidebar's rendering changes. The per-session SUBSCRIBE budget is 2000/min because over-budget frames are *dropped, not refused* — at the old 200 the tail of a large account's own subscriptions vanished with no error anywhere.
   - **Authorisation happens once, at SUBSCRIBE.** The broker never re-checks, so revoking access needs the subscription taken away too: `ChannelSubscriptionRevoker` (channels) and its conversation sibling do that on leave, kick, and channel delete. Evicting the access cache alone only stops the *next* subscribe.
 - **`CurrentUser`** is the single bridge between Spring Security principals and the domain `User`. It provisions/upserts a `User` row from the OIDC subject the first time it sees a principal. Always go through it; don't read JWT/OidcUser claims in controllers.
+  **It resolves in two steps, and the order matters.** `UserService.findUnchanged` is a read-only single-`select` lookup that answers only when the row already agrees with the token on *every* field the write path sets — handle, email, display name, admin. Anything else returns empty and falls through to `UserService.upsert`, which is unchanged and still the only thing that writes. This runs on every authenticated request, so the difference is the whole per-request database cost of being logged in: one replica-eligible read instead of two primary reads inside a writable transaction. Both halves read their claims through `UserService.claimsOf`, one shared `ClaimView` — a second copy of the claim-reading logic would let the two disagree about whether anything changed, which is a write on every request and no error anywhere. The fall-through is stable, not repeating: `upsert` settles the row into exactly the shape `findUnchanged` tests for. `UserProvisioningFastPathTest` pins the per-field cases, including that a revoked `admin` claim must not be served from the existing row.
+  One consequence worth knowing: with a read replica configured, the suspension backstop in `CurrentUser.resolve` reads a row that may be up to the replication lag old. A ban issued through `BanService` is unaffected — it updates `SuspensionRegistry` before writing the row, and the filter refuses the request before it reaches the backstop. What lags is what the registry cannot see: a `suspended_at` edited directly in psql, or a ban issued by another node.
 - **Channel types.** `PUBLIC` channels are joinable by anyone via `ChannelService.join` **unless archived**. `PRIVATE` channels require `ChannelService.invite` by an admin. The creator becomes the first `ADMIN` member automatically, and `join` promotes the first person into an *empty* channel — otherwise a channel everyone left could never have an admin again. Members can `leave`; the last admin leaving hands the role to the longest-standing remaining member rather than being refused.
 - **Slug rule.** `Channel.slug` is generated from the name in `ChannelService.create` **and `ChannelService.rename`**: lowercased, non-alphanumerics collapsed to `-`, trimmed to 80 chars. A name with no alphanumerics is rejected. Renaming moves the slug, which is safe because nothing user-facing resolves a channel by slug — pages are `/channels/{id}` and every API route is id-keyed.
 - **UI icons come from the SVG sprite, never from emoji.** `templates/fragments/icon-sprite.html` holds every symbol; use it as `<svg class="icon"><use href="#icon-name"/></svg>` (`.icon` = 20px buttons, `.icon-sm` = 14px inline markers), and add a new 24×24 symbol rather than reaching for a glyph. Emoji as icons look wrong for three reasons: they render in the font's own colours so they ignore the theme and can't be dimmed or turned red for a destructive action, they're drawn differently on every platform, and they vanish entirely on hosts with no emoji font. Real emoji stay emoji — reactions, the picker, and custom status are content. Letterforms (`B`, `I`, `S`, `{ }`) in the composer toolbar are labels, not icons; leave them. Note that a message's action row has **one builder and several readers**: `attachActions` in `js/chat/index.js` builds it for channel messages (including server-rendered ones — `channels.html` renders no action row at all) and `js/conversation.js` does the same for DMs. The desktop `⋯` overflow menu and the mobile long-press sheet in `chat-kit.js` both *derive* from the buttons that builder produced, reading their `data-action` and `title`. Add an action in the builder and the other two inherit it; add a second builder and they won't.
@@ -127,6 +130,9 @@ Several autoconfigurations that lived inside `spring-boot-autoconfigure` in 3.x
 - **Sidebar.** `SidebarService.joinedFor(user)` returns a `SidebarView` of **every channel the user is a member of** — not a ranked shortlist — alphabetical (case-insensitive, ties by id), excluding archived ones, rendered as Favourites then Channels. Entries carry `joined` and `favourite`; there is no `admin` flag, because being a channel admin is not something you need in a list you scan fifty times a day (the members panel and the cog show it). The markup is `templates/fragments/sidebar.html`, one copy shared by `channels.html` *and* `conversation.html`, in the **left** `<aside class="sidebar">`.
 - **WebSocket destinations.** Send to `/app/channels/{id}/send`, subscribe to `/topic/channels/{id}` (plus `/typing`); conversations mirror it at `/app/conversations/{id}/…` and `/topic/conversations/{id}`. The server persists, renders Markdown, then broadcasts the `MessageDto`. Per-user queues carry what only the sender or recipient should see: `/user/queue/notices` (slash-command replies and refusals), `/user/queue/conversation-alerts` (DM notifications). A thread reply rides the normal channel topic with `threadParticipants` on the DTO — deliberately *not* routed to the mention bell, which is for things addressed to you by name.
 - **Open-in-view is off** (`spring.jpa.open-in-view=false`). Touch lazy associations inside `@Transactional` boundaries on the service, never in the controller.
+- **An optional read replica turns `readOnly = true` into a routing decision.** `ichat.datasource.replica.enabled` (off by default, and off means the beans don't exist — Boot's ordinary single pool) adds a second Hikari pool in `ReadReplicaDataSourceConfig`, behind a `LazyConnectionDataSourceProxy` whose read-only variant is the replica. `@Transactional(readOnly = true)` then lands on the replica; writes, Flyway, and raw `DataSource`/`JdbcTemplate` access land on the primary. Note that a **Spring Data repository call from a non-transactional caller is a read-only transaction** — `SimpleJpaRepository` is annotated `@Transactional(readOnly = true)` at class level — so the controllers that hold a repository directly route to the replica too; only the raw-JDBC path opts out by never having a transaction at all. The laziness is the mechanism, not a tuning choice: Hibernate checks a connection out when the transaction begins, which is before the read-only flag exists, so a pool wired straight to the EntityManagerFactory would have taken a primary connection before anyone could route it. Two things follow.
+  - `readOnly = true` now means "this may read a slightly stale world", so it is **wrong for a read that decides to delete something** or that must see a write this process just made. The Lucene↔Postgres reconciles in `CleanupTasks` and `LuceneBootstrap` are the cases here, and all three carry a comment saying why they use a plain `@Transactional` — putting `readOnly = true` back turns replica lag into deleted search documents. Adding it to a service method that only reads is exactly right and needs no thought.
+  - The replica pool is marked read-only at the driver rather than per transaction, because `LazyConnectionDataSourceProxy` suppresses the per-transaction `setReadOnly` once a dedicated read-only DataSource is configured. Flyway is pinned to the writer with `@FlywayDataSource` rather than left to follow `@Primary`. Both are asserted in `ReadReplicaDataSourceConfigTest`; `ReadReplicaRoutingIT` asserts the routing itself against a real Postgres, since every link in the chain is framework internals a Boot upgrade could move.
 - **The STOMP channel executors are load-bearing.** `WebSocketConfig` sets them *unconditionally* via `registration.executor(...)`, with sizes constructor-injected (not `@Value` fields — those can be unset when the configurer callback runs). A missing inbound executor silently lands every `@MessageMapping` on the single-threaded heartbeat scheduler, which caps the whole server at one message in flight. `StompChannelDiagnostics` logs the resolved executors at startup; check that line before trusting any throughput number. See `scalability.md`.
 - **The message send path is the hot path** and is deliberately query-free: the domain `User` comes from the STOMP session (cached at CONNECT by `StompAuthorizationConfig`), the channel and write-access decision from `ChannelAccessCache`, and mentions from what `syncMentions` already resolved. A body with no `@` never reaches mention resolution at all. The exception is a **broadcast** handle (`@channel`/`@here`/`@everyone`), which costs one member fetch plus a batched INSERT per 500 recipients — ordinary messages are untouched. If you add work to `ChatWebSocketController.send` or `MessageService.postWithMentions`, check `benchmark/write-stages.sh` afterwards.
 - **`ChannelAccessCache` caches only *positive* access decisions, and everything that can turn one false has to say so.** Membership used to be add-only; it isn't — `ChannelService.leave` and `removeMember` exist, and both call `evictMember`. A channel's own state changes too: rename, archive and unarchive all call `evictChannel`, and archiving matters most because the archived check lives inside `requireWriteAccess` **before** the cached short-circuit — behind it, the members with the warmest entries (the ones who post most) would keep posting into an archived channel for the whole TTL.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c422602..d6dd05a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -108,7 +108,19 @@ against anything: there is no released version for something to have been fixed
 - Runs a workspace of a thousand people in **under a gigabyte of memory on a single core**.
 - **Flyway migrations**, **health endpoints**, and configuration through environment variables —
   every tunable listed in `.env.example` — with an optional **Vault/OpenBao** backend for the
-  five credentials.
+  database and Keycloak credentials.
+- **An optional read replica.** Point `ICHAT_DB_REPLICA_URL` at a standby and every
+  `@Transactional(readOnly = true)` is served from it, while writes and migrations stay on the
+  primary — 90–95% of queries on a read-heavy mix, and all of them on an endpoint that only reads.
+  Off by default, and off means the second pool does not exist rather than sitting idle — a
+  deployment that never asks for one gains no proxy and no new way to fail. The replica can be
+  configured entirely from Vault alongside the primary's credentials.
+- **Identifying the caller costs one read instead of three.** Resolving a logged-in principal used
+  to run two queries inside a writable transaction on every single request, to re-derive a row that
+  had not changed since the request before. It now takes a read-only single-`select` fast path and
+  only falls back to the full upsert when the token actually disagrees with the stored row. This is
+  a saving on its own and the thing that makes the replica worthwhile, since the old cost fell on
+  every request regardless of how little work it did.
 - **An AlmaLinux installer** and a separate **SELinux hardening script**, both verified end to
   end on AlmaLinux 10.2 with SELinux enforcing.
 - **Container quick start** with `podman compose up -d`.
diff --git a/scalability.md b/scalability.md
index bf2fa64..8c184da 100644
--- a/scalability.md
+++ b/scalability.md
@@ -324,6 +324,40 @@ pool of 10 — worth knowing before you copy a number from here into production.
 acquire time at 13,000 posts/second is 0.03 ms with zero pending — the pool is not a constraint at
 this rate, and raising it would not help. Postgres itself sat at ~10% CPU.
 
+### Read replica
+
+`ichat.datasource.replica.enabled=true` plus a URL adds a second Hikari pool against a standby, and
+every `@Transactional(readOnly = true)` is served from it. Writes, Flyway and raw JDBC access stay
+on the primary. Sized separately through `ichat.datasource.replica.hikari.*`.
+
+Most of the read volume moves. A `GET /channels/{id}` runs about fourteen read-only transactions
+(the `CurrentUser` lookup, sidebar, conversations, the message page and its attachments, reactions,
+reply counts and polls, membership, notification level) against a single primary read — the one
+inside `markRead`'s write. An endpoint that only reads puts nothing on the primary at all. Call it
+**90–95% of `SELECT`s on a read-heavy mix**, and 100% for the pure-read endpoints.
+
+That depends on `CurrentUser` resolving a settled principal through `UserService.findUnchanged`
+rather than `upsert` — see the `CurrentUser` bullet in AGENTS.md. Before that fast path existed,
+every authenticated request spent two `SELECT`s inside a writable transaction just to identify the
+caller, which pinned the figure nearer 80% and made small API calls a roughly even split. It is
+the single change that decides whether a replica is worth having: it is a fixed per-request cost,
+so it dominates exactly the light endpoints a replica is otherwise best at absorbing.
+
+WebSocket sends contribute almost no read volume either way — the send path is deliberately
+query-free, and the user is resolved once at CONNECT rather than per frame. Both pools are named
+(`ichat-writer`, `ichat-reader`), so measure the real split per pool rather than trusting this
+paragraph.
+
+Note what the numbers above say about when this is worth doing: at 17,000 messages/second Postgres
+is at ~10% CPU, so the write path is nowhere near needing relief. **The case for a replica here is
+read volume and availability, not write throughput** — a workspace whose history, search hydration
+and sidebar reads dominate the query mix, or a deployment that wants the primary reserved for
+writes. Adding one to chase message throughput will not move the number this document reports.
+
+The cost is that a replica lags, so a read-only transaction may see a slightly older world than the
+write that just returned. Reads that decide to *delete* something must therefore stay on the
+primary; the Lucene reconcile sweeps do, deliberately. See the read-replica bullet in AGENTS.md.
+
 ### Kernel
 
 The stock kernel is provisioned for a workstation, not 10⁵ sockets. Persist these in
diff --git a/src/main/java/ai/intellistream/chat/cleanup/CleanupTasks.java b/src/main/java/ai/intellistream/chat/cleanup/CleanupTasks.java
index 9d65c4d..7b6ae3e 100644
--- a/src/main/java/ai/intellistream/chat/cleanup/CleanupTasks.java
+++ b/src/main/java/ai/intellistream/chat/cleanup/CleanupTasks.java
@@ -142,7 +142,13 @@ private void sweepDir(String label, Path root, Supplier<Set<String>> liveKeys) {
     /** CLEAN-3: reconcile the Lucene index with the messages table — index the missing, drop the stale. */
     @Scheduled(fixedDelayString = "${ichat.cleanup.reconcile-ms:3600000}",
                initialDelayString = "${ichat.cleanup.initial-delay-ms:300000}")
-    @Transactional(readOnly = true)
+    // Deliberately NOT readOnly = true. This method reads nothing but it deletes on what it read,
+    // and readOnly is what routes a transaction to the read replica when one is configured
+    // (ReadReplicaDataSourceConfig). A replica lags; a message committed a moment ago is in the
+    // index and not yet in the replica's copy of `messages`, which reads here as "stale" — and
+    // the sweep would delete the search document for a message that exists. The read ordering
+    // below (N3) closes the same window for the primary; only a primary read closes it at all.
+    @Transactional
     public void reconcileSearchIndex() {
         if (!props.isEnabled()) return;
         // Snapshot the INDEX first, then the DB (N3). A message posted+indexed between the two reads
@@ -202,7 +208,9 @@ public void reconcileSearchIndex() {
      */
     @Scheduled(fixedDelayString = "${ichat.cleanup.reconcile-ms:3600000}",
                initialDelayString = "${ichat.cleanup.initial-delay-ms:300000}")
-    @Transactional(readOnly = true)
+    // Not readOnly = true, for the reason spelled out on reconcileSearchIndex above: this one
+    // deletes too, so it has to read the primary.
+    @Transactional
     public void reconcileConversationSearchIndex() {
         if (!props.isEnabled()) return;
         // Index first, then the DB — see reconcileSearchIndex above (N3).
diff --git a/src/main/java/ai/intellistream/chat/config/ReadReplicaDataSourceConfig.java b/src/main/java/ai/intellistream/chat/config/ReadReplicaDataSourceConfig.java
new file mode 100644
index 0000000..6f95e0f
--- /dev/null
+++ b/src/main/java/ai/intellistream/chat/config/ReadReplicaDataSourceConfig.java
@@ -0,0 +1,231 @@
+/*
+ * Copyright 2026 IntelliStream AS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package ai.intellistream.chat.config;
+
+import com.zaxxer.hikari.HikariDataSource;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.event.ApplicationReadyEvent;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.boot.flyway.autoconfigure.FlywayDataSource;
+import org.springframework.boot.jdbc.DataSourceBuilder;
+import org.springframework.boot.jdbc.autoconfigure.DataSourceProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+import org.springframework.context.event.EventListener;
+import org.springframework.jdbc.datasource.LazyConnectionDataSourceProxy;
+
+import javax.sql.DataSource;
+
+/**
+ * Optional second connection pool against a Postgres read replica, so read-only transactions
+ * leave the primary alone.
+ *
+ * <p><b>Off unless asked for.</b> The whole class is gated on
+ * {@code ichat.datasource.replica.enabled=true}. Without it none of these beans exist, Boot's
+ * {@code DataSourceAutoConfiguration} builds the single pool it always has, and nothing about the
+ * application changes — the same shape as the optional Vault backend. With it,
+ * {@code DataSourceAutoConfiguration} backs off (it is {@code @ConditionalOnMissingBean(DataSource)})
+ * and the three beans below replace it.
+ *
+ * <h2>What decides which pool a query uses</h2>
+ *
+ * <p>{@code @Transactional(readOnly = true)} — nothing else. There is no annotation to learn and no
+ * thread-local to set. The chain is entirely Spring's own:
+ *
+ * <ol>
+ *   <li>{@code HibernateJpaDialect.beginTransaction} sees {@code definition.isReadOnly()} and calls
+ *       {@code DataSourceUtils.prepareConnectionForTransaction}, which is
+ *       {@code connection.setReadOnly(true)}.</li>
+ *   <li>That connection is a {@link LazyConnectionDataSourceProxy} handle holding no physical
+ *       connection yet, so the call just records a flag.</li>
+ *   <li>On the first actual statement the proxy fetches a real connection, and because the flag is
+ *       set it fetches it from the DataSource handed to
+ *       {@link LazyConnectionDataSourceProxy#setReadOnlyDataSource} — the replica.</li>
+ * </ol>
+ *
+ * <p><b>The laziness is the mechanism, not a tuning choice.</b> Hibernate checks a connection out
+ * when the transaction begins, which is *before* {@code AbstractPlatformTransactionManager} has
+ * finished preparing it. Hand the EntityManagerFactory a pool directly and every transaction —
+ * read-only or not — has already taken a primary connection by the time anyone could route it.
+ * The proxy is what moves the checkout to first use, which is the first moment the read-only flag
+ * exists.
+ *
+ * <p>Consequently a read that never joins a transaction — a raw {@code DataSource} connection or a
+ * {@code JdbcTemplate} call — goes to the <b>primary</b>, because nothing ever set the flag. That
+ * is the safe direction to be wrong in.
+ *
+ * <p><b>A Spring Data repository call is not that.</b> {@code SimpleJpaRepository} is annotated
+ * {@code @Transactional(readOnly = true)} at class level, so {@code repo.findById(…)} invoked from
+ * a non-transactional caller starts its own read-only transaction and lands on the replica —
+ * including the handful of controllers that hold a repository directly. The rule is genuinely
+ * "read-only transactions go to the replica"; it is only the raw-JDBC path that opts out by
+ * never having a transaction at all.
+ *
+ * <h2>What must not run on the replica</h2>
+ *
+ * <p>A replica lags. Anything that reads in order to <em>delete</em> something, or that must see a
+ * write this process just made, has to use a plain {@code @Transactional} instead — the
+ * Lucene↔Postgres reconcile sweeps in {@code CleanupTasks} and {@code LuceneBootstrap} are the
+ * cases in this codebase, and each says so at the annotation. Adding {@code readOnly = true} to
+ * one of those turns replica lag into deleted search documents.
+ *
+ * <p>Flyway is pinned to the primary explicitly ({@code @FlywayDataSource}) rather than left to
+ * pick up the {@code @Primary} bean, so a migration can never depend on which way the proxy
+ * happened to route.
+ */
+@Configuration(proxyBeanMethods = false)
+@ConditionalOnProperty(name = "ichat.datasource.replica.enabled", havingValue = "true")
+@EnableConfigurationProperties(ReadReplicaProperties.class)
+public class ReadReplicaDataSourceConfig {
+
+    private static final Logger log = LoggerFactory.getLogger(ReadReplicaDataSourceConfig.class);
+
+    /**
+     * Boot registers this itself from {@code DataSourceAutoConfiguration}, which has backed off
+     * because this class contributes a {@link DataSource}. Declaring it here keeps
+     * {@code spring.datasource.*} meaning exactly what it always did.
+     */
+    @Bean
+    @Primary
+    @ConfigurationProperties("spring.datasource")
+    public DataSourceProperties dataSourceProperties() {
+        return new DataSourceProperties();
+    }
+
+    /**
+     * The primary pool: every write, every non-transactional read, every migration. Binds
+     * {@code spring.datasource.hikari.*} exactly as the auto-configuration would.
+     */
+    @Bean
+    @FlywayDataSource
+    @ConfigurationProperties("spring.datasource.hikari")
+    public HikariDataSource writerDataSource(DataSourceProperties properties) {
+        var writer = properties.initializeDataSourceBuilder().type(HikariDataSource.class).build();
+        namePool(writer, "ichat-writer");
+        return writer;
+    }
+
+    /**
+     * The replica pool. Sized independently through {@code ichat.datasource.replica.hikari.*} —
+     * read traffic and write traffic are different shapes, and the replica is usually the one that
+     * wants the larger pool.
+     *
+     * <p>The pool is marked read-only rather than each transaction marking its connection:
+     * {@link LazyConnectionDataSourceProxy} deliberately suppresses the per-transaction
+     * {@code setReadOnly} call when a dedicated read-only DataSource is configured, expecting the
+     * flag to be a pool default. That saves a round trip per transaction, and it means a write that
+     * somehow reaches this pool fails on the JDBC driver rather than on the standby.
+     */
+    @Bean
+    @ConfigurationProperties("ichat.datasource.replica.hikari")
+    public HikariDataSource readerDataSource(DataSourceProperties primary, ReadReplicaProperties replica) {
+        if (!replica.hasUrl()) {
+            // Fail at boot, the way the Vault backend does. An operator who set enabled=true wants
+            // reads on the replica; silently serving them from the primary would look like it
+            // worked and show up months later as a primary that never got any relief.
+            throw new IllegalStateException(
+                    "ichat.datasource.replica.enabled=true but ichat.datasource.replica.url is not set");
+        }
+        var reader = DataSourceBuilder.create()
+                .type(HikariDataSource.class)
+                .driverClassName(primary.determineDriverClassName())
+                .url(replica.getUrl())
+                // Blank inherits the primary's credentials — a streaming replica normally carries
+                // the same roles as the machine it replicates.
+                .username(blankTo(replica.getUsername(), primary.determineUsername()))
+                .password(blankTo(replica.getPassword(), primary.determinePassword()))
+                .build();
+        namePool(reader, "ichat-reader");
+        // Set before the @ConfigurationProperties binding runs, so it is a default an operator can
+        // still override with ichat.datasource.replica.hikari.read-only rather than a lock.
+        reader.setReadOnly(true);
+        return reader;
+    }
+
+    /**
+     * The bean everything else injects: JPA, {@code JdbcTemplate}, the health endpoint. Lazy so the
+     * read-only flag exists before a connection is taken (see the class javadoc), and carrying the
+     * replica as its read-only variant.
+     */
+    @Bean
+    @Primary
+    public DataSource dataSource(HikariDataSource writerDataSource, HikariDataSource readerDataSource) {
+        var proxy = new LazyConnectionDataSourceProxy(writerDataSource);
+        proxy.setReadOnlyDataSource(readerDataSource);
+        return proxy;
+    }
+
+    /**
+     * Registered as a bean rather than put on the configuration class, which cannot inject its own
+     * beans without a cycle.
+     */
+    @Bean
+    public ReplicaDiagnostics readReplicaDiagnostics(HikariDataSource readerDataSource) {
+        return new ReplicaDiagnostics(readerDataSource);
+    }
+
+    /**
+     * Says at startup what the routing actually resolved to. The failure this exists for is a
+     * "replica" URL that points back at the primary — nothing misbehaves, the pool connects, and
+     * the deployment simply runs two pools against one machine while believing it split the load.
+     * {@code pg_is_in_recovery()} is the one question that distinguishes them.
+     *
+     * <p>Runs after startup and never fails it: a replica that is briefly unreachable is a reason
+     * to log loudly, not to refuse to serve. The pool itself is lazy for the same reason.
+     */
+    public static class ReplicaDiagnostics {
+
+        private final HikariDataSource reader;
+
+        ReplicaDiagnostics(HikariDataSource reader) {
+            this.reader = reader;
+        }
+
+        @EventListener(ApplicationReadyEvent.class)
+        public void reportReplicaRouting() {
+            log.info("Read replica active — @Transactional(readOnly = true) routes to {} (pool max {})",
+                    reader.getJdbcUrl(), reader.getMaximumPoolSize());
+            try (var connection = reader.getConnection();
+                 var statement = connection.prepareStatement("SELECT pg_is_in_recovery()");
+                 var rs = statement.executeQuery()) {
+                if (rs.next() && !rs.getBoolean(1)) {
+                    log.warn("Replica at {} reports pg_is_in_recovery() = false — it is not a standby. "
+                            + "Check ichat.datasource.replica.url; as configured, read and write pools "
+                            + "are both hitting the same server.", reader.getJdbcUrl());
+                }
+            } catch (Exception e) {
+                log.warn("Could not verify the read replica at {} — read-only transactions will fail "
+                        + "until it is reachable", reader.getJdbcUrl(), e);
+            }
+        }
+    }
+
+    /** Leave an operator-supplied {@code pool-name} alone; replace Hikari's anonymous default. */
+    private static void namePool(HikariDataSource ds, String name) {
+        if (ds.getPoolName() == null || ds.getPoolName().startsWith("HikariPool-")) {
+            ds.setPoolName(name);
+        }
+    }
+
+    private static String blankTo(String value, String fallback) {
+        return (value == null || value.isBlank()) ? fallback : value;
+    }
+}
diff --git a/src/main/java/ai/intellistream/chat/config/ReadReplicaProperties.java b/src/main/java/ai/intellistream/chat/config/ReadReplicaProperties.java
new file mode 100644
index 0000000..c7e1d60
--- /dev/null
+++ b/src/main/java/ai/intellistream/chat/config/ReadReplicaProperties.java
@@ -0,0 +1,71 @@
+/*
+ * Copyright 2026 IntelliStream AS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package ai.intellistream.chat.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/**
+ * Connection settings for an optional Postgres read replica, bound from
+ * {@code ichat.datasource.replica.*}.
+ *
+ * <p>Off by default: with {@code enabled=false} (or absent) nothing in
+ * {@link ReadReplicaDataSourceConfig} is registered and Boot's ordinary
+ * {@code DataSourceAutoConfiguration} builds the single pool it always has. That is the same
+ * "optional means genuinely absent" contract {@link VaultEnvironmentPostProcessor} follows —
+ * a deployment that never sets these properties has no second pool, no proxy, and no new
+ * failure mode.
+ *
+ * <p>{@code username} and {@code password} fall back to the primary's
+ * ({@code spring.datasource.*}) when left blank, because a streaming replica usually carries the
+ * same roles as the machine it replicates. Set them only when the replica has its own login —
+ * a dedicated read-only role, or a pooler in front of it.
+ *
+ * <p>All three of {@code url}, {@code username} and {@code password} can equally come from Vault;
+ * see {@link VaultEnvironmentPostProcessor} for the record shape.
+ */
+@ConfigurationProperties("ichat.datasource.replica")
+public class ReadReplicaProperties {
+
+    /** Master switch. False (the default) means no replica pool exists at all. */
+    private boolean enabled = false;
+
+    /** JDBC URL of the replica. Required when enabled — boot fails loudly if it is blank. */
+    private String url = "";
+
+    /** Replica login. Blank inherits {@code spring.datasource.username}. */
+    private String username = "";
+
+    /** Replica password. Blank inherits {@code spring.datasource.password}. */
+    private String password = "";
+
+    public boolean isEnabled() { return enabled; }
+    public void setEnabled(boolean enabled) { this.enabled = enabled; }
+
+    public String getUrl() { return url; }
+    public void setUrl(String url) { this.url = url; }
+
+    public String getUsername() { return username; }
+    public void setUsername(String username) { this.username = username; }
+
+    public String getPassword() { return password; }
+    public void setPassword(String password) { this.password = password; }
+
+    /** True once the replica has somewhere to connect to. */
+    public boolean hasUrl() {
+        return url != null && !url.isBlank();
+    }
+}
diff --git a/src/main/java/ai/intellistream/chat/config/VaultEnvironmentPostProcessor.java b/src/main/java/ai/intellistream/chat/config/VaultEnvironmentPostProcessor.java
index c212042..91ce7bf 100644
--- a/src/main/java/ai/intellistream/chat/config/VaultEnvironmentPostProcessor.java
+++ b/src/main/java/ai/intellistream/chat/config/VaultEnvironmentPostProcessor.java
@@ -65,8 +65,12 @@
  * </ul>
  *
  * <p>Vault record fields it copies into the Spring environment:
- * {@code db.username}, {@code db.password}, {@code keycloak.client-id},
- * {@code keycloak.client-secret}, {@code keycloak.issuer-uri}.
+ * {@code db.url}, {@code db.username}, {@code db.password}, {@code db.replica-enabled},
+ * {@code db.replica-url}, {@code db.replica-username}, {@code db.replica-password},
+ * {@code keycloak.client-id}, {@code keycloak.client-secret}, {@code keycloak.issuer-uri}.
+ * The four {@code db.replica-*} keys configure the optional read replica
+ * ({@link ReadReplicaDataSourceConfig}); like everything else here they are optional, and a
+ * record that omits them leaves the env-var chain in charge.
  */
 public class VaultEnvironmentPostProcessor implements EnvironmentPostProcessor {
 
@@ -95,9 +99,10 @@ public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplicatio
         Map<String, Object> secrets = fetchKvV2(URI.create(uri), token, path);
         var mapped = mapToSpringProperties(secrets);
         if (mapped.isEmpty()) {
-            log.warn("Vault path {} contained no recognised keys (looked for: db.username, db.password, "
-                    + "keycloak.client-id, keycloak.client-secret, keycloak.issuer-uri); "
-                    + "leaving env-var defaults in place.", path);
+            log.warn("Vault path {} contained no recognised keys (looked for: db.url, db.username, "
+                    + "db.password, db.replica-enabled, db.replica-url, db.replica-username, "
+                    + "db.replica-password, keycloak.client-id, keycloak.client-secret, "
+                    + "keycloak.issuer-uri); leaving env-var defaults in place.", path);
             return;
         }
         // First in the chain → wins over command-line, env, and YAML for these specific keys.
@@ -152,8 +157,17 @@ private static Map<String, Object> fetchKvV2(URI vaultUri, String token, String
      */
     static Map<String, Object> mapToSpringProperties(Map<String, Object> secrets) {
         var out = new LinkedHashMap<String, Object>();
+        copyIfPresent(secrets, "db.url", out, "spring.datasource.url");
         copyIfPresent(secrets, "db.username", out, "spring.datasource.username");
         copyIfPresent(secrets, "db.password", out, "spring.datasource.password");
+        // Optional read replica (ReadReplicaDataSourceConfig). The whole record is mappable, the
+        // enabled flag included, so a deployment can be switched onto a replica by editing Vault
+        // and restarting — the alternative is a topology decision split across two places.
+        // The flag is read by @ConditionalOnProperty, which evaluates well after this runs.
+        copyIfPresent(secrets, "db.replica-enabled", out, "ichat.datasource.replica.enabled");
+        copyIfPresent(secrets, "db.replica-url", out, "ichat.datasource.replica.url");
+        copyIfPresent(secrets, "db.replica-username", out, "ichat.datasource.replica.username");
+        copyIfPresent(secrets, "db.replica-password", out, "ichat.datasource.replica.password");
         copyIfPresent(secrets, "keycloak.client-id",
                 out, "spring.security.oauth2.client.registration.keycloak.client-id");
         copyIfPresent(secrets, "keycloak.client-secret",
diff --git a/src/main/java/ai/intellistream/chat/moderation/SuspensionRegistry.java b/src/main/java/ai/intellistream/chat/moderation/SuspensionRegistry.java
index 060558a..c14342e 100644
--- a/src/main/java/ai/intellistream/chat/moderation/SuspensionRegistry.java
+++ b/src/main/java/ai/intellistream/chat/moderation/SuspensionRegistry.java
@@ -44,7 +44,9 @@
  * {@code false} only <em>after</em> the unsuspend commits. Nothing else in the application writes
  * {@code suspended_at}. And it is not the last word — {@code CurrentUser.resolve} re-checks the row
  * it just loaded, so a request that reaches a controller is judged on database state regardless of
- * what this says.
+ * what this says. (With a read replica configured that row may be up to the replication lag old;
+ * this set is not, which is why the two together are stronger than either. See the note at the
+ * suspension check in {@code CurrentUser.resolve}.)
  *
  * <p><b>Single-process state</b>, like {@code RateLimiter} and {@code PresenceTracker}. A second
  * instance would not learn about a ban issued on the first until it restarted; that is one more
diff --git a/src/main/java/ai/intellistream/chat/search/LuceneBootstrap.java b/src/main/java/ai/intellistream/chat/search/LuceneBootstrap.java
index 5e98ae2..8f9ba76 100644
--- a/src/main/java/ai/intellistream/chat/search/LuceneBootstrap.java
+++ b/src/main/java/ai/intellistream/chat/search/LuceneBootstrap.java
@@ -56,7 +56,12 @@ public LuceneBootstrap(MessageIndexService messageIndex,
     private static final int PAGE_SIZE = 5000;
 
     @EventListener(ApplicationReadyEvent.class)
-    @Transactional(readOnly = true)
+    // Deliberately NOT readOnly = true: that flag routes the transaction to the read replica when
+    // one is configured (ReadReplicaDataSourceConfig), and a lagging replica makes a
+    // just-committed message look absent from Postgres — which reconcileTail() classifies as
+    // "stale" and deletes from the index. The server is already accepting messages when this
+    // runs, so the window is real. Same reasoning as CleanupTasks' reconcile sweeps.
+    @Transactional
     public void rebuildOrReconcile() {
         // An index written by an older build has documents missing a field the current queries
         // read (see MessageIndexService.SCHEMA_VERSION). Reconciling wouldn't touch them — every
diff --git a/src/main/java/ai/intellistream/chat/security/CurrentUser.java b/src/main/java/ai/intellistream/chat/security/CurrentUser.java
index c2b6c68..907083f 100644
--- a/src/main/java/ai/intellistream/chat/security/CurrentUser.java
+++ b/src/main/java/ai/intellistream/chat/security/CurrentUser.java
@@ -73,23 +73,34 @@ public User resolve(Authentication auth) {
         var principal = auth.getPrincipal();
         User user;
         if (principal instanceof OidcUser oidc) {
-            user = userService.provisionFromOidc(oidc);
+            user = userService.findUnchanged(UserService.claimsOf(oidc))
+                    .orElseGet(() -> userService.provisionFromOidc(oidc));
         } else if (auth instanceof JwtAuthenticationToken jwtAuth) {
-            user = userService.provisionFromJwt(jwtAuth.getToken());
+            var token = jwtAuth.getToken();
+            user = userService.findUnchanged(UserService.claimsOf(token))
+                    .orElseGet(() -> userService.provisionFromJwt(token));
         } else if (principal instanceof Jwt jwt) {
-            user = userService.provisionFromJwt(jwt);
+            user = userService.findUnchanged(UserService.claimsOf(jwt))
+                    .orElseGet(() -> userService.provisionFromJwt(jwt));
         } else {
             // Don't echo the principal class name in the response — log it server-side and
             // reply with a generic message so we don't leak internal types to API clients.
             log.warn("Unsupported principal type: {}", principal == null ? "null" : principal.getClass().getName());
             throw new AccessDeniedException("Unsupported principal type");
         }
-        // Suspension is judged on the row we have just loaded, which makes this the one check that
-        // cannot be stale: every controller, every page, and the STOMP CONNECT frame come through
-        // here, and none of them pays an extra query for it. SuspensionEnforcementFilter answers
-        // the same question earlier and from memory so it can return a useful body; this is the
-        // backstop that holds when that in-memory view is wrong, and the reason a hand-edited
-        // suspended_at takes effect without a restart.
+        // Suspension is judged on the row we have just loaded: every controller, every page, and
+        // the STOMP CONNECT frame come through here, and none of them pays an extra query for it.
+        // SuspensionEnforcementFilter answers the same question earlier and from memory so it can
+        // return a useful body; this is the backstop that holds when that in-memory view is wrong,
+        // and the reason a hand-edited suspended_at takes effect without a restart.
+        //
+        // With a read replica configured, "without a restart" becomes "within replication lag":
+        // the fast path above is a read-only transaction, so the row may be a moment old. That
+        // costs nothing in the case this backstop mostly exists for — a ban issued through
+        // BanService updates SuspensionRegistry before it writes the row, so the filter refuses
+        // the request before it ever reaches here. What lags is the case the registry cannot see:
+        // a suspended_at edited straight in psql, or a ban issued by another node. Both are
+        // delayed by the lag, neither is missed.
         if (user.isSuspended()) {
             throw new AccountSuspendedException(user.getUsername());
         }
diff --git a/src/main/java/ai/intellistream/chat/service/UserService.java b/src/main/java/ai/intellistream/chat/service/UserService.java
index 267f6bd..398f5f8 100644
--- a/src/main/java/ai/intellistream/chat/service/UserService.java
+++ b/src/main/java/ai/intellistream/chat/service/UserService.java
@@ -27,6 +27,8 @@
 import java.time.Duration;
 import java.time.Instant;
 import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.regex.Pattern;
@@ -77,30 +79,84 @@ public UserService(UserRepository userRepository,
      */
     private static final String ADMIN_REALM_ROLE = KeycloakRolesConverter.ADMIN_REALM_ROLE;
 
-    @Transactional
-    public User provisionFromOidc(OidcUser oidc) {
+    /**
+     * What the identity provider says an account should look like, extracted from a token and
+     * carrying no database state. One shape for both token flavours so the provisioning path and
+     * the read-only fast path below cannot drift in how they read a claim — the failure that
+     * would produce is a fast path that thinks nothing changed while {@link #upsert} thinks
+     * something did, which is a write on every single request and no error anywhere.
+     */
+    public record ClaimView(String subject, String username, String email,
+                            String displayName, boolean admin) {}
+
+    public static ClaimView claimsOf(OidcUser oidc) {
         var subject = oidc.getSubject();
         var username = sanitizeUsername(firstNonBlank(
                 oidc.getPreferredUsername(),
                 oidc.getEmail(),
                 subject), subject);
-        var email = oidc.getEmail();
-        var displayName = firstNonBlank(oidc.getFullName(), username);
-        var admin = isAdminFromClaims(oidc.getClaimAsMap("realm_access"));
-        return upsert(subject, username, email, displayName, admin);
+        return new ClaimView(subject, username, oidc.getEmail(),
+                firstNonBlank(oidc.getFullName(), username),
+                isAdminFromClaims(oidc.getClaimAsMap("realm_access")));
     }
 
-    @Transactional
-    public User provisionFromJwt(Jwt jwt) {
+    public static ClaimView claimsOf(Jwt jwt) {
         var subject = jwt.getSubject();
         var username = sanitizeUsername(firstNonBlank(
                 jwt.getClaimAsString("preferred_username"),
                 jwt.getClaimAsString("email"),
                 subject), subject);
-        var email = jwt.getClaimAsString("email");
-        var displayName = firstNonBlank(jwt.getClaimAsString("name"), username);
-        var admin = isAdminFromClaims(jwt.getClaimAsMap("realm_access"));
-        return upsert(subject, username, email, displayName, admin);
+        return new ClaimView(subject, username, jwt.getClaimAsString("email"),
+                firstNonBlank(jwt.getClaimAsString("name"), username),
+                isAdminFromClaims(jwt.getClaimAsMap("realm_access")));
+    }
+
+    /**
+     * The row for these claims, if it already exists and already agrees with them — the common
+     * case on every request after the first.
+     *
+     * <p><b>Why this exists.</b> {@code CurrentUser} resolves a principal on every authenticated
+     * request, and {@link #upsert} answers it with a read-write transaction and two queries: one
+     * to find the row, one inside {@link #uniqueUsername} to check the handle is free. For an
+     * account whose claims have not changed since last request — which is essentially all of them,
+     * essentially always — both the second query and the writable transaction are pure overhead.
+     * This answers the same question with one {@code select} in a read-only transaction, which
+     * also makes it eligible for the read replica when one is configured.
+     *
+     * <p>Returns empty for anything that might need a write: no row yet, a renamed handle, a
+     * changed email or display name, a role change. The caller falls back to {@link #upsert},
+     * which is unchanged and still the only thing that writes. That fallback is stable rather than
+     * repeating: {@code upsert} settles the row to exactly the shape this method tests for, so an
+     * account takes the slow path once and the fast path afterwards.
+     *
+     * <p>The comparison is deliberately exact, not case-insensitive. A row holding {@code Alice}
+     * for a claim of {@code alice} is a rename that {@code upsert} should perform once, not a
+     * match to be tolerated forever.
+     */
+    @Transactional(readOnly = true)
+    public Optional<User> findUnchanged(ClaimView claims) {
+        return userRepository.findBySubject(claims.subject()).filter(u -> agreesWith(u, claims));
+    }
+
+    private static boolean agreesWith(User user, ClaimView claims) {
+        return Objects.equals(user.getUsername(), claims.username())
+                && Objects.equals(user.getEmail(), claims.email())
+                && Objects.equals(user.getDisplayName(), claims.displayName())
+                && user.isAdmin() == claims.admin();
+    }
+
+    @Transactional
+    public User provisionFromOidc(OidcUser oidc) {
+        var claims = claimsOf(oidc);
+        return upsert(claims.subject(), claims.username(), claims.email(),
+                claims.displayName(), claims.admin());
+    }
+
+    @Transactional
+    public User provisionFromJwt(Jwt jwt) {
+        var claims = claimsOf(jwt);
+        return upsert(claims.subject(), claims.username(), claims.email(),
+                claims.displayName(), claims.admin());
     }
 
     @SuppressWarnings("unchecked")
@@ -141,6 +197,26 @@ public User upsert(String subject, String username, String email, String display
      * username-keyed private notices / mentions / presence).
      */
     private String uniqueUsername(String desired, String subject) {
+        return uniqueUsername(desired, subject, null);
+    }
+
+    /**
+     * As above, but skipping the collision query when {@code held} — the row already owned by
+     * {@code subject} — is itself the holder of {@code desired}.
+     *
+     * <p>{@code uk_users_username_lower} (V2) makes at most one row match a handle
+     * case-insensitively, so if this subject's own row already holds it, the query can only come
+     * back with that same row and return {@code desired} unchanged. Skipping it is the second of
+     * the two per-request queries {@code CurrentUser} used to pay, and it is what keeps the
+     * fall-through path cheap for the accounts that never reach the fast path — a handle that had
+     * to be suffixed for a collision never equals its own claim, so those requests land here every
+     * time.
+     */
+    private String uniqueUsername(String desired, String subject, User held) {
+        if (held != null && held.getUsername() != null
+                && held.getUsername().equalsIgnoreCase(desired)) {
+            return desired;
+        }
         var holder = userRepository.findByUsernameIgnoreCase(desired);
         if (holder.isEmpty() || java.util.Objects.equals(holder.get().getSubject(), subject)) {
             return desired;
@@ -168,7 +244,7 @@ public User upsert(String subject, String username, String email, String display
         if (existing.isPresent()) {
             var u = existing.get();
             var oldUsername = u.getUsername();
-            var newUsername = uniqueUsername(username, subject);
+            var newUsername = uniqueUsername(username, subject, u);
             u.setUsername(newUsername);
             u.setEmail(email);
             u.setDisplayName(displayName);
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 7952678..2bc7c14 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -10,6 +10,7 @@ spring:
     url: ${ICHAT_DB_URL:jdbc:postgresql://localhost:5432/intellistream_chat}
     username: ${ICHAT_DB_USERNAME:ichat_role}
     password: ${ICHAT_DB_PASSWORD:ichat_role}
+    # Optional read replica: see ichat.datasource.replica below.
 
   jpa:
     hibernate:
@@ -81,6 +82,35 @@ ichat:
   assets:
     unbundled: ${ICHAT_ASSETS_UNBUNDLED:false}
 
+  # Optional second connection pool against a Postgres read replica (ReadReplicaDataSourceConfig).
+  # Off by default, and off means genuinely absent — no proxy, no second pool, nothing to go wrong.
+  #
+  # When enabled, a transaction annotated @Transactional(readOnly = true) is served from the
+  # replica; writes, migrations and raw JDBC access stay on the primary. That is the whole routing
+  # rule, and there is no per-query annotation. Note that a Spring Data repository call made
+  # outside a transaction counts as read-only — SimpleJpaRepository declares it — so it goes to
+  # the replica too.
+  #
+  # What it buys and what it costs: the primary stops serving the channel history, search result
+  # hydration and sidebar reads that make up most of the query volume, which is the relief worth
+  # having on a busy instance. The cost is that a replica lags, so a read-only transaction can see
+  # a slightly older world than the write that just returned. That is fine for reading history and
+  # wrong for a read that decides to delete something — the Lucene reconcile sweeps use a plain
+  # @Transactional for exactly that reason. Keep new code on the same rule.
+  #
+  # username/password are optional: blank inherits spring.datasource.*, which is what a streaming
+  # replica normally wants. Size the pool with ichat.datasource.replica.hikari.* (Boot's usual
+  # Hikari keys) — the read pool is generally the one that wants to be larger.
+  #
+  # All four keys can equally come from Vault as db.replica-enabled / db.replica-url /
+  # db.replica-username / db.replica-password.
+  datasource:
+    replica:
+      enabled: ${ICHAT_DB_REPLICA_ENABLED:false}
+      url: ${ICHAT_DB_REPLICA_URL:}
+      username: ${ICHAT_DB_REPLICA_USERNAME:}
+      password: ${ICHAT_DB_REPLICA_PASSWORD:}
+
   attachments:
     dir: ${ICHAT_ATTACHMENTS_DIR:./data/attachments}
     # Default total an account may store, in bytes (2 GiB). A per-account override lives in
diff --git a/src/test/java/ai/intellistream/chat/config/ReadReplicaDataSourceConfigTest.java b/src/test/java/ai/intellistream/chat/config/ReadReplicaDataSourceConfigTest.java
new file mode 100644
index 0000000..bdd3241
--- /dev/null
+++ b/src/test/java/ai/intellistream/chat/config/ReadReplicaDataSourceConfigTest.java
@@ -0,0 +1,145 @@
+/*
+ * Copyright 2026 IntelliStream AS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package ai.intellistream.chat.config;
+
+import com.zaxxer.hikari.HikariDataSource;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+import org.springframework.jdbc.datasource.LazyConnectionDataSourceProxy;
+
+import javax.sql.DataSource;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Wiring contract for the optional read replica. No database and no container: Hikari pools built
+ * through {@code DataSourceBuilder} are lazy, so a context can be assembled and inspected without
+ * anything connecting. {@code ReadReplicaRoutingIT} is the other half — it proves a read-only
+ * transaction actually lands on the second pool.
+ *
+ * <p>The case worth guarding hardest is the first one. "Optional" has to mean the feature is
+ * absent, not merely idle: a deployment that never asked for a replica should not gain a
+ * connection proxy, a second pool, or a new way to fail.
+ */
+class ReadReplicaDataSourceConfigTest {
+
+    private final ApplicationContextRunner runner = new ApplicationContextRunner()
+            .withConfiguration(AutoConfigurations.of(DataSourceAutoConfiguration.class))
+            .withUserConfiguration(ReadReplicaDataSourceConfig.class)
+            .withPropertyValues(
+                    "spring.datasource.url=jdbc:postgresql://primary.invalid:5432/chat",
+                    "spring.datasource.username=chat",
+                    "spring.datasource.password=chat");
+
+    @Test
+    void withoutTheFlagTheApplicationHasExactlyOnePoolAndNoProxy() {
+        runner.run(context -> {
+            assertThat(context).hasSingleBean(DataSource.class);
+            assertThat(context).doesNotHaveBean("readerDataSource");
+            assertThat(context).doesNotHaveBean("writerDataSource");
+            // Boot's own auto-configuration, untouched — not a proxy that happens to point at
+            // the primary twice.
+            assertThat(context.getBean(DataSource.class)).isInstanceOf(HikariDataSource.class);
+        });
+    }
+
+    @Test
+    void enablingItPutsTheProxyInFrontAndKeepsBothPoolsAddressable() {
+        runner.withPropertyValues(
+                        "ichat.datasource.replica.enabled=true",
+                        "ichat.datasource.replica.url=jdbc:postgresql://replica.invalid:5432/chat")
+                .run(context -> {
+                    assertThat(context.getBean(DataSource.class)).isInstanceOf(LazyConnectionDataSourceProxy.class);
+                    assertThat(context.getBean("writerDataSource", HikariDataSource.class).getJdbcUrl())
+                            .isEqualTo("jdbc:postgresql://primary.invalid:5432/chat");
+                    assertThat(context.getBean("readerDataSource", HikariDataSource.class).getJdbcUrl())
+                            .isEqualTo("jdbc:postgresql://replica.invalid:5432/chat");
+                });
+    }
+
+    @Test
+    void blankReplicaCredentialsInheritThePrimarysRatherThanConnectingAnonymously() {
+        runner.withPropertyValues(
+                        "ichat.datasource.replica.enabled=true",
+                        "ichat.datasource.replica.url=jdbc:postgresql://replica.invalid:5432/chat")
+                .run(context -> {
+                    var reader = context.getBean("readerDataSource", HikariDataSource.class);
+                    assertThat(reader.getUsername()).isEqualTo("chat");
+                    assertThat(reader.getPassword()).isEqualTo("chat");
+                });
+    }
+
+    @Test
+    void replicaCredentialsOverrideThePrimarysWhenTheReplicaHasItsOwnRole() {
+        runner.withPropertyValues(
+                        "ichat.datasource.replica.enabled=true",
+                        "ichat.datasource.replica.url=jdbc:postgresql://replica.invalid:5432/chat",
+                        "ichat.datasource.replica.username=chat_ro",
+                        "ichat.datasource.replica.password=ro-secret")
+                .run(context -> {
+                    var reader = context.getBean("readerDataSource", HikariDataSource.class);
+                    assertThat(reader.getUsername()).isEqualTo("chat_ro");
+                    assertThat(reader.getPassword()).isEqualTo("ro-secret");
+                });
+    }
+
+    @Test
+    void theReplicaPoolIsReadOnlyAtTheDriverRatherThanPerTransaction() {
+        runner.withPropertyValues(
+                        "ichat.datasource.replica.enabled=true",
+                        "ichat.datasource.replica.url=jdbc:postgresql://replica.invalid:5432/chat")
+                .run(context -> {
+                    // LazyConnectionDataSourceProxy suppresses the per-transaction setReadOnly call
+                    // once a dedicated read-only DataSource is configured, expecting the flag to be
+                    // a pool default. Without this the replica pool would hand out connections that
+                    // believe they are writable.
+                    assertThat(context.getBean("readerDataSource", HikariDataSource.class).isReadOnly()).isTrue();
+                    assertThat(context.getBean("writerDataSource", HikariDataSource.class).isReadOnly()).isFalse();
+                });
+    }
+
+    @Test
+    void theTwoPoolsAreSizedSeparately() {
+        runner.withPropertyValues(
+                        "spring.datasource.hikari.maximum-pool-size=8",
+                        "ichat.datasource.replica.enabled=true",
+                        "ichat.datasource.replica.url=jdbc:postgresql://replica.invalid:5432/chat",
+                        "ichat.datasource.replica.hikari.maximum-pool-size=40")
+                .run(context -> {
+                    // Read traffic and write traffic are different shapes; a shared number would
+                    // make the replica pointless at exactly the load that motivated adding one.
+                    assertThat(context.getBean("writerDataSource", HikariDataSource.class)
+                            .getMaximumPoolSize()).isEqualTo(8);
+                    assertThat(context.getBean("readerDataSource", HikariDataSource.class)
+                            .getMaximumPoolSize()).isEqualTo(40);
+                });
+    }
+
+    @Test
+    void enabledWithNoUrlFailsTheBootRatherThanQuietlyServingReadsFromThePrimary() {
+        runner.withPropertyValues("ichat.datasource.replica.enabled=true").run(context -> {
+            // The silent fallback is the bad outcome: it looks like it worked and shows up months
+            // later as a primary that never got any relief.
+            assertThat(context).hasFailed();
+            assertThat(context.getStartupFailure())
+                    .hasRootCauseMessage("ichat.datasource.replica.enabled=true but "
+                            + "ichat.datasource.replica.url is not set");
+        });
+    }
+}
diff --git a/src/test/java/ai/intellistream/chat/config/VaultEnvironmentPostProcessorTest.java b/src/test/java/ai/intellistream/chat/config/VaultEnvironmentPostProcessorTest.java
index 58f7559..83e4784 100644
--- a/src/test/java/ai/intellistream/chat/config/VaultEnvironmentPostProcessorTest.java
+++ b/src/test/java/ai/intellistream/chat/config/VaultEnvironmentPostProcessorTest.java
@@ -55,6 +55,40 @@ void translatesEveryKnownVaultKeyToItsSpringEquivalent() {
                         "https://kc.example.com/realms/ichat-realm");
     }
 
+    @Test
+    void theOptionalReadReplicaCanBeConfiguredEntirelyFromTheVaultRecord() {
+        var vaultRecord = Map.<String, Object>of(
+                "db.url", "jdbc:postgresql://primary.internal:5432/chat",
+                "db.replica-enabled", "true",
+                "db.replica-url", "jdbc:postgresql://replica.internal:5432/chat",
+                "db.replica-username", "chat_ro",
+                "db.replica-password", "ro-secret"
+        );
+
+        var mapped = VaultEnvironmentPostProcessor.mapToSpringPropertiesForTesting(vaultRecord);
+
+        // The enabled flag included: it is read by @ConditionalOnProperty, which evaluates long
+        // after an EnvironmentPostProcessor runs. Leaving it out would split one topology decision
+        // across Vault and the env file.
+        assertThat(mapped)
+                .containsEntry("spring.datasource.url", "jdbc:postgresql://primary.internal:5432/chat")
+                .containsEntry("ichat.datasource.replica.enabled", "true")
+                .containsEntry("ichat.datasource.replica.url", "jdbc:postgresql://replica.internal:5432/chat")
+                .containsEntry("ichat.datasource.replica.username", "chat_ro")
+                .containsEntry("ichat.datasource.replica.password", "ro-secret");
+    }
+
+    @Test
+    void aRecordWithoutReplicaKeysLeavesTheReplicaAloneEntirely() {
+        var record = Map.<String, Object>of("db.username", "rad", "db.password", "s3cret");
+
+        var mapped = VaultEnvironmentPostProcessor.mapToSpringPropertiesForTesting(record);
+
+        // Nothing under ichat.datasource.replica, not even enabled=false — an existing Vault
+        // record must keep meaning what it meant before the replica existed.
+        assertThat(mapped.keySet()).noneMatch(key -> key.startsWith("ichat.datasource.replica"));
+    }
+
     @Test
     void unknownVaultKeysAreDroppedRatherThanLeakingIntoTheEnvironment() {
         var record = new LinkedHashMap<String, Object>();
diff --git a/src/test/java/ai/intellistream/chat/integration/ReadReplicaRoutingIT.java b/src/test/java/ai/intellistream/chat/integration/ReadReplicaRoutingIT.java
new file mode 100644
index 0000000..65d6244
--- /dev/null
+++ b/src/test/java/ai/intellistream/chat/integration/ReadReplicaRoutingIT.java
@@ -0,0 +1,156 @@
+/*
+ * Copyright 2026 IntelliStream AS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package ai.intellistream.chat.integration;
+
+import ai.intellistream.chat.config.ReadReplicaDataSourceConfig;
+import jakarta.persistence.EntityManager;
+import jakarta.persistence.PersistenceContext;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Import;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.springframework.transaction.annotation.Transactional;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import javax.sql.DataSource;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Proves that {@code @Transactional(readOnly = true)} actually reaches the second pool, and that
+ * nothing else does.
+ *
+ * <p>The routing chain is entirely inside Spring and Hibernate — {@code HibernateJpaDialect}
+ * marks the transaction's connection read-only, {@code LazyConnectionDataSourceProxy} has not yet
+ * fetched a physical one, and when it does it picks the replica because of that mark. Every link
+ * is framework internals we don't own, which is exactly why this is asserted end to end rather
+ * than reasoned about: a Boot upgrade that changes when the connection is checked out would
+ * silently send every read back to the primary, and nothing else in the suite would notice.
+ *
+ * <p><b>One container, two pools.</b> A second Postgres would need the schema, Flyway and a
+ * replication link to be genuinely a replica, and would still not prove anything this doesn't.
+ * What the test needs is only to tell the two pools apart, so each is opened with its own
+ * {@code ApplicationName} and asks Postgres which one it is talking on. Where the connections
+ * come from is the question; whether the data differs is not.
+ */
+@Testcontainers
+@SpringBootTest(
+        classes = IntegrationTestApplication.class,
+        webEnvironment = SpringBootTest.WebEnvironment.NONE
+)
+@Import({ReadReplicaDataSourceConfig.class, ReadReplicaRoutingIT.ProbeConfig.class})
+class ReadReplicaRoutingIT {
+
+    private static final String WRITER = "ichat-writer-probe";
+    private static final String READER = "ichat-reader-probe";
+
+    @Container
+    @SuppressWarnings("resource")
+    static final PostgreSQLContainer<?> POSTGRES = new PostgreSQLContainer<>("postgres:18-alpine")
+            .withDatabaseName("chat")
+            .withUsername("chat")
+            .withPassword("chat");
+
+    @DynamicPropertySource
+    static void datasource(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", () -> tagged(WRITER));
+        registry.add("spring.datasource.username", POSTGRES::getUsername);
+        registry.add("spring.datasource.password", POSTGRES::getPassword);
+        // The "replica" is the same server reached over a differently-tagged pool — see the class
+        // javadoc for why that is the whole of what this test needs.
+        registry.add("ichat.datasource.replica.enabled", () -> "true");
+        registry.add("ichat.datasource.replica.url", () -> tagged(READER));
+        registry.add("spring.flyway.enabled", () -> "true");
+        registry.add("spring.jpa.hibernate.ddl-auto", () -> "validate");
+        registry.add("ichat.attachments.dir", () -> "build/test-attachments-replica-routing");
+        TestLuceneDirs.register(registry);
+    }
+
+    private static String tagged(String applicationName) {
+        var url = POSTGRES.getJdbcUrl();
+        return url + (url.contains("?") ? "&" : "?") + "ApplicationName=" + applicationName;
+    }
+
+    @Autowired Probe probe;
+    @Autowired DataSource dataSource;
+
+    @Test
+    void readOnlyTransactionsAreServedByTheReplicaPool() {
+        assertThat(probe.inReadOnlyTransaction()).isEqualTo(READER);
+    }
+
+    @Test
+    void writableTransactionsStayOnThePrimary() {
+        assertThat(probe.inWritableTransaction()).isEqualTo(WRITER);
+    }
+
+    @Test
+    void rawJdbcWithNoTransactionAtAllStaysOnThePrimary() throws Exception {
+        // Nothing marked the connection read-only, so the proxy has no reason to route it. Note
+        // this is the raw-DataSource path specifically: a Spring Data repository call outside a
+        // transaction is NOT this case — SimpleJpaRepository declares readOnly = true, so it
+        // starts a read-only transaction of its own and does reach the replica.
+        try (var connection = dataSource.getConnection();
+             var statement = connection.prepareStatement("SELECT current_setting('application_name')");
+             var rs = statement.executeQuery()) {
+            assertThat(rs.next()).isTrue();
+            assertThat(rs.getString(1)).isEqualTo(WRITER);
+        }
+    }
+
+    @TestConfiguration(proxyBeanMethods = false)
+    static class ProbeConfig {
+        @Bean
+        Probe readReplicaProbe() {
+            return new Probe();
+        }
+    }
+
+    /**
+     * Asks Postgres which pool the current transaction is talking on. A separate
+     * {@code @Transactional} bean rather than test methods, because the routing decision is made
+     * when the transaction begins — so the test class itself must not be transactional, and each
+     * probe call has to start its own.
+     */
+    static class Probe {
+
+        @PersistenceContext
+        private EntityManager entityManager;
+
+        @Transactional(readOnly = true)
+        public String inReadOnlyTransaction() {
+            return applicationName();
+        }
+
+        @Transactional
+        public String inWritableTransaction() {
+            return applicationName();
+        }
+
+        private String applicationName() {
+            return (String) entityManager
+                    .createNativeQuery("SELECT current_setting('application_name')")
+                    .getSingleResult();
+        }
+    }
+}
diff --git a/src/test/java/ai/intellistream/chat/integration/UserProvisioningIT.java b/src/test/java/ai/intellistream/chat/integration/UserProvisioningIT.java
new file mode 100644
index 0000000..da870af
--- /dev/null
+++ b/src/test/java/ai/intellistream/chat/integration/UserProvisioningIT.java
@@ -0,0 +1,135 @@
+/*
+ * Copyright 2026 IntelliStream AS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package ai.intellistream.chat.integration;
+
+import ai.intellistream.chat.service.UserService;
+import ai.intellistream.chat.service.UserService.ClaimView;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * The round-trip property the unit tests cannot reach: {@code upsert} must settle a row into
+ * exactly the shape {@link UserService#findUnchanged} tests for.
+ *
+ * <p>If it does not, nothing breaks and nothing is logged — {@code CurrentUser} simply takes the
+ * write path on every request of every session forever, which is the cost the fast path exists to
+ * remove, reappearing silently. A mocked repository cannot catch that: the mock returns whatever
+ * the test put in it, so the two halves agree by construction. Only a real round trip through JPA
+ * and Postgres shows whether the row that comes back out matches the claims that went in.
+ */
+@Testcontainers
+@SpringBootTest(
+        classes = IntegrationTestApplication.class,
+        webEnvironment = SpringBootTest.WebEnvironment.NONE
+)
+class UserProvisioningIT {
+
+    @Container
+    @SuppressWarnings("resource")
+    static final PostgreSQLContainer<?> POSTGRES = new PostgreSQLContainer<>("postgres:18-alpine")
+            .withDatabaseName("chat")
+            .withUsername("chat")
+            .withPassword("chat");
+
+    @DynamicPropertySource
+    static void datasource(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", POSTGRES::getJdbcUrl);
+        registry.add("spring.datasource.username", POSTGRES::getUsername);
+        registry.add("spring.datasource.password", POSTGRES::getPassword);
+        registry.add("spring.flyway.enabled", () -> "true");
+        registry.add("spring.jpa.hibernate.ddl-auto", () -> "validate");
+        registry.add("ichat.attachments.dir", () -> "build/test-attachments-user-provisioning");
+        TestLuceneDirs.register(registry);
+    }
+
+    @Autowired UserService users;
+
+    private static ClaimView claims(String subject, String username, String email,
+                                    String displayName, boolean admin) {
+        return new ClaimView(subject, username, email, displayName, admin);
+    }
+
+    private void provision(ClaimView c) {
+        users.upsert(c.subject(), c.username(), c.email(), c.displayName(), c.admin());
+    }
+
+    @Test
+    void aFreshlyProvisionedAccountIsImmediatelyOnTheFastPath() {
+        var c = claims("kc-fresh", "fresh", "fresh@example.com", "Fresh Person", false);
+
+        assertThat(users.findUnchanged(c)).as("no row yet").isEmpty();
+        provision(c);
+
+        // The very next request must not write again. This is the property: one slow path, then
+        // fast for the life of the account.
+        assertThat(users.findUnchanged(c)).isPresent();
+    }
+
+    @Test
+    void aClaimChangeTakesTheWritePathOnceAndThenSettles() {
+        var before = claims("kc-renamed", "before", "before@example.com", "Before", false);
+        provision(before);
+
+        var after = claims("kc-renamed", "after", "after@example.com", "After", true);
+        assertThat(users.findUnchanged(after)).as("claims moved, so the row must be rewritten").isEmpty();
+
+        provision(after);
+        assertThat(users.findUnchanged(after)).isPresent();
+        assertThat(users.findUnchanged(before)).as("the old claims must not match any more").isEmpty();
+    }
+
+    @Test
+    void anAccountWhoseHandleWasSuffixedForACollisionStillSettles() {
+        provision(claims("kc-holder", "taken", "holder@example.com", "Holder", false));
+
+        // A second principal wanting the same handle gets a suffix, so the stored username never
+        // equals the claim and findUnchanged can never match it. That is correct but it would mean
+        // this account pays the write path on every request forever — assert the suffix is at
+        // least stable, so it is one steady query rather than a rename fight on each pass.
+        var contender = claims("kc-contender", "taken", "contender@example.com", "Contender", false);
+        provision(contender);
+        var firstHandle = users.findUnchanged(
+                claims("kc-contender", "taken", "contender@example.com", "Contender", false));
+        assertThat(firstHandle).as("suffixed handle never equals the bare claim").isEmpty();
+
+        provision(contender);
+        provision(contender);
+        // Stable: repeated provisioning must not keep appending suffixes.
+        assertThat(users.findUnchanged(contender)).isEmpty();
+    }
+
+    @Test
+    void aCaseOnlyDifferenceIsCorrectedOnceAndThenMatches() {
+        provision(claims("kc-case", "Mixed", "case@example.com", "Case", false));
+
+        var lower = claims("kc-case", "mixed", "case@example.com", "Case", false);
+        assertThat(users.findUnchanged(lower)).as("stored handle is still 'Mixed'").isEmpty();
+
+        // upsert lowercases the column; the collision check is skipped because the account already
+        // holds the handle case-insensitively, which uk_users_username_lower guarantees is unique.
+        provision(lower);
+        assertThat(users.findUnchanged(lower)).isPresent();
+    }
+}
diff --git a/src/test/java/ai/intellistream/chat/service/UserProvisioningFastPathTest.java b/src/test/java/ai/intellistream/chat/service/UserProvisioningFastPathTest.java
new file mode 100644
index 0000000..1abf623
--- /dev/null
+++ b/src/test/java/ai/intellistream/chat/service/UserProvisioningFastPathTest.java
@@ -0,0 +1,182 @@
+/*
+ * Copyright 2026 IntelliStream AS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package ai.intellistream.chat.service;
+
+import ai.intellistream.chat.domain.User;
+import ai.intellistream.chat.repository.ConversationMessageRepository;
+import ai.intellistream.chat.repository.MessageRepository;
+import ai.intellistream.chat.repository.UserRepository;
+import ai.intellistream.chat.search.MessageIndexService;
+import ai.intellistream.chat.service.UserService.ClaimView;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.Optional;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * The read-only fast path {@code CurrentUser} takes on every authenticated request.
+ *
+ * <p>Two things are being protected. The first is cost: resolving an unchanged principal must be
+ * one {@code select} in a read-only transaction, not the two queries and the writable transaction
+ * {@link UserService#upsert} costs — that is the whole point, and a regression would be invisible
+ * because the behaviour stays correct. The second is that "unchanged" is judged on <em>every</em>
+ * field the write path would set. A fast path that ignores one of them serves a stale row forever;
+ * for {@code admin} that means a revoked role that never takes effect, which is why the
+ * per-field cases below are spelled out one at a time rather than as a single happy path.
+ */
+class UserProvisioningFastPathTest {
+
+    private static final String SUBJECT = "kc-subject-1";
+
+    private UserRepository users;
+    private UserService service;
+
+    /** The claims Keycloak sends for a settled account, and the row that already matches them. */
+    private static final ClaimView SETTLED =
+            new ClaimView(SUBJECT, "alice", "alice@example.com", "Alice Example", false);
+
+    private static User rowMatching(ClaimView claims) {
+        return new User(claims.subject(), claims.username(), claims.email(), claims.displayName());
+    }
+
+    @BeforeEach
+    void setUp() {
+        users = mock(UserRepository.class);
+        service = new UserService(users, mock(MessageRepository.class),
+                mock(ConversationMessageRepository.class), mock(MessageIndexService.class));
+    }
+
+    @Test
+    void anUnchangedAccountResolvesFromOneQueryAndNeverChecksTheHandle() {
+        var existing = rowMatching(SETTLED);
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.of(existing));
+
+        assertThat(service.findUnchanged(SETTLED)).containsSame(existing);
+
+        // The second query is the one this exists to remove. findByUsernameIgnoreCase is the
+        // collision check inside uniqueUsername, and an unchanged handle cannot collide with
+        // anything but its own row.
+        verify(users, never()).findByUsernameIgnoreCase(anyString());
+    }
+
+    @Test
+    void anAccountWithNoRowYetFallsThroughToProvisioning() {
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.empty());
+
+        assertThat(service.findUnchanged(SETTLED)).isEmpty();
+    }
+
+    @Test
+    void aRevokedAdminRoleFallsThroughRatherThanBeingServedFromTheExistingRow() {
+        var wasAdmin = rowMatching(SETTLED);
+        wasAdmin.setAdmin(true);
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.of(wasAdmin));
+
+        // SETTLED carries admin=false. Matching on anything less than every written field would
+        // leave this account an administrator until something else happened to rewrite the row.
+        assertThat(service.findUnchanged(SETTLED)).isEmpty();
+    }
+
+    @Test
+    void aChangedDisplayNameFallsThrough() {
+        var stale = rowMatching(SETTLED);
+        stale.setDisplayName("Alice Old");
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.of(stale));
+
+        assertThat(service.findUnchanged(SETTLED)).isEmpty();
+    }
+
+    @Test
+    void aChangedEmailFallsThrough() {
+        var stale = rowMatching(SETTLED);
+        stale.setEmail("alice@old.example.com");
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.of(stale));
+
+        assertThat(service.findUnchanged(SETTLED)).isEmpty();
+    }
+
+    @Test
+    void aCaseOnlyHandleDifferenceIsARenameToPerformOnceNotAMatchToTolerate() {
+        var mixedCase = rowMatching(SETTLED);
+        mixedCase.setUsername("Alice");
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.of(mixedCase));
+
+        // Falls through to upsert, which lowercases the column once; the request after that one
+        // matches exactly and takes the fast path. Tolerating the difference here would leave the
+        // stored handle disagreeing with the claim forever.
+        assertThat(service.findUnchanged(SETTLED)).isEmpty();
+    }
+
+    @Test
+    void theFallThroughSkipsTheCollisionCheckWhenTheHandleItselfIsUnchanged() {
+        var existing = rowMatching(SETTLED);
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.of(existing));
+
+        // Only the email moved, so this lands on the write path — but the handle is still the
+        // account's own, and uk_users_username_lower (V2) makes at most one row match it. The
+        // collision query could only come back with this same row.
+        var updated = service.upsert(SUBJECT, "alice", "alice@new.example.com", "Alice Example", false);
+
+        assertThat(updated.getEmail()).isEqualTo("alice@new.example.com");
+        assertThat(updated.getUsername()).isEqualTo("alice");
+        verify(users, never()).findByUsernameIgnoreCase(anyString());
+    }
+
+    @Test
+    void anActualRenameStillPaysTheCollisionCheck() {
+        var existing = rowMatching(SETTLED);
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.of(existing));
+        when(users.findByUsernameIgnoreCase("bob")).thenReturn(Optional.empty());
+
+        var renamed = service.upsert(SUBJECT, "bob", SETTLED.email(), SETTLED.displayName(), false);
+
+        // The skip must not swallow the case it exists for: a handle this account does not
+        // already hold can be held by somebody else, and that is what uniqueUsername resolves.
+        assertThat(renamed.getUsername()).isEqualTo("bob");
+        verify(users).findByUsernameIgnoreCase("bob");
+    }
+
+    @Test
+    void aRenameOntoAHandleSomebodyElseHoldsIsSuffixed() {
+        var existing = rowMatching(SETTLED);
+        var otherPerson = new User("kc-subject-2", "bob", "bob@example.com", "Bob");
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.of(existing));
+        when(users.findByUsernameIgnoreCase("bob")).thenReturn(Optional.of(otherPerson));
+
+        var renamed = service.upsert(SUBJECT, "bob", SETTLED.email(), SETTLED.displayName(), false);
+
+        assertThat(renamed.getUsername()).startsWith("bob-").isNotEqualTo("bob");
+    }
+
+    @Test
+    void aNullEmailOnBothSidesStillCountsAsUnchanged() {
+        var claims = new ClaimView(SUBJECT, "alice", null, "Alice Example", false);
+        var existing = rowMatching(claims);
+        when(users.findBySubject(SUBJECT)).thenReturn(Optional.of(existing));
+
+        // Keycloak realms without an email mapper send none. Comparing with == or equals() on a
+        // null field would push every one of those accounts onto the write path on every request.
+        assertThat(service.findUnchanged(claims)).containsSame(existing);
+    }
+}