datahike.pg.server — org.replikativ/pg-datahike 0.1.8

PostgreSQL wire protocol server for Datahike.

Starts a pgwire-compatible server that accepts SQL queries from standard PostgreSQL clients (psql, DBeaver, JDBC, Python/psycopg2, etc.) and translates them to Datahike Datalog queries.

Usage: (require '[datahike.api :as d]) (require '[datahike.pg.server :as pg])

(def conn (d/connect cfg)) (def server (pg/start-server conn {:port 5432})) ;; ... use any PostgreSQL client ... (pg/stop-server server)

make-query-handler clj

(make-query-handler conn
                    &
                    [{:keys [on-query db-name registered-databases] :as opts}])

Create a PgWireServer.QueryHandler that dispatches SQL to Datahike.

conn: a Datahike connection opts: optional map with :on-query (fn [sql]) invoked on every SQL string :compat :strict (default) | :permissive — named bundle of features to silently accept, see compat-presets. :silently-accept a set of reject-kinds to swallow on top of the preset. Valid kinds: :grant :revoke :policy :rls :create-extension. These return a synthetic success tag (e.g. "GRANT") instead of SQLSTATE 0A000. :db-name string — the database name this handler represents. Returned by current_database(); defaults to "datahike" when omitted. :registered-databases seq of strings — all database names registered at the server. Surfaced in the virtual pg_database catalog so \l and DatabaseMetaData enumerate the server's tenancy. Typically supplied by start-server with the keys of its registry; omit for single-DB / bare-handler use.

Supports temporal session variables: SET datahike.as_of = '2024-01-15T00:00:00Z' SET datahike.since = '2024-01-01T00:00:00Z' SET datahike.history = 'true' RESET datahike.as_of

make-query-handler-factory clj

(make-query-handler-factory registry & [opts])

Build a QueryHandlerFactory that routes on the StartupMessage's database parameter.

registry: {name → conn} map of database name to Datahike conn. opts: forwarded to make-query-handler (e.g. :on-query, :compat).

Clients that pass database=X land on (registry "X"). Unknown names get a handler that errors every query with 3D000 invalid_catalog_name — matching PG's behaviour on a non-existent db.

Intended for callers who want to wrap their own PgWireServer (e.g. custom host/port binding); start-server uses it internally.

reset-advisory-locks! clj

(reset-advisory-locks!)

Clear the advisory-lock registry. Test-fixture helper; not for handler code. In production, locks release on unlock, COMMIT/ROLLBACK (xact- level), DISCARD ALL, or connection close.

reset-lock-registry! clj

(reset-lock-registry!)

Clear the server-wide row-lock registry. Intended for test fixtures — in production, locks are released on COMMIT/ROLLBACK/DISCARD ALL and when the handler's TCP connection closes. Do not call this from handler code.

start-server clj

(start-server conn-or-registry
              &
              [{:keys [port host on-query default]
                :or {port 5432 host "127.0.0.1" default "datahike"}
                :as opts}])

Start a PostgreSQL wire protocol server for one or more Datahike connections.

conn-or-registry is either:

• a single Datahike conn (convenience — treated as {"datahike" conn}), or
• a map {name → conn} of database name to conn. Clients route via the StartupMessage database parameter (e.g. jdbc:postgresql://…/prod lands on the "prod" conn).

Options: :port — Port to listen on (default 5432) :host — Host to bind to (default "127.0.0.1") :on-query — Callback (fn [sql-string]) for logging :default — Database name used when conn-or-registry is a bare conn (default "datahike"). Ignored when a map is supplied.

Returns a map with :server (PgWireServer) and :registry (the normalized {name → conn} map).

Examples: ;; single DB (def srv (pg/start-server conn {:port 5433}))

;; multi-DB (def srv (pg/start-server {"prod" prod-conn "staging" staging-conn} {:port 5432}))

(pg/stop-server srv)

stop-server clj

(stop-server {:keys [server]})

Stop a running PgWire server.