clojure.spec: Instrument next.jdbc functions
Clojure specifications are available for all
next.jdbc functions contained in namespaces
Instrumenting the functions with their specifications will check the arguments passed to a function conform to the appropriate specification. If the arguments conform, the next.jdbc function will evaluate with those arguments. If the arguments do not conform, then an error is returned.
Instrumenting specifications provided additional details when errors occur, helping diagnose the issue quickly.
Require the next.jdbc specifications
next.jdbc.specs namespace in the project, typically in the namespace where
next.jdbc is also required.
(ns practicalli.database-access (:require [next.jdbc :as jdbc] [next.jdbc.specs :as jdbc-spec]))
In a Rich Comment block, call the
instrument function from
next.jdbc.specs namespace. This will instrument the specifications for all functions across all the next.jdbc namespaces.
(comment (jdbc-spec/instrument) )
Instrumented functions are typically used during development, not in staging or production. Only calling
instrument manually from a rich comment block ensures the developer controls when functions are instrumented.
With instrumentation enabled, any calls to
next.jdbc functions will have the arguments checked to ensure they conform to the specification.
For example, the instrumented
execute! function will generate an error if passed an SQL statement as a string, rather than a vector containing a string.
(jdbc/execute! data-source "SELECT * FROM account_holders") Call to #'next.jdbc/execute! did not conform to spec.
:problems section of the instrumented function error includes the
:path [:sql :sql-params] and
:pred vector? for the
:val "SELECT * FROM account_holders".
Without the instrumented specification, assistance, the less helpful error message
ClassCastException is the only assistance when debugging the issue.
Example from Banking on Clojure
Turning off instrumentation for next.jdbc
unstrument function removes the instrumentation from the functions. Typically this is called from a rich comment block too, as its not common to run instrumented functions outside of the development environment.
(comment (jdbc-spec/instrument) (jdbc-spec/unstrument) )