Transaction Functions

A transaction function lets you build transactions that are flexible based on the value of the database at the start of the transaction (db-before). Rather than determining all the values a transaction needs prior to submitting the transaction, you can use transaction functions to calculate values based on the current state of the database (db-before).

A transaction function is a pure function [db-before, args] -> tx-data, i.e. a transaction function takes db-before plus args you provide and produces tx-data for inclusion in the transaction.

Transaction functions support the operation of d/with, which is also a pure function [db-before, tx-data] -> tx-data. d/with calls transaction functions to augment tx-data, producing more tx-data:

tx-data + (tx-fn db-before args) -> tx-data'

Transaction functions are tightly focused: they do not see the entire tx-data, only the args passed to them. They also do not see each other's return value. This tight focus is semantically critical, e.g. if d/with piped the return value from one transaction function into the next, then Datomic transactions would have order semantics and no longer be declarative!

Consistency refers to the property that a database transaction takes the database from one valid state to another. Datomic has a number of built-in consistency checks that you can augment by writing custom entity predicates and transaction functions. Datomic’s features are well-tested and optimized, and you should prefer them over writing custom code where they fit your use case. Generally speaking, you should work your way down the table below, preferring the approaches listed earlier if they are sufficient for your needs.

By their nature, transaction functions and entity predicates run inside the serialized pipeline of transactions for a database. A slow transaction function and/or entity predicate will impact not only the current transaction, but any transaction requests queued behind the current transaction in the pipeline. Transaction functions and entity predicates should do the minimal amount of work possible, and should do only work that requires access to the in-transaction value of the database.

Transaction functions and entity predicates are arbitrary code, and should be safeguarded in the same ways you would safeguard any other mechanism for deploying code into production. In particular, database functions are deployed via transactions, so you should prevent arbitrary transactions from untrusted users.

Datomic supports two types of transaction function: database functions and classpath functions. They have essentially the same capabilities and differ primarily in how they are deployed.

1. You can transactionally store a database function in a Datomic database. After you do, this function is available on the transactor and in any peer. Database functions can accept up to 10 arguments.
2. Classpath functions use Java’s classpath.

You can use either or both approaches, which differ as follows:

Datomic calls transaction functions automatically when encountering anything other than :db/add or :db/retract as the first element in a list form. For example, the transaction data below includes a call to the built-in transaction function :db/retractEntity

[[:db/retractEntity [:person/email "jdoe@example.com"]]]

Transaction functions can abort a transaction for any reason whatsoever by calling cancel, or they can expand to (possibly empty) data that will be included in the transaction.

The following example installs and invokes a trivial database function:

;; tx-data to install the function
[{:db/ident :add-doc
  :db/fn    (d/function
              {:lang   "clojure"
               :params '[db e doc]
               :code   [[:db/add 'e :db/doc 'doc]]})}]

;; tx-data to call the function
[[:add-doc "foo" "this is foo's doc"]]

The example below installs and invokes an equivalent classpath transaction function:

;; put this on the transactor's classpath
(ns my.fns)
(defn add-doc
  [db e doc]
  [[:db/add e :db/doc doc]])

;; and then put this tx-data in a transaction
[[my.fns/add-doc "foo" "this is foo's doc"]]

The following transaction functions are automatically included in Datomic for you to use.

If you have a consistency requirement that is not covered by a built-in feature of Datomic, you can write a custom transaction function, adhering to the following rules:

1. Must be pure functions, free of side effects.
2. Must take the current value of the database (db-before) as a first argument, followed by data arguments that match the arguments in the transaction data.
3. On success, must return valid transaction data (which can include more transaction functions!)
4. To abort a transaction, call cancel.
5. Transaction data is serialized with Fressian. Transaction functions should not rely on, or presume, Clojure collection capabilities since collections deserialized by Fressian are guaranteed only Java interfaces.

cancel cancels the current Datomic query or transaction, and throws an ex-info with an anomaly to the original caller.

cancel requires a map with the key :cognitect.anomalies/category, which has valid values of:

• :cognitect.anomalies/incorrect
• :cognitect.anomalies/conflict

When :cognitect.anomalies/message is provided, the message will be used as the Exception's detail message.

All other keys should be namespace-qualified and all data passed to cancel must be either transit-serializable in the Client API, or fressian-serializable in the Peer API.

The example below uses a transaction function to ensure that users always have a name and email. The first transaction succeeds, but the second is canceled since :address is passed instead of :email.

(def add-user-code
  '(if (every? umap [:name :email])
     [{:user/name (:name umap)
       :user/email (:email umap)}]
     (datomic.api/cancel {:cognitect.anomalies/category :cognitect.anomalies/incorrect
                          :cognitect.anomalies/message "User map must contain :email and :name"})))

;; Install transaction function:
@(d/transact conn [{:db/ident :add-user
                    :db/fn (d/function {:lang "clojure" :params '[db umap] :code add-user-code})}])

;; Success:
@(d/transact conn [[:add-user {:name "Marshall" :email "test@test.com"}]])

=> ;; tx result map
;; Failure:
@(d/transact conn [[:add-user {:name "Marshall" :address "test@test.com"}]])

=> Execution error (ExceptionInfo) at datomic.error/deserialize-exception (error.clj:175).
User map must contain :email and :name

Transaction functions are ordinary code, and can be developed and tested in whatever environment/IDE you use for writing JVM code. In particular, they are suited for REPL-based testing in Clojure.

Database functions and classpath functions are deployed differently.