diff --git a/examples/ideas-board/README.md b/examples/ideas-board/README.md new file mode 100644 index 0000000..34a5e33 --- /dev/null +++ b/examples/ideas-board/README.md @@ -0,0 +1,52 @@ +# Concurrent Ideas Board — pure-Java example + +The pure-Java twin of the Spring and .NET fundamentals demos. It shows the +library's hero feature: **automatic retry on serialization conflicts (SQLSTATE +40001)**. Many threads upvote the same idea; without retry votes are lost, with +`Crdb.tx(...)` every vote lands. + +Pinned to `cockroachdb-java-library` **0.1.2** (anonymous Maven Pages feed). + +## What it shows + +- `upvoteWithoutRetry(id)` — a plain SERIALIZABLE read-modify-write. Under + contention CockroachDB raises 40001 and the lost conflicts never recover. +- `upvote(id)` — the same work wrapped in `Crdb.tx(ds, conn -> …)`, which runs + SERIALIZABLE and replays the whole transaction on each 40001. All votes land. + +## Prerequisites + +- Java 25 (`sdk use java 25.0.2-graalce`) and Gradle 9.x. +- For `gradle run`: a reachable CockroachDB. Start one locally: + ``` + cockroach start-single-node --insecure --listen-addr=localhost:26257 + ``` + Override the URL with `JDBC_URL` (default + `jdbc:postgresql://localhost:26257/defaultdb?sslmode=disable&user=root`). +- For `gradle test`: Docker only — the test spins up CockroachDB via + Testcontainers (`CockroachHarness`). No local cluster needed. + +## Run + +```bash +# Prove it under contention (Testcontainers; Docker must be up): +gradle test + +# Watch lost votes vs. retried votes against a running cluster: +gradle run +``` + +`gradle run` prints both outcomes, e.g.: + +``` +WITHOUT retry (plain) successes=41 failures=19 votes=41/60 +WITH Crdb.tx retry successes=60 failures=0 votes=60/60 +``` + +## The proof + +`IdeaServiceConcurrencyTest` runs 3 threads × 20 iterations (60 upvotes) on one +idea via the testing module's `ConcurrencyRunner`, and asserts: + +- the retry path lands **exactly 60** votes with **zero** failures; +- the plain path does **not** reliably reach 60 (votes lost or failures raised). diff --git a/examples/ideas-board/build.gradle b/examples/ideas-board/build.gradle new file mode 100644 index 0000000..73aa76a --- /dev/null +++ b/examples/ideas-board/build.gradle @@ -0,0 +1,85 @@ +plugins { + id 'application' + id 'java' +} + +group = 'com.cockroachlabs.ideas' +version = '0.1.0' + +java { + toolchain { + languageVersion = JavaLanguageVersion.of(25) + } +} + +application { + mainClass = 'com.cockroachlabs.ideas.Main' +} + +// tag::repo-maven[] +repositories { + mavenCentral() + // Anonymous, no-token CockroachDB Java library Maven feed (GitHub Pages). + maven { + name = 'cockroachdb-java-library' + url = 'https://cockroachlabs.github.io/cockroachdb-java-library/maven/' + } +} +// end::repo-maven[] + +// tag::deps[] +dependencies { + // The pure-Java library core: Crdb.tx(...) retry entry point, @FollowerRead, + // Crdb.enhance(...). Pinned 0.1.2. + implementation 'com.cockroachlabs:cockroachdb-java-library-core:0.1.2' + + // Metrics module: CrdbMetrics facade + InMemoryMetricsRecorder, counting + // transactions and observe-bus retry events. + implementation 'com.cockroachlabs:cockroachdb-java-library-metrics:0.1.2' + + // CDC module: CdcEventHandler, CdcEventDecoder, ChangefeedHandlerRegistry for + // consuming CockroachDB changefeed webhook deliveries. + implementation 'com.cockroachlabs:cockroachdb-java-library-cdc:0.1.2' + + // AI module: VectorStore + VectorDocument + DistanceMetric over CockroachDB's + // native VECTOR type, for semantic / similarity search. + implementation 'com.cockroachlabs:cockroachdb-java-library-ai:0.1.2' + + // A JDBC driver + DataSource for plain read-modify-write DAO code. + implementation 'org.postgresql:postgresql:42.7.14' + + // Testing module: Testcontainers CockroachDB harness + concurrency runner. + // Declared as implementation (not test-only) so Main can drive the same + // ConcurrencyRunner the test uses; it stays available to the test too. + implementation 'com.cockroachlabs:cockroachdb-java-library-testing:0.1.2' + + // JUnit 6 (matches the library's parent junitVersion 6.1.3). + testImplementation 'org.junit.jupiter:junit-jupiter:6.1.3' + testRuntimeOnly 'org.junit.platform:junit-platform-launcher' + + // Mockito for the fast, no-DB unit test: mocks DataSource / Connection / + // IdeaRepository so IdeaService logic is verified without Docker. 5.24.0 + // bundles a ByteBuddy that supports Java 25, and its inline mock maker + // (default in Mockito 5) can mock the final IdeaRepository class. + testImplementation 'org.mockito:mockito-core:5.24.0' +} +// end::deps[] + +// Mockito's inline mock maker needs a Java agent. Self-attach works today but +// is deprecated on modern JDKs, so load mockito-core explicitly as an agent +// (the documented, future-proof setup) to keep the unit test clean on Java 25. +configurations { + mockitoAgent +} +dependencies { + mockitoAgent('org.mockito:mockito-core:5.24.0') { transitive = false } +} + +tasks.named('test') { + useJUnitPlatform() + jvmArgs "-javaagent:${configurations.mockitoAgent.asPath}" + testLogging { + events 'passed', 'skipped', 'failed' + showStandardStreams = true + } +} diff --git a/examples/ideas-board/settings.gradle b/examples/ideas-board/settings.gradle new file mode 100644 index 0000000..174cd9b --- /dev/null +++ b/examples/ideas-board/settings.gradle @@ -0,0 +1 @@ +rootProject.name = 'ideas-board' diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/Idea.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/Idea.java new file mode 100644 index 0000000..215e27d --- /dev/null +++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/Idea.java @@ -0,0 +1,13 @@ +package com.cockroachlabs.ideas; + +import java.util.UUID; + +// tag::entity[] +/** + * An idea on the board. {@code votes} is the hotly-contended column: many + * upvotes race to increment the same row, which is exactly where CockroachDB's + * SERIALIZABLE isolation raises 40001 and the library's retry earns its keep. + */ +public record Idea(UUID id, String text, int votes) { +} +// end::entity[] diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaChangefeedHandler.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaChangefeedHandler.java new file mode 100644 index 0000000..79643fb --- /dev/null +++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaChangefeedHandler.java @@ -0,0 +1,59 @@ +package com.cockroachlabs.ideas; + +import com.cockroachlabs.crdb.cdc.CdcEvent; +import com.cockroachlabs.crdb.cdc.CdcEventHandler; +import com.cockroachlabs.crdb.cdc.Operation; + +import java.util.List; +import java.util.Map; +import java.util.UUID; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.CopyOnWriteArrayList; + +// tag::cdc-handler[] +/** + * A {@link CdcEventHandler} for the {@code idea} table. CockroachDB's changefeed + * webhook delivers batches of decoded {@link CdcEvent}s; this handler turns each + * insert/update into an {@link Idea} and tracks deletes, so an app can mirror the + * ideas board into a cache, search index, or audit log as rows change. + * + *
Thread-safe: a changefeed webhook can deliver batches concurrently.
+ */
+public final class IdeaChangefeedHandler implements CdcEventHandler {
+
+ /** The table this handler is registered for. */
+ public static final String TABLE = "idea";
+
+ private final List The embedding here is a deterministic {@code float[3]} supplied by the caller
+ * (no model): that keeps the semantic-search integration test reproducible on a
+ * single node. In a real app the vector would come from an {@code EmbeddingProvider}
+ * (OpenAI, Ollama, a local model) of whatever width the column declares.
+ */
+public record IdeaDoc(String id, String text, float[] embedding) {
+
+ /** Embedding width; must match the {@code VECTOR(DIMENSIONS)} column. */
+ public static final int DIMENSIONS = 3;
+
+ /**
+ * Map to the AI module's {@link VectorDocument}, carrying the precomputed
+ * embedding (non-null, so the store never consults an embedding model).
+ */
+ public VectorDocument toVectorDocument() {
+ return new VectorDocument(id, text, embedding, Map.of());
+ }
+}
+// end::vector-entity[]
diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaReadService.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaReadService.java
new file mode 100644
index 0000000..44890b2
--- /dev/null
+++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaReadService.java
@@ -0,0 +1,78 @@
+package com.cockroachlabs.ideas;
+
+import com.cockroachlabs.crdb.Crdb;
+import com.cockroachlabs.crdb.annotations.FollowerRead;
+
+import javax.sql.DataSource;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+// tag::follower-read[]
+/**
+ * Leaderboard reads served from a follower via the library's {@code @FollowerRead}
+ * API. The annotated method runs through a {@link Crdb#enhance enhanced} proxy,
+ * which binds the follower-read staleness into the call context; the
+ * {@code Crdb.tx} transaction then emits
+ * {@code SET TRANSACTION AS OF SYSTEM TIME follower_read_timestamp()} as its first
+ * statement, so the leaderboard query runs against a slightly-stale snapshot the
+ * nearest replica can serve — no leaseholder round-trip.
+ *
+ * This is an interface (plus a factory and a package-private impl) so
+ * {@code Crdb.enhance} uses the JDK-dynamic-proxy strategy: the enhanced object is
+ * the interface type and delegates to the original instance, which is the exact
+ * idiom the library's own integration test uses for an annotated, DataSource-backed
+ * service.
+ */
+public interface IdeaReadService {
+
+ /**
+ * The top ideas by vote count, read from a follower at
+ * {@code follower_read_timestamp()} (about 4.8s stale). Because the read is
+ * historical, freshly-inserted rows become visible only once wall-clock time
+ * advances past the staleness window.
+ */
+ @FollowerRead
+ List The read-modify-write helpers ({@link #findById} / {@link #updateVotes})
+ * take an in-transaction {@link Connection} so the caller controls isolation and
+ * commit; the convenience helpers ({@link #currentVotes} / {@link #reset}) open
+ * their own short-lived connection.
+ */
+public final class IdeaRepository {
+
+ private final DataSource ds;
+
+ public IdeaRepository(DataSource ds) {
+ this.ds = ds;
+ }
+
+ /** Create the single-table schema (idempotent). */
+ public void createSchema() {
+ try (Connection c = ds.getConnection(); Statement s = c.createStatement()) {
+ s.execute("""
+ CREATE TABLE IF NOT EXISTS idea (
+ id UUID PRIMARY KEY,
+ text STRING NOT NULL,
+ votes INT NOT NULL DEFAULT 0
+ )""");
+ } catch (SQLException e) {
+ throw new RuntimeException("schema creation failed", e);
+ }
+ }
+
+ /** Insert one idea with zero votes and return it. */
+ public Idea seed(String text) {
+ Idea idea = new Idea(UUID.randomUUID(), text, 0);
+ try (Connection c = ds.getConnection();
+ PreparedStatement ps =
+ c.prepareStatement("INSERT INTO idea (id, text, votes) VALUES (?, ?, 0)")) {
+ ps.setObject(1, idea.id());
+ ps.setString(2, idea.text());
+ ps.executeUpdate();
+ } catch (SQLException e) {
+ throw new RuntimeException("seed failed", e);
+ }
+ return idea;
+ }
+
+ /** Read one idea on an in-transaction connection (the "read" of read-modify-write). */
+ public Idea findById(Connection c, UUID id) throws SQLException {
+ try (PreparedStatement ps =
+ c.prepareStatement("SELECT id, text, votes FROM idea WHERE id = ?")) {
+ ps.setObject(1, id);
+ try (ResultSet rs = ps.executeQuery()) {
+ if (!rs.next()) {
+ throw new SQLException("idea not found: " + id);
+ }
+ return new Idea((UUID) rs.getObject("id"), rs.getString("text"), rs.getInt("votes"));
+ }
+ }
+ }
+
+ /** Write the vote count on an in-transaction connection (the "write"). */
+ public void updateVotes(Connection c, UUID id, int votes) throws SQLException {
+ try (PreparedStatement ps =
+ c.prepareStatement("UPDATE idea SET votes = ? WHERE id = ?")) {
+ ps.setInt(1, votes);
+ ps.setObject(2, id);
+ ps.executeUpdate();
+ }
+ }
+
+ /** The current vote count, on its own connection (for assertions / printing). */
+ public int currentVotes(UUID id) {
+ try (Connection c = ds.getConnection();
+ PreparedStatement ps = c.prepareStatement("SELECT votes FROM idea WHERE id = ?")) {
+ ps.setObject(1, id);
+ try (ResultSet rs = ps.executeQuery()) {
+ return rs.next() ? rs.getInt(1) : -1;
+ }
+ } catch (SQLException e) {
+ throw new RuntimeException("currentVotes failed", e);
+ }
+ }
+
+ /** Reset the vote count to zero (between the two contention runs). */
+ public void reset(UUID id) {
+ try (Connection c = ds.getConnection();
+ PreparedStatement ps = c.prepareStatement("UPDATE idea SET votes = 0 WHERE id = ?")) {
+ ps.setObject(1, id);
+ ps.executeUpdate();
+ } catch (SQLException e) {
+ throw new RuntimeException("reset failed", e);
+ }
+ }
+}
+// end::repo[]
diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaService.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaService.java
new file mode 100644
index 0000000..f88487d
--- /dev/null
+++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaService.java
@@ -0,0 +1,63 @@
+package com.cockroachlabs.ideas;
+
+import com.cockroachlabs.crdb.Crdb;
+
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.sql.SQLException;
+import java.util.UUID;
+
+/**
+ * Upvotes an idea two ways so you can watch serialization conflicts bite — and
+ * then watch the library make them disappear.
+ */
+public final class IdeaService {
+
+ private final DataSource ds;
+ private final IdeaRepository repo;
+
+ public IdeaService(DataSource ds, IdeaRepository repo) {
+ this.ds = ds;
+ this.repo = repo;
+ }
+
+ // tag::plain[]
+ /**
+ * Upvote with NO retry. A plain SERIALIZABLE read-modify-write: under
+ * contention CockroachDB raises SQLSTATE 40001 and this method just lets it
+ * propagate, so concurrent upvotes are lost.
+ */
+ public void upvoteWithoutRetry(UUID id) {
+ try (Connection c = ds.getConnection()) {
+ c.setAutoCommit(false);
+ // SERIALIZABLE is required for 40001 to surface on a read-modify-write.
+ c.setTransactionIsolation(Connection.TRANSACTION_SERIALIZABLE);
+ try {
+ Idea idea = repo.findById(c, id);
+ repo.updateVotes(c, id, idea.votes() + 1);
+ c.commit();
+ } catch (SQLException e) {
+ c.rollback();
+ throw new RuntimeException(e);
+ }
+ } catch (SQLException e) {
+ throw new RuntimeException(e);
+ }
+ }
+ // end::plain[]
+
+ // tag::retry[]
+ /**
+ * Upvote WITH automatic retry. {@code Crdb.tx} runs the same
+ * read-modify-write in a SERIALIZABLE transaction and replays the whole unit
+ * on a 40001 conflict, so every upvote eventually lands.
+ */
+ public void upvote(UUID id) {
+ Crdb.tx(ds, c -> {
+ Idea idea = repo.findById(c, id);
+ repo.updateVotes(c, id, idea.votes() + 1);
+ return null;
+ });
+ }
+ // end::retry[]
+}
diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/Main.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/Main.java
new file mode 100644
index 0000000..d06be24
--- /dev/null
+++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/Main.java
@@ -0,0 +1,119 @@
+package com.cockroachlabs.ideas;
+
+import com.cockroachlabs.crdb.cdc.CdcEvent;
+import com.cockroachlabs.crdb.cdc.ChangefeedHandlerRegistry;
+import com.cockroachlabs.crdb.cdc.Operation;
+import com.cockroachlabs.crdb.metrics.CrdbMetrics;
+import com.cockroachlabs.crdb.metrics.InMemoryMetricsRecorder;
+import com.cockroachlabs.crdb.metrics.MetricsSnapshot;
+import com.cockroachlabs.crdb.testing.ConcurrencyResult;
+import com.cockroachlabs.crdb.testing.ConcurrencyRunner;
+import org.postgresql.ds.PGSimpleDataSource;
+
+import javax.sql.DataSource;
+import java.util.List;
+import java.util.Map;
+
+// tag::runner[]
+/**
+ * Seeds one idea, then hammers it with concurrent upvotes two ways using the
+ * library's {@link ConcurrencyRunner}:
+ *
+ * Point it at a running cluster via the {@code JDBC_URL} env var, or start a
+ * local one: {@code cockroach start-single-node --insecure}.
+ */
+public final class Main {
+
+ private static final int WORKERS = 3;
+ private static final int ITERATIONS = 20;
+ private static final int EXPECTED = WORKERS * ITERATIONS; // 60
+
+ public static void main(String[] args) {
+ DataSource ds = dataSource();
+ IdeaRepository repo = new IdeaRepository(ds);
+ IdeaService service = new IdeaService(ds, repo);
+
+ repo.createSchema();
+ Idea idea = repo.seed("Add dark mode to the ideas board");
+ System.out.println("Seeded idea " + idea.id() + " — expecting " + EXPECTED + " upvotes\n");
+
+ ConcurrencyRunner runner = new ConcurrencyRunner(WORKERS, ITERATIONS);
+
+ // 1) No retry: conflicts are lost.
+ repo.reset(idea.id());
+ ConcurrencyResult plain = runner.run((w, i) -> service.upvoteWithoutRetry(idea.id()));
+ report("WITHOUT retry (plain)", plain, repo.currentVotes(idea.id()));
+
+ // tag::metrics-config[]
+ // Enable metrics: attach a recorder to the core observe bus so every retry
+ // the library makes is counted. timeTransaction additionally records each
+ // transaction's duration and success/failure.
+ CrdbMetrics metrics = CrdbMetrics.inMemory().register();
+ // end::metrics-config[]
+
+ // 2) With Crdb.tx retry, timed through the metrics facade: every vote counted.
+ repo.reset(idea.id());
+ ConcurrencyResult retry = runner.run((w, i) ->
+ metrics.timeTransaction(() -> {
+ service.upvote(idea.id());
+ return null;
+ }));
+ report("WITH Crdb.tx retry", retry, repo.currentVotes(idea.id()));
+
+ MetricsSnapshot snap = ((InMemoryMetricsRecorder) metrics.recorder()).snapshot();
+ System.out.printf("%nmetrics: transactions=%d successes=%d retryAttempts=%d%n",
+ snap.transactionCount(), snap.transactionSuccessCount(), snap.retryAttempts());
+ metrics.unregister();
+
+ // 3) Follower-read leaderboard (reads at follower_read_timestamp(), ~4.8s
+ // stale, so freshly-written votes may not yet be visible).
+ IdeaReadService reads = IdeaReadService.create(ds);
+ System.out.println("\ntop ideas (follower read): " + reads.topIdeas(5));
+
+ demonstrateChangefeed();
+ }
+
+ // tag::cdc-register[]
+ /**
+ * Register the {@code idea} changefeed handler and feed it a synthetic webhook
+ * event (a real deployment points a {@code CREATE CHANGEFEED ... INTO
+ * 'webhook-...'} at a {@code ChangefeedWebhookHandler} mounted on an HttpServer).
+ */
+ private static void demonstrateChangefeed() {
+ IdeaChangefeedHandler cdc = new IdeaChangefeedHandler();
+ ChangefeedHandlerRegistry registry =
+ new ChangefeedHandlerRegistry().register(IdeaChangefeedHandler.TABLE, cdc);
+
+ CdcEvent synthetic = new CdcEvent(
+ Operation.INSERT, IdeaChangefeedHandler.TABLE,
+ List.of("00000000-0000-0000-0000-000000000001"),
+ Map.of("id", "00000000-0000-0000-0000-000000000001",
+ "text", "Idea seen via CDC", "votes", 1),
+ null, "1700000000.0");
+ registry.dispatch(List.of(synthetic));
+ System.out.println("cdc handled: " + cdc.handled());
+ }
+ // end::cdc-register[]
+
+ private static void report(String label, ConcurrencyResult r, int votes) {
+ System.out.printf(
+ "%-24s successes=%d failures=%d votes=%d/%d%n",
+ label, r.successes(), r.failures(), votes, EXPECTED);
+ }
+
+ private static DataSource dataSource() {
+ String url = System.getenv().getOrDefault(
+ "JDBC_URL",
+ "jdbc:postgresql://localhost:26257/defaultdb?sslmode=disable&user=root");
+ PGSimpleDataSource ds = new PGSimpleDataSource();
+ ds.setUrl(url);
+ return ds;
+ }
+}
+// end::runner[]
diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/RegionalIdea.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/RegionalIdea.java
new file mode 100644
index 0000000..1e2c2bd
--- /dev/null
+++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/RegionalIdea.java
@@ -0,0 +1,13 @@
+package com.cockroachlabs.ideas;
+
+import java.util.UUID;
+
+// tag::regional-entity[]
+/**
+ * An idea pinned to a CockroachDB region via REGIONAL BY ROW. {@code region} is the
+ * hidden {@code crdb_region} column the library writes from the call context, so the
+ * row's home (and its low-latency leaseholder) follows the writer's region.
+ */
+public record RegionalIdea(UUID id, String text, String region) {
+}
+// end::regional-entity[]
diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/RegionalIdeaService.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/RegionalIdeaService.java
new file mode 100644
index 0000000..2fa3da8
--- /dev/null
+++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/RegionalIdeaService.java
@@ -0,0 +1,112 @@
+package com.cockroachlabs.ideas;
+
+import com.cockroachlabs.crdb.Crdb;
+import com.cockroachlabs.crdb.annotations.Region;
+import com.cockroachlabs.crdb.context.CrdbContext;
+
+import javax.sql.DataSource;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.util.UUID;
+
+/**
+ * Region-scoped writes to a REGIONAL BY ROW {@code regional_idea} table, using the
+ * library's {@code @Region} API.
+ *
+ * Same enhanced-proxy idiom as {@link IdeaReadService}: {@code Crdb.enhance}
+ * returns a JDK dynamic proxy over an interface; a {@code @Region}-annotated method
+ * binds the region into {@link CrdbContext} for the duration of the call. The impl
+ * reads {@code CrdbContext.region()} and writes it into the hidden {@code crdb_region}
+ * column, so the row homes in that region without the caller hand-threading it.
+ *
+ * REGIONAL BY ROW requires a multi-region database (multiple {@code ADD REGION}s),
+ * which a single node does not have — so the proof ({@link RegionalIdeaIT}) is gated
+ * on a real multi-region cluster and skips by default.
+ */
+public interface RegionalIdeaService {
+
+ // tag::region-config[]
+ /**
+ * Enablement DDL. On a multi-region database (created with
+ * {@code ALTER DATABASE ... ADD REGION ...}) this makes the table REGIONAL BY ROW,
+ * adding the hidden {@code crdb_region} column the service writes.
+ */
+ String REGIONAL_BY_ROW_DDL = """
+ CREATE TABLE IF NOT EXISTS regional_idea (id UUID PRIMARY KEY, text STRING NOT NULL);
+ ALTER TABLE regional_idea SET LOCALITY REGIONAL BY ROW;
+ """;
+ // end::region-config[]
+
+ // tag::inregion-usage[]
+ /** Store an idea homed in {@code us-east1} (bound into the context by {@code @Region}). */
+ @Region("us-east1")
+ void addInUsEast(UUID id, String text);
+
+ /** Store an idea homed in {@code us-west1}. */
+ @Region("us-west1")
+ void addInUsWest(UUID id, String text);
+ // end::inregion-usage[]
+
+ /** The {@code crdb_region} a row actually landed in, if present. */
+ String regionOf(UUID id);
+
+ /** Build a region-aware view over {@code ds}. */
+ static RegionalIdeaService create(DataSource ds) {
+ return Crdb.enhance((RegionalIdeaService) new Impl(ds));
+ }
+
+ /** JDBC implementation; the {@code @Region} on the concrete method is what the proxy reads. */
+ final class Impl implements RegionalIdeaService {
+
+ private final DataSource ds;
+
+ Impl(DataSource ds) {
+ this.ds = ds;
+ }
+
+ @Override
+ @Region("us-east1")
+ public void addInUsEast(UUID id, String text) {
+ insertInBoundRegion(id, text);
+ }
+
+ @Override
+ @Region("us-west1")
+ public void addInUsWest(UUID id, String text) {
+ insertInBoundRegion(id, text);
+ }
+
+ /**
+ * Write the row into the region the proxy bound into {@link CrdbContext}.
+ * {@code crdb_region} is set explicitly so the REGIONAL BY ROW row homes
+ * where the {@code @Region} annotation says, not where the gateway happens to be.
+ */
+ private void insertInBoundRegion(UUID id, String text) {
+ String region = CrdbContext.region().orElseThrow(
+ () -> new IllegalStateException("no region bound; call via the enhanced proxy"));
+ Crdb.tx(ds, c -> {
+ try (PreparedStatement ps = c.prepareStatement(
+ "INSERT INTO regional_idea (id, text, crdb_region) VALUES (?, ?, ?)")) {
+ ps.setObject(1, id);
+ ps.setString(2, text);
+ ps.setString(3, region);
+ ps.executeUpdate();
+ }
+ return null;
+ });
+ }
+
+ @Override
+ public String regionOf(UUID id) {
+ return Crdb.tx(ds, c -> {
+ try (PreparedStatement ps = c.prepareStatement(
+ "SELECT crdb_region::STRING FROM regional_idea WHERE id = ?")) {
+ ps.setObject(1, id);
+ try (ResultSet rs = ps.executeQuery()) {
+ return rs.next() ? rs.getString(1) : null;
+ }
+ }
+ });
+ }
+ }
+}
diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/SemanticIdeaService.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/SemanticIdeaService.java
new file mode 100644
index 0000000..6a116c0
--- /dev/null
+++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/SemanticIdeaService.java
@@ -0,0 +1,62 @@
+package com.cockroachlabs.ideas;
+
+import com.cockroachlabs.crdb.ai.DistanceMetric;
+import com.cockroachlabs.crdb.ai.HashingEmbeddingProvider;
+import com.cockroachlabs.crdb.ai.VectorSearchResult;
+import com.cockroachlabs.crdb.ai.VectorStore;
+import com.cockroachlabs.crdb.ai.VectorStoreConfig;
+
+import javax.sql.DataSource;
+import java.util.Arrays;
+import java.util.List;
+
+// tag::vector-search[]
+/**
+ * Semantic search over ideas, backed by the AI module's {@link VectorStore} on a
+ * CockroachDB native {@code VECTOR} column.
+ *
+ * {@code store(...)} upserts {@link IdeaDoc}s (each carrying a precomputed
+ * embedding) and {@code findSimilar(queryVector, k)} returns the nearest docs,
+ * ordered closest-first, via the configured {@link DistanceMetric}'s SQL distance
+ * operator ({@code <=>} for cosine).
+ *
+ * Uses brute-force KNN (no {@code CREATE VECTOR INDEX}), which needs only the
+ * {@code VECTOR} type and distance operator — available on CockroachDB v25.2+ with
+ * no index/feature flag — so the search is deterministic on a single test node.
+ */
+public final class SemanticIdeaService {
+
+ /** The backing table; shared with the integration test for assertions. */
+ public static final String TABLE = "idea_doc";
+
+ private final VectorStore store;
+
+ public SemanticIdeaService(DataSource ds) {
+ VectorStoreConfig config = VectorStoreConfig.builder()
+ .tableName(TABLE)
+ .dimensions(IdeaDoc.DIMENSIONS)
+ .distanceMetric(DistanceMetric.COSINE)
+ .createVectorIndex(false) // brute-force KNN; no C-SPANN index needed
+ .build();
+ // Embeddings are precomputed per IdeaDoc, so the provider is only here to
+ // satisfy the store's non-null embedder contract and dimension check; it is
+ // never consulted for stored or queried vectors.
+ this.store = new VectorStore(ds, new HashingEmbeddingProvider(IdeaDoc.DIMENSIONS), config);
+ }
+
+ /** Create the backing {@code VECTOR} table if absent. Safe to call repeatedly. */
+ public void initialize() {
+ store.initializeSchema();
+ }
+
+ /** Upsert ideas with their precomputed embeddings. */
+ public void store(IdeaDoc... docs) {
+ store.add(Arrays.stream(docs).map(IdeaDoc::toVectorDocument).toList());
+ }
+
+ /** The {@code k} ideas nearest to {@code queryVector}, closest-first. */
+ public List Because a follower read is historical (~4.8s stale), freshly-seeded rows are
+ * invisible until wall-clock time passes the staleness window, so the test polls
+ * until the snapshot catches up rather than asserting immediately.
+ *
+ * Requires Docker at test runtime.
+ */
+class IdeaFollowerReadIT {
+
+ // tag::follower-read-it[]
+ @Test
+ void topIdeasReturnsVotesOrderedFromAFollowerSnapshot() {
+ try (CockroachHarness harness = CockroachHarness.container().start()) {
+ // The harness URL has no user; the Testcontainers node authenticates as root.
+ PGSimpleDataSource ds = new PGSimpleDataSource();
+ ds.setUrl(harness.jdbcUrl());
+ ds.setUser("root");
+
+ IdeaRepository repo = new IdeaRepository(ds);
+ repo.createSchema();
+ insert(ds, "Dark mode", 5);
+ insert(ds, "Full-text search", 12);
+ insert(ds, "CSV export", 3);
+
+ IdeaReadService reads = IdeaReadService.create(ds);
+
+ // Poll: the seeded rows appear once follower_read_timestamp() advances
+ // past their insert time.
+ List Requires Docker at test runtime.
+ */
+class IdeaMetricsIT {
+
+ private static final int WORKERS = 4;
+ private static final int ITERATIONS = 25;
+ private static final int EXPECTED = WORKERS * ITERATIONS; // 100
+
+ @Test
+ void transactionAndRetryCountersMoveUnderContention() {
+ try (CockroachHarness harness = CockroachHarness.container().start()) {
+ PGSimpleDataSource ds = new PGSimpleDataSource();
+ ds.setUrl(harness.jdbcUrl());
+ ds.setUser("root");
+
+ IdeaRepository repo = new IdeaRepository(ds);
+ IdeaService service = new IdeaService(ds, repo);
+ repo.createSchema();
+ Idea idea = repo.seed("Instrument the ideas board");
+
+ // tag::metrics-config[]
+ // Enable metrics: attach a recorder to the core observe bus so every
+ // retry attempt the library makes is counted automatically.
+ CrdbMetrics metrics = CrdbMetrics.inMemory().register();
+ // end::metrics-config[]
+ try {
+ // tag::metrics-it[]
+ // Each upvote is timed as one transaction; the inner Crdb.tx retries
+ // on 40001 are counted independently via the observe bus.
+ ConcurrencyRunner runner = new ConcurrencyRunner(WORKERS, ITERATIONS);
+ ConcurrencyResult result = runner.run((w, i) ->
+ metrics.timeTransaction(() -> {
+ service.upvote(idea.id());
+ return null;
+ }));
+
+ assertEquals(0, result.failures(), "retry must absorb every conflict");
+ assertEquals(EXPECTED, repo.currentVotes(idea.id()), "every upvote must land");
+
+ MetricsSnapshot snap = ((InMemoryMetricsRecorder) metrics.recorder()).snapshot();
+ assertEquals(EXPECTED, snap.transactionCount(),
+ "one recorded transaction per timed upvote");
+ assertEquals(EXPECTED, snap.transactionSuccessCount());
+ assertTrue(snap.retryAttempts() > 0,
+ "contention on one row must force at least one 40001 retry, but retryAttempts="
+ + snap.retryAttempts());
+ // end::metrics-it[]
+ } finally {
+ metrics.unregister();
+ }
+ }
+ }
+}
diff --git a/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaServiceConcurrencyTest.java b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaServiceConcurrencyTest.java
new file mode 100644
index 0000000..86caf58
--- /dev/null
+++ b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaServiceConcurrencyTest.java
@@ -0,0 +1,62 @@
+package com.cockroachlabs.ideas;
+
+import com.cockroachlabs.crdb.testing.CockroachHarness;
+import com.cockroachlabs.crdb.testing.ConcurrencyResult;
+import com.cockroachlabs.crdb.testing.ConcurrencyRunner;
+import org.junit.jupiter.api.Test;
+import org.postgresql.ds.PGSimpleDataSource;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Proves the hero feature under real contention: a Testcontainers CockroachDB
+ * node, three worker threads, twenty upvotes each (60 total) racing on one row.
+ *
+ * Requires Docker at test runtime.
+ */
+class IdeaServiceConcurrencyTest {
+
+ private static final int WORKERS = 3;
+ private static final int ITERATIONS = 20;
+ private static final int EXPECTED = WORKERS * ITERATIONS; // 60
+
+ @Test
+ void retryLandsEveryVoteWhilePlainLosesSome() {
+ try (CockroachHarness harness = CockroachHarness.container().start()) {
+ // CockroachHarness.dataSource() sets only the URL; the Testcontainers
+ // node authenticates as user "root", so build the DataSource from the
+ // harness URL with that user set explicitly.
+ PGSimpleDataSource ds = new PGSimpleDataSource();
+ ds.setUrl(harness.jdbcUrl());
+ ds.setUser("root");
+
+ IdeaRepository repo = new IdeaRepository(ds);
+ IdeaService service = new IdeaService(ds, repo);
+
+ repo.createSchema();
+ Idea idea = repo.seed("Concurrent upvotes");
+ ConcurrencyRunner runner = new ConcurrencyRunner(WORKERS, ITERATIONS);
+
+ // tag::concurrency-test[]
+ // Plain path: SERIALIZABLE conflicts raise 40001 and are lost, so the
+ // final count does NOT reliably reach 60.
+ repo.reset(idea.id());
+ ConcurrencyResult plain = runner.run((w, i) -> service.upvoteWithoutRetry(idea.id()));
+ int plainVotes = repo.currentVotes(idea.id());
+ assertTrue(plainVotes < EXPECTED || plain.failures() > 0,
+ "plain upvote should lose votes under contention, but got votes="
+ + plainVotes + " with failures=" + plain.failures());
+
+ // Retry path: Crdb.tx replays the transaction on every 40001, so all
+ // 60 votes land with zero failures.
+ repo.reset(idea.id());
+ ConcurrencyResult retry = runner.run((w, i) -> service.upvote(idea.id()));
+ assertEquals(0, retry.failures(),
+ "Crdb.tx retry must absorb all serialization conflicts");
+ assertEquals(EXPECTED, repo.currentVotes(idea.id()),
+ "every upvote must be counted with retry");
+ // end::concurrency-test[]
+ }
+ }
+}
diff --git a/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaServiceUnitTest.java b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaServiceUnitTest.java
new file mode 100644
index 0000000..8b23bc9
--- /dev/null
+++ b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaServiceUnitTest.java
@@ -0,0 +1,59 @@
+package com.cockroachlabs.ideas;
+
+import org.junit.jupiter.api.Test;
+
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * Fast, no-Docker unit test for {@link IdeaService#upvoteWithoutRetry}.
+ *
+ * This mocks the JDBC seam ({@link DataSource} / {@link Connection}) and the
+ * {@link IdeaRepository}, so it asserts only the service's call/logic:
+ * that it reads via {@code findById}, writes {@code votes + 1} via
+ * {@code updateVotes}, selects SERIALIZABLE isolation, and commits — with no
+ * real database.
+ *
+ * The real SQLSTATE 40001 contention behavior and the {@code Crdb.tx} retry
+ * (the hero feature) are covered by the Testcontainers integration test
+ * {@link IdeaServiceConcurrencyTest}; nothing here needs a container.
+ */
+class IdeaServiceUnitTest {
+
+ // tag::unit-test[]
+ @Test
+ void upvoteWithoutRetryReadsIncrementsAndCommits() throws Exception {
+ UUID id = UUID.randomUUID();
+
+ DataSource ds = mock(DataSource.class);
+ Connection conn = mock(Connection.class);
+ IdeaRepository repo = mock(IdeaRepository.class);
+
+ when(ds.getConnection()).thenReturn(conn);
+ when(repo.findById(conn, id)).thenReturn(new Idea(id, "Ship it", 41));
+
+ new IdeaService(ds, repo).upvoteWithoutRetry(id);
+
+ verify(repo).findById(conn, id);
+ verify(repo).updateVotes(conn, id, 42); // read 41, write 41 + 1
+ verify(conn).setTransactionIsolation(Connection.TRANSACTION_SERIALIZABLE);
+ verify(conn).commit();
+ }
+ // end::unit-test[]
+
+ @Test
+ void ideaRecordExposesItsFields() {
+ UUID id = UUID.randomUUID();
+ Idea idea = new Idea(id, "Add dark mode", 7);
+
+ assertEquals(id, idea.id());
+ assertEquals("Add dark mode", idea.text());
+ assertEquals(7, idea.votes());
+ }
+}
diff --git a/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/RegionalIdeaIT.java b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/RegionalIdeaIT.java
new file mode 100644
index 0000000..23fb467
--- /dev/null
+++ b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/RegionalIdeaIT.java
@@ -0,0 +1,56 @@
+package com.cockroachlabs.ideas;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;
+import org.postgresql.ds.PGSimpleDataSource;
+
+import java.sql.Connection;
+import java.sql.Statement;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * Proves region-scoped writes against a real multi-region CockroachDB cluster:
+ * the {@code @Region}-annotated {@link RegionalIdeaService} methods land each row in the
+ * right {@code crdb_region} of a REGIONAL BY ROW table.
+ *
+ * Gated on purpose. REGIONAL BY ROW needs a database with multiple regions,
+ * which a single Testcontainers node does not have. This test therefore SKIPS unless
+ * {@code CRDB_MULTIREGION=true}; when enabled it reads an external cluster from
+ * {@code CRDB_URL} (expected to already have {@code us-east1} and {@code us-west1}
+ * added as regions). It never fails by default — it is skipped.
+ */
+@EnabledIfEnvironmentVariable(named = "CRDB_MULTIREGION", matches = "true")
+class RegionalIdeaIT {
+
+ // tag::region-test[]
+ @Test
+ void writesHomeRowsInTheAnnotatedRegion() throws Exception {
+ String url = System.getenv("CRDB_URL");
+ PGSimpleDataSource ds = new PGSimpleDataSource();
+ ds.setUrl(url);
+
+ // The external multi-region database must already have the regions added:
+ // ALTER DATABASE Vector enablement: the {@link CockroachHarness} has no vector-enable
+ * helper, and its default image ({@code cockroachdb/cockroach:v24.1.5}) predates the
+ * native {@code VECTOR} type. Vector is therefore enabled by running against a
+ * v25.2+ image via {@link CockroachHarness#container(String)} — overridable with the
+ * {@code CRDB_VECTOR_IMAGE} env var. Brute-force KNN (no {@code CREATE VECTOR INDEX})
+ * needs only the type and the {@code <=>} operator, so no feature flag is required.
+ * If the chosen image genuinely lacks the {@code VECTOR} type, the test SKIPS (via
+ * {@link Assumptions}) rather than faking a pass.
+ *
+ * Requires Docker at test runtime.
+ */
+class SemanticSearchIT {
+
+ private static final String IMAGE =
+ System.getenv().getOrDefault("CRDB_VECTOR_IMAGE", "cockroachdb/cockroach:latest-v25.2");
+
+ // tag::vector-it[]
+ @Test
+ void findSimilarReturnsNearestIdeaFirst() {
+ try (CockroachHarness harness = CockroachHarness.container(IMAGE).start()) {
+ PGSimpleDataSource ds = new PGSimpleDataSource();
+ ds.setUrl(harness.jdbcUrl());
+ ds.setUser("root");
+
+ SemanticIdeaService semantic = new SemanticIdeaService(ds);
+ try {
+ semantic.initialize();
+ } catch (RuntimeException e) {
+ // Honest gate: if this image has no native VECTOR type, skip (don't fake it).
+ Assumptions.assumeTrue(!mentionsVectorUnsupported(e),
+ "VECTOR type unsupported on image " + IMAGE + ": " + e.getMessage());
+ throw e;
+ }
+
+ // Four deterministic 3-dim vectors pointing in distinct directions.
+ semantic.store(
+ new IdeaDoc("dark-mode", "Dark mode toggle", new float[] {1.0f, 0.0f, 0.0f}),
+ new IdeaDoc("mobile", "Mobile dark theme", new float[] {0.8f, 0.2f, 0.0f}),
+ new IdeaDoc("search", "Full-text search", new float[] {0.0f, 1.0f, 0.0f}),
+ new IdeaDoc("export", "CSV export", new float[] {0.0f, 0.0f, 1.0f}));
+
+ // Query near "dark-mode"; second-nearest is "mobile", then "search", then "export".
+ List
+ *
+ *
+ * > read,
+ int expected, Duration timeout) {
+ Instant deadline = Instant.now().plus(timeout);
+ List