ebifriedrice.postlog.admin — net.clojars.ebifriedrice/postlog 0.1.0

Manage the server-side objects a logical-replication consumer needs: replication slots and publications, plus the introspection (WAL level, current LSN, slot state) that operations around a consumer want.

Everything here runs as ordinary SQL on a regular connection -- no replication protocol -- so it works with any JDBC connection the caller already has. Connect with a map or a JDBC URL:

(with-open [conn (admin/connect {:host "localhost" :database "app"
                                 :user "repl" :password "..."})]
  (admin/ensure-slot! conn "my_slot")
  (admin/ensure-publication! conn "my_pub" {:tables ["public.users"]}))

A user creating slots or publications needs enough privilege (superuser, or pg_create_subscription/ownership as the server version allows) and the server must run wal_level = logical.

connect clj

(connect spec)

Open a java.sql.Connection from a spec map or JDBC URL string. The caller owns closing it (with-open works).

create-publication! clj

(create-publication! conn pub-name opts)

Create a publication (see publication-ddl for opts).

create-slot! clj

(create-slot! conn name)

(create-slot! conn name {:keys [plugin] :or {plugin "pgoutput"} :as _opts})

Create a logical replication slot. Returns {:slot-name ... :lsn ...} where :lsn (the slot's consistent point) is where a stream from this slot begins. opts:

:plugin output plugin, default pgoutput.

Creating a slot pins WAL from that point: drop it when done, or the server retains WAL forever.

current-wal-lsn clj

(current-wal-lsn conn)

The server's current write-ahead log position, as a long LSN.

drop-publication! clj

(drop-publication! conn pub-name {:keys [if-exists?]})

Drop a publication. Pass :if-exists? true to tolerate a missing one.

drop-slot! clj

(drop-slot! conn name)

Drop a replication slot, freeing its WAL retention. Fails (as Postgres does) when the slot is active.

ensure-publication! clj

(ensure-publication! conn name opts)

The publication named name, created with opts if missing. Returns {:created? bool :tables [...]}.

ensure-slot! clj

(ensure-slot! conn name)

(ensure-slot! conn name opts)

The slot named name, created with opts if missing. Idempotent bootstrap for consumers. Returns slot-info (plus :created?).

jdbc-url clj

(jdbc-url spec)

JDBC URL for spec: a map (:host :port :database :user plus any extra params, keywordized as query params) or an existing URL string, passed through.

publication-ddl clj

(publication-ddl pub-name
                 {:keys [tables all-tables? publish via-partition-root?]
                  :or {publish [:insert :update :delete :truncate]}})

The CREATE PUBLICATION statement for pub-name and opts:

:tables vector of table names ("public.users"); mutually exclusive with :all-tables? :all-tables? publish every table (FOR ALL TABLES) :publish operations to publish, subset of #{:insert :update :delete :truncate}, default all :via-partition-root? publish partition leaf rows through the root table (Postgres 13+)

Exposed because the DDL string is what there is to unit-test.

publication-exists? clj

(publication-exists? conn name)

publication-tables clj

(publication-tables conn name)

The schema.table names a publication carries.

replication-jdbc-url clj

(replication-jdbc-url spec)

Like jdbc-url but with the parameters that make a pgjdbc connection a replication connection: replication=database and assumeMinServerVersion=14. The version assumption is load bearing: pgjdbc forwards the replication flag in the startup packet only when it believes the server is at least 9.4, and without the assumption the connection silently opens as a regular one whose first replication command dies as a SQL syntax error. postlog supports Postgres 14+.

slot-exists? clj

(slot-exists? conn name)

slot-info clj

(slot-info conn name)

The slot named name, or nil. Shape as in slots.

slots clj

(slots conn)

All replication slots the server holds, as maps with parsed LSNs.

wal-level clj

(wal-level conn)

The server's wal_level setting; logical replication requires logical.