<This is an AI managed, human verified repository>

Vert.x Replication Streams

Reactive, non-blocking change data capture (CDC) and replication streams for Vert.x.

This project provides a shared replication core plus database-specific connectors for PostgreSQL, SQL Server, MySQL, MariaDB, CockroachDB, Oracle, Db2, Cassandra, ScyllaDB, MongoDB, and Neo4j.

Why This Project

• Unified replication stream lifecycle (start(), close(), subscriptions)

• Built for Vert.x async programming model

• Typed change events and operation-aware filtering

• Retry and reconnect policies

• Pluggable checkpoint persistence (LsnStore)

Modules

• replication-core

• replication-postgres

• replication-sqlserver

• replication-mysql

• replication-mariadb

• replication-cockroachdb

• replication-oracle

• replication-db2

• replication-cassandra

• replication-scylladb

• replication-mongodb

• replication-neo4j

Note

Support language we use with customers: True CDC / logical replication: connector reads the database change log or native change stream directly. Polling CDC adapter: connector polls change rows/events on an interval (pollIntervalMs); this is CDC-style ingestion, but not direct log-streaming replication.

Support by connector:

• PostgreSQL (replication-postgres): True CDC / logical replication via PostgreSQL logical decoding (wal2json and pgoutput).

• MySQL (replication-mysql): True CDC / log-based capture via MySQL binlog streaming.

• MariaDB (replication-mariadb): True CDC / log-based capture via MariaDB binlog streaming.

• MongoDB (replication-mongodb): True CDC / native change streams via watch().

• SQL Server (replication-sqlserver): Polling CDC adapter over SQL Server CDC tables/functions.

• CockroachDB (replication-cockroachdb): Polling CDC adapter (JDBC polling model).

• Oracle (replication-oracle): Polling CDC adapter (JDBC polling model).

• Db2 (replication-db2): Polling CDC adapter (JDBC polling model).

• Cassandra (replication-cassandra): Polling CDC adapter over source/event rows.

• ScyllaDB (replication-scylladb): Polling CDC adapter over source/event rows.

• Neo4j (replication-neo4j): Polling CDC adapter over configured event query.

Requirements

• JDK 11+

• Maven 3.8+

• Docker (for integration tests)

PostgreSQL connector requirements:

• wal2json plugin installed on the server

• wal_level=logical

• max_replication_slots>=1

• max_wal_senders>=1

Installation

PostgreSQL connector:

<dependency>
  <groupId>dev.henneberger</groupId>
  <artifactId>vertx-pg-logical-replication</artifactId>
  <version>0.3.0-SNAPSHOT</version>
</dependency>

Core module:

<dependency>
  <groupId>dev.henneberger</groupId>
  <artifactId>vertx-replication-core</artifactId>
  <version>0.3.0-SNAPSHOT</version>
</dependency>

SQL Server connector:

<dependency>
  <groupId>dev.henneberger</groupId>
  <artifactId>vertx-sqlserver-cdc-replication</artifactId>
  <version>0.3.0-SNAPSHOT</version>
</dependency>

Quickstart (PostgreSQL)

Vertx vertx = Vertx.vertx();

PostgresReplicationOptions options = new PostgresReplicationOptions()
  .setHost("localhost")
  .setPort(5432)
  .setDatabase("app")
  .setUser("app")
  .setPassword("secret")
  .setSlotName("vertx_app_slot");

PostgresLogicalReplicationStream stream = new PostgresLogicalReplicationStream(vertx, options);

PostgresChangeSubscription subscription = stream.subscribe(
  PostgresChangeFilter.tables("public.orders")
    .operations(PostgresChangeEvent.Operation.INSERT, PostgresChangeEvent.Operation.UPDATE),
  event -> {
    System.out.println(event.getNewData());
    return Future.succeededFuture();
  },
  Throwable::printStackTrace
);

stream.start().onFailure(Throwable::printStackTrace);

// shutdown
subscription.cancel();
stream.close();
vertx.close();

LSN Store and Checkpointing

LsnStore controls where stream checkpoints are persisted so connectors can resume after restarts.

Default behavior:

• Most connectors default to NoopLsnStore, which does not persist checkpoints.

• With NoopLsnStore, a restart resumes from connector-specific defaults instead of the last committed checkpoint.

• For production, configure a durable store.

Available stores in replication-core:

• InMemoryLsnStore: in-process only, lost on JVM restart.

• LocalMapLsnStore: Vert.x local shared-data map, not durable across process restarts.

• FileLsnStore: durable JSON file persisted on disk.

• PrefixedLsnStore: decorator that namespaces keys for multi-tenant or multi-env deployments.

Example (PostgreSQL + durable file-backed checkpoints):

Vertx vertx = Vertx.vertx();

LsnStore lsnStore = new PrefixedLsnStore(
  new FileLsnStore(Paths.get("var/checkpoints/replication-lsn.json")),
  "prod:"
);

PostgresReplicationOptions options = new PostgresReplicationOptions()
  .setHost("localhost")
  .setPort(5432)
  .setDatabase("app")
  .setUser("app")
  .setPassword("secret")
  .setSlotName("vertx_app_slot")
  .setLsnStore(lsnStore);

Build and Test

mvn clean verify

Build and package docs:

mvn -Pdocs -DskipTests package

Documentation

• Local docs source: docs/index.adoc

• Published docs: http://vertx-logical-replication.henneberger.dev/

• Additional references:

• Building Guide

• Contributing Guide

• Publishing Guide

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a PR.

Roadmap

• Improve end-to-end integration test coverage for all connectors

• Stabilize non-PostgreSQL connector APIs

• Expand operational guidance and deployment docs

License

Apache License 2.0. See LICENSE.txt.