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 handled = new CopyOnWriteArrayList<>(); + private final AtomicInteger deletes = new AtomicInteger(); + + @Override + public void handle(List events) { + for (CdcEvent event : events) { + if (event.operation() == Operation.DELETE) { + deletes.incrementAndGet(); // after-image is null on a delete + continue; + } + handled.add(toIdea(event.after())); + } + } + + /** Project a changefeed {@code after} image onto an {@link Idea}. */ + static Idea toIdea(Map after) { + return new Idea( + UUID.fromString(String.valueOf(after.get("id"))), + String.valueOf(after.get("text")), + ((Number) after.get("votes")).intValue()); // JSON numbers decode as Number + } + + /** Ideas seen so far from insert/update events, in arrival order. */ + public List handled() { + return List.copyOf(handled); + } + + /** Count of delete events seen. */ + public int deletes() { + return deletes.get(); + } +} +// end::cdc-handler[] diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaDoc.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaDoc.java new file mode 100644 index 0000000..bf9c891 --- /dev/null +++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaDoc.java @@ -0,0 +1,30 @@ +package com.cockroachlabs.ideas; + +import com.cockroachlabs.crdb.ai.VectorDocument; + +import java.util.Map; + +// tag::vector-entity[] +/** + * An idea with a small fixed-dimension embedding, stored in a CockroachDB native + * {@code VECTOR} column so similar ideas can be found by vector distance. + * + *

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 topIdeas(int limit); + + /** Build a follower-read-enabled view over {@code ds}. */ + static IdeaReadService create(DataSource ds) { + return Crdb.enhance((IdeaReadService) new Impl(ds)); + } + + /** JDBC implementation; the {@code @FollowerRead} on the concrete method is what the proxy reads. */ + final class Impl implements IdeaReadService { + + private final DataSource ds; + + Impl(DataSource ds) { + this.ds = ds; + } + + @Override + @FollowerRead + public List topIdeas(int limit) { + // Crdb.tx picks up the follower-read staleness bound by the proxy and + // applies SET TRANSACTION AS OF SYSTEM TIME before this query runs. + return Crdb.tx(ds, c -> { + try (PreparedStatement ps = c.prepareStatement( + "SELECT id, text, votes FROM idea ORDER BY votes DESC, text ASC LIMIT ?")) { + ps.setInt(1, limit); + try (ResultSet rs = ps.executeQuery()) { + List out = new ArrayList<>(); + while (rs.next()) { + out.add(new Idea( + (UUID) rs.getObject("id"), + rs.getString("text"), + rs.getInt("votes"))); + } + return out; + } + } + }); + } + } +} +// end::follower-read[] diff --git a/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaRepository.java b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaRepository.java new file mode 100644 index 0000000..d723987 --- /dev/null +++ b/examples/ideas-board/src/main/java/com/cockroachlabs/ideas/IdeaRepository.java @@ -0,0 +1,107 @@ +package com.cockroachlabs.ideas; + +import javax.sql.DataSource; +import java.sql.Connection; +import java.sql.PreparedStatement; +import java.sql.ResultSet; +import java.sql.SQLException; +import java.sql.Statement; +import java.util.UUID; + +// tag::repo[] +/** + * Plain-JDBC data access for {@link Idea}. No Spring, no JPA — just a + * {@link DataSource} and {@link PreparedStatement}s, so this works in any JDBC + * app. + * + *

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}: + * + *

    + *
  1. {@code upvoteWithoutRetry} — plain SERIALIZABLE; conflicts surface as + * 40001 failures and votes are lost.
  2. + *
  3. {@code upvote} — {@code Crdb.tx} auto-retries; every vote lands.
  4. + *
+ * + *

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 findSimilar(float[] queryVector, int k) { + return store.similaritySearch(queryVector, k, null); + } +} +// end::vector-search[] diff --git a/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaCdcUnitTest.java b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaCdcUnitTest.java new file mode 100644 index 0000000..804b5c4 --- /dev/null +++ b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaCdcUnitTest.java @@ -0,0 +1,77 @@ +package com.cockroachlabs.ideas; + +import com.cockroachlabs.crdb.cdc.CdcEvent; +import com.cockroachlabs.crdb.cdc.CdcEventDecoder; +import com.cockroachlabs.crdb.cdc.ChangefeedHandlerRegistry; +import com.cockroachlabs.crdb.cdc.Operation; +import org.junit.jupiter.api.Test; + +import java.util.List; +import java.util.Map; +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Fast, no-Docker unit test for {@link IdeaChangefeedHandler}. CDC processing is + * pure logic — classify the event, project the {@code after} image onto an + * {@link Idea} — so it needs no live changefeed. The library ships no CDC + * simulator, so we exercise the handler two ways: directly with a constructed + * {@link CdcEvent}, and through the library's real decode-and-dispatch path by + * feeding a synthetic changefeed webhook envelope. + */ +class IdeaCdcUnitTest { + + // tag::cdc-unit-test[] + @Test + void handlerProjectsInsertEventOntoIdeaAndTracksDeletes() { + IdeaChangefeedHandler handler = new IdeaChangefeedHandler(); + UUID id = UUID.randomUUID(); + + // A synthetic insert: after-image present, no before-image. + CdcEvent insert = new CdcEvent( + Operation.INSERT, IdeaChangefeedHandler.TABLE, List.of(id.toString()), + Map.of("id", id.toString(), "text", "Add dark mode", "votes", 7), + null, "1700000000.0000000000"); + // A synthetic delete: after-image is null. + CdcEvent delete = new CdcEvent( + Operation.DELETE, IdeaChangefeedHandler.TABLE, List.of(id.toString()), + null, null, "1700000001.0000000000"); + + handler.handle(List.of(insert, delete)); + + assertEquals(1, handler.handled().size(), "insert must be projected onto an Idea"); + Idea seen = handler.handled().get(0); + assertEquals(id, seen.id()); + assertEquals("Add dark mode", seen.text()); + assertEquals(7, seen.votes()); + assertEquals(1, handler.deletes(), "delete must be counted, not projected"); + } + + @Test + void handlerProcessesAWebhookEnvelopeThroughDecodeAndDispatch() { + IdeaChangefeedHandler handler = new IdeaChangefeedHandler(); + ChangefeedHandlerRegistry registry = + new ChangefeedHandlerRegistry().register(IdeaChangefeedHandler.TABLE, handler); + + UUID id = UUID.randomUUID(); + // The exact 'wrapped' JSON envelope CockroachDB's webhook sink emits. + String envelope = """ + {"payload":[ + {"after":{"id":"%s","text":"Full-text search","votes":12},"key":["%s"],"topic":"idea","updated":"1700000002.0"} + ],"length":1}""".formatted(id, id); + + List events = new CdcEventDecoder().decodeEvents(envelope); + int tablesDispatched = registry.dispatch(events); + + assertEquals(1, tablesDispatched, "the idea table's handler must be invoked"); + assertEquals(1, handler.handled().size()); + Idea seen = handler.handled().get(0); + assertEquals(id, seen.id()); + assertEquals("Full-text search", seen.text()); + assertEquals(12, seen.votes()); + assertTrue(handler.deletes() == 0); + } + // end::cdc-unit-test[] +} diff --git a/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaFollowerReadIT.java b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaFollowerReadIT.java new file mode 100644 index 0000000..2cce0d5 --- /dev/null +++ b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaFollowerReadIT.java @@ -0,0 +1,116 @@ +package com.cockroachlabs.ideas; + +import com.cockroachlabs.crdb.testing.CockroachHarness; +import org.junit.jupiter.api.Test; +import org.postgresql.ds.PGSimpleDataSource; + +import javax.sql.DataSource; +import java.sql.Connection; +import java.sql.PreparedStatement; +import java.time.Duration; +import java.time.Instant; +import java.util.List; +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assertions.fail; + +/** + * Proves the follower-read leaderboard end to end against a real CockroachDB node: + * the {@code @FollowerRead}-annotated {@link IdeaReadService} reads at + * {@code follower_read_timestamp()} and returns the ideas ordered by votes. + * + *

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 top = awaitSize(() -> reads.topIdeas(10), 3, Duration.ofSeconds(30)); + + assertFalse(top.isEmpty(), "follower read must return the seeded ideas"); + assertEquals(3, top.size()); + assertEquals("Full-text search", top.get(0).text(), "highest-voted idea must sort first"); + assertEquals(12, top.get(0).votes()); + for (int i = 1; i < top.size(); i++) { + assertTrue(top.get(i - 1).votes() >= top.get(i).votes(), + "leaderboard must be ordered by votes descending"); + } + } + } + // end::follower-read-it[] + + /** Insert one idea with an explicit vote count (seed() always starts at zero). */ + private static void insert(DataSource ds, String text, int votes) { + try (Connection c = ds.getConnection(); + PreparedStatement ps = + c.prepareStatement("INSERT INTO idea (id, text, votes) VALUES (?, ?, ?)")) { + ps.setObject(1, UUID.randomUUID()); + ps.setString(2, text); + ps.setInt(3, votes); + ps.executeUpdate(); + } catch (Exception e) { + throw new RuntimeException("insert failed", e); + } + } + + /** + * Call {@code read} until it returns {@code expected} rows or the deadline + * passes. A follower read runs {@code AS OF SYSTEM TIME follower_read_timestamp()} + * (~4.8s in the past); on a seconds-old container that timestamp can predate the + * freshly-created schema, so the read transiently errors with "does not exist" + * until the staleness window advances. Those are expected while the window + * catches up, so we poll through them. + */ + private static List awaitSize(java.util.function.Supplier> read, + int expected, Duration timeout) { + Instant deadline = Instant.now().plus(timeout); + List last = List.of(); + RuntimeException lastError = null; + while (Instant.now().isBefore(deadline)) { + try { + last = read.get(); + lastError = null; + if (last.size() >= expected) { + return last; + } + } catch (RuntimeException e) { + lastError = e; // as-of-time read before schema existed; retry as window advances + } + try { + Thread.sleep(500); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + throw new RuntimeException(e); + } + } + if (lastError != null) { + throw new AssertionError("follower read never succeeded before deadline", lastError); + } + fail("follower read never caught up: expected " + expected + " rows, last saw " + last.size()); + return last; // unreachable + } +} diff --git a/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaMetricsIT.java b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaMetricsIT.java new file mode 100644 index 0000000..067018b --- /dev/null +++ b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/IdeaMetricsIT.java @@ -0,0 +1,73 @@ +package com.cockroachlabs.ideas; + +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 com.cockroachlabs.crdb.testing.CockroachHarness; +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 metrics module counts real work: under contention the retrying + * {@code upvote} fires retry events on the core observe bus, and wrapping each + * upvote in {@link CrdbMetrics#timeTransaction} records a transaction. The + * in-memory recorder's snapshot must show both counters moved. + * + *

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 ADD REGION 'us-east1'; ADD REGION 'us-west1'; + try (Connection c = ds.getConnection(); Statement s = c.createStatement()) { + s.execute("DROP TABLE IF EXISTS regional_idea"); + for (String ddl : RegionalIdeaService.REGIONAL_BY_ROW_DDL.split(";")) { + if (!ddl.isBlank()) { + s.execute(ddl); + } + } + } + + RegionalIdeaService svc = RegionalIdeaService.create(ds); + + UUID east = UUID.randomUUID(); + UUID west = UUID.randomUUID(); + svc.addInUsEast(east, "Home me in the east"); + svc.addInUsWest(west, "Home me in the west"); + + assertEquals("us-east1", svc.regionOf(east), "@Region(us-east1) must land the row in us-east1"); + assertEquals("us-west1", svc.regionOf(west), "@Region(us-west1) must land the row in us-west1"); + } + // end::region-test[] +} diff --git a/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/SemanticSearchIT.java b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/SemanticSearchIT.java new file mode 100644 index 0000000..edbdeb4 --- /dev/null +++ b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/SemanticSearchIT.java @@ -0,0 +1,93 @@ +package com.cockroachlabs.ideas; + +import com.cockroachlabs.crdb.ai.VectorSearchResult; +import com.cockroachlabs.crdb.testing.CockroachHarness; +import org.junit.jupiter.api.Assumptions; +import org.junit.jupiter.api.Test; +import org.postgresql.ds.PGSimpleDataSource; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Proves semantic search end to end against a real CockroachDB node: four ideas with + * deterministic {@code float[3]} embeddings are stored in a native {@code VECTOR} + * column, and a query vector near one of them returns the ideas ordered closest-first + * by cosine distance. + * + *

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 hits = semantic.findSimilar(new float[] {0.95f, 0.05f, 0.0f}, 4); + + assertEquals(4, hits.size(), "all four ideas must be returned"); + assertEquals("dark-mode", hits.get(0).id(), "nearest idea must sort first"); + assertEquals("mobile", hits.get(1).id(), "second-nearest idea must sort second"); + assertEquals("search", hits.get(2).id()); + assertEquals("export", hits.get(3).id(), "most-distant idea must sort last"); + + // Distances must be non-decreasing (closest-first), and the hero hit is very close. + for (int i = 1; i < hits.size(); i++) { + assertTrue(hits.get(i - 1).distance() <= hits.get(i).distance(), + "results must be ordered by distance ascending"); + } + assertTrue(hits.get(0).distance() < 0.01, + "the query sits almost on dark-mode, so its distance must be tiny"); + } + } + // end::vector-it[] + + private static boolean mentionsVectorUnsupported(Throwable e) { + for (Throwable t = e; t != null; t = t.getCause()) { + String m = t.getMessage(); + if (m != null) { + String lower = m.toLowerCase(); + if (lower.contains("vector") || lower.contains("type \"vector\" does not exist")) { + return true; + } + } + } + return false; + } +} diff --git a/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/SemanticSearchUnitTest.java b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/SemanticSearchUnitTest.java new file mode 100644 index 0000000..f7345b2 --- /dev/null +++ b/examples/ideas-board/src/test/java/com/cockroachlabs/ideas/SemanticSearchUnitTest.java @@ -0,0 +1,33 @@ +package com.cockroachlabs.ideas; + +import com.cockroachlabs.crdb.ai.VectorDocument; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Fast, no-Docker unit test for the one piece of genuinely unit-testable logic in the + * semantic feature: {@link IdeaDoc#toVectorDocument()} mapping. The real + * similarity-search behaviour (ordering, distances) needs a {@code VECTOR}-capable + * database and is covered by the Testcontainers {@link SemanticSearchIT}. + */ +class SemanticSearchUnitTest { + + @Test + void ideaDocMapsToVectorDocumentCarryingItsPrecomputedEmbedding() { + float[] embedding = {0.1f, 0.2f, 0.3f}; + IdeaDoc doc = new IdeaDoc("dark-mode", "Dark mode toggle", embedding); + + VectorDocument vd = doc.toVectorDocument(); + + assertEquals("dark-mode", vd.id()); + assertEquals("Dark mode toggle", vd.content()); + assertNotNull(vd.embedding(), "a precomputed embedding must be passed through, not regenerated"); + assertArrayEquals(embedding, vd.embedding(), "embedding values must survive the mapping"); + assertEquals(IdeaDoc.DIMENSIONS, vd.embedding().length, "embedding width must match the column"); + assertTrue(vd.metadata().isEmpty(), "no metadata is attached by the mapping"); + } +}