XTDB

All functions are located in the com.biffweb namespace.

(start-node
 {:keys [topology dir opts jdbc-spec pool-opts kv-store tx-fns],
  :or {kv-store :rocksdb},
  :as options})

A higher-level version of xtdb.api/start-node.

Calls xtdb.api/sync before returning the node.

topology:   One of #{:standalone :jdbc}.
kv-store:   One of #{:rocksdb :lmdb}. Default :rocksdb
dir:        A path to store RocksDB instances in.
jdbc-spec,
pool-opts:  Used only when topology is :jdbc. Passed in as
            {:xtdb.jdbc/connection-pool
             {:db-spec jdbc-spec :pool-opts pool-opts ...}}.
opts:       Additional options to pass to xtdb.api/start-node.
tx-fns:     A map of transaction functions to be saved after indexing
            finishes. See save-tx-fns!

(use-xtdb
 {:keys [biff/secret],
  :biff.xtdb/keys [topology kv-store dir opts tx-fns],
  :as ctx})

A Biff component that starts an XTDB node.

Sets :biff.xtdb/node on the system map. topology, kv-store, dir, opts and
tx-fns are passed to start-node. Any keys matching :biff.xtdb.jdbc/* or
:biff.xtdb.jdbc-pool/* are passed in as jdbc-spec and pool-opts,
respectively.

If :biff/secret is set, the value of :biff.xtdb.jdbc/password will be replaced
with (secret :biff.xtdb.jdbc/password).

(use-xtdb-tx-listener
 {:keys
  [biff/modules
   biff/plugins
   biff/features
   biff.xtdb/on-tx
   biff.xtdb/node],
  :as ctx})

If on-tx or modules is provided, starts an XTDB transaction listener.

modules:  A var containing a collection of module maps. Each module map may
          contain an :on-tx key.
plugins:  Deprecated. Alias for modules. modules takes precedence.
features: Deprecated. Alias for modules. modules and plugins take precedence.
on-tx:    Deprecated. Use modules instead. If set, takes precedence over
          modules.

Calls each on-tx function in modules whenever a new transaction is
successfully indexed. on-tx receives the system map and the transaction, i.e.
(on-tx ctx tx). tx is the transaction as returned by (xtdb.api/open-tx-log
node tx-id true). on-tx will not be called concurrently: if a second
transaction is indexed while on-tx is still running, use-xtdb-tx-listener will
wait until it finishes before passing the second transaction.

(use-xt
 {:keys [biff/secret],
  :biff.xtdb/keys [topology kv-store dir opts tx-fns],
  :as ctx})

Deprecated. Renamed to use-xtdb.

(use-tx-listener
 {:keys
  [biff/modules
   biff/plugins
   biff/features
   biff.xtdb/on-tx
   biff.xtdb/node],
  :as ctx})

Deprecated. Renamed to use-xtdb-tx-listener.

(assoc-db {:keys [biff.xtdb/node], :as ctx})

Sets :biff/db on the context map to (xt/db node)

(q db query & args)

Convenience wrapper for xtdb.api/q.

If the :find value is not a vector, results will be passed through
(map first ...) after (vector ...)-ing the value. Also throws an exception if
(count args) doesn't match (count (:in query)).

(lazy-q db query & args)

Calls xtdb.api/open-q and passes a lazy seq of the results to a function.

Accepts the same arguments as xtdb.api/open-q, except the last argument is a
function which must process the results eagerly. Also includes the same
functionality as biff/q.

(lookup db & args)

Returns the first document found with the given key(s) and value(s).

For example:
(lookup db :user/email "hello@example.com")
=> {:xt/id #uuid "...", :user/email "hello@example.com"}

You can pass in a custom pull expression if needed (default is '[*]):
(lookup db '[:xt/id {:msg/_user [:msg/text]}] :user/email "hello@example.com")
=> {:xt/id #uuid "..."
    :msg/_user ({:msg/text "hello"}
                {:msg/text "how do you do"})}

(lookup-all db & args)

Like lookup, but returns multiple documents.

(lookup-id db & kvs)

Returns the ID of the first document found with the given key(s) and value(s).

For example:
(lookup-id db :user/email "hello@example.com")
=> #uuid "..."

(lookup-id-all db & kvs)

Like lookup-id, but returns multiple documents.

(biff-tx->xt
 {:keys [biff/now biff/db biff/malli-opts], :as ctx}
 biff-tx)

Converts the given Biff transaction into an XT transaction.

The elements of biff-tx may be maps (in which case they are treated as Biff
operations) or vectors (in which case they are treated as XT operations). For
example:

[{:db/doc-type :user
  :xt/id #uuid "..."
  :user/name "example"}
 [:xtdb.api/put {:xt/id #uuid "..."}]]

biff-tx may optionally be a function which takes ctx and returns a Biff
transaction.

See https://biffweb.com/docs/reference/transactions.

(submit-with-retries ctx make-tx)

Submits an XT transaction, retrying up to three times if there is contention.
Blocks until the transaction is indexed or aborted.

make-tx is a one-argument function that takes the context map and returns an
XT transaction. The :biff/db and :biff/now keys in ctx will be updated before
each time make-tx is called.

(submit-tx
 {:keys [biff.xtdb/retry biff.xtdb/node], :or {retry true}, :as ctx}
 biff-tx)

High-level wrapper over xtdb.api/submit-tx. See biff-tx->xt.

If retry is true, the transaction will be passed to submit-with-retries.

(save-tx-fns! node tx-fns)

Saves (or updates) the given transaction functions.

For example, given the map {:foo '(fn ...)}, a transaction of the form
[:xtdb.api/put {:xt/id :foo :xt/fn '(fn ...)}] will be submitted.

If all the given functions are already in the database and haven't been
changed, then no transaction will be submitted.

A map of Biff-provided transaction functions. See use-xtdb and save-tx-fns!

Includes the following tx fns:

:biff/ensure-unique - Aborts the transaction if more than one document
contains the given key-value pairs. For example:

(biff/submit-tx ctx
  [{:db/doc-type :user
    :db/op :update
    :xt/id user-id
    :user/name "example"}
   [:xtdb.api/fn :biff/ensure-unique {:user/name "example"}]])

(test-xtdb-node docs)

Returns an in-memory node that's initialized with the given docs and with biff/tx-fns.

 Each element of docs will be given a random UUID for :xt/id, unless you
 supply one. The docs are inserted with :xtdb.api/put operations, i.e. they're
 inserted verbatim without schema checking or any other biff/submit-tx
 features.

 Example:

   (deftest my-test
     (with-open [node (test-xtdb-node [{:user/email "hello@example.com"}
                                       {:user/email "there@example.com"}])]
       (let [db (xt/db node)]
         ...)))