connection.clj

(ns toucan2.connection
  "#### Connection Resolution

  The rules for determining which connection to use are as follows. These are tried in order until one returns
  non-nil:

  1. The connectable specified in the function arguments.

  2. The [[toucan2.connection/*current-connectable*]], if bound. This is bound automatically when
     using [[with-connection]] or [[with-transaction]]

  3. The [[toucan2.model/default-connectable]] for the model resolved from the `modelable` in the function arguments;

  4. The `:default` implementation of [[toucan2.connection/do-with-connection]]

  You can define a 'named' connectable such as `::db` by adding an implementation
  of [[toucan2.connection/do-with-connection]], or use things like JDBC URL connection strings or [[clojure.java.jdbc]]
  connection properties maps directly.

  IMPORTANT CAVEAT! Positional connectables will be used in preference to [[*current-connectable*]], even when it was
  bound by [[with-transaction]] -- this means your query will run OUTSIDE of the current transaction! Sometimes, this is
  what you want, because maybe a certain query is meant to run against a different database! Usually, however, it is
  not! So in that case you can either do something like

  ```clj
  (t2/query (or conn/*current-connectable* ::my-db) ...)
  ```

  to use the current connection if it exists, or define your named connectable method like

  ```clj
  (m/defmethod conn/do-with-connection ::my-db
    [_connectable f]
    (conn/do-with-connection
     (if (and conn/*current-connectable*
              (not= conn/*current-connectable* ::my-db))
         conn/*current-connectable*
         \"jdbc:postgresql://...\")
     f))
  ```

  This, however, is super annoying! So I might reconsider this behavior in the future.

  For reducible queries, the connection is not resolved until the query is executed, so you may create a reducible query
  with no default connection available and execute it later with one bound. (This also means
  that [[toucan2.execute/reducible-query]] does not capture dynamic bindings such
  as [[toucan2.connection/*current-connectable*]] -- you probably wouldn't want it to, anyway, since we have no
  guarantees and open connection will be around when we go to use the reducible query later.

  The default JDBC implementations for methods here live in [[toucan2.jdbc.connection]]."
  (:require
   [clojure.spec.alpha :as s]
   [methodical.core :as m]
   [pretty.core :as pretty]
   [toucan2.log :as log]
   [toucan2.protocols :as protocols]
   [toucan2.types :as types]
   [toucan2.util :as u]))

(set! *warn-on-reflection* true)

(comment types/keep-me)

(def ^:dynamic *current-connectable*
  "The current connectable or connection. If you get a connection with [[with-connection]] or [[with-transaction]], it
  will be bound here. You can also bind this yourself to a connectable or connection, and Toucan methods called without
  an explicit will connectable will use it rather than the `:default` connection."
  nil)

(m/defmulti do-with-connection
  "Take a *connectable*, get a connection of some sort from it, and execute `(f connection)` with an open connection. A
  normal implementation might look something like:

  ```clj
  (m/defmethod t2.conn/do-with-connection ::my-connectable
    [_connectable f]
    (with-open [conn (get-connection)]
      (f conn)))
  ```

  Another common use case is to define a 'named' connectable that acts as an alias for another more complicated
  connectable, such as a JDBC connection string URL. You can do that like this:

  ```clj
  (m/defmethod t2.conn/do-with-connection ::a-connectable
    [_connectable f]
    (t2.conn/do-with-connection
     \"jdbc:postgresql://localhost:5432/toucan2?user=cam&password=cam\"
     f))
  ```"
  {:arglists            '([connectable₁ f])
   :defmethod-arities   #{2}
   :dispatch-value-spec ::types/dispatch-value.keyword-or-class}
  u/dispatch-on-first-arg
  :default-value ::default)

(defn- bind-current-connectable-fn
  "Wrap functions as passed to [[do-with-connection]] or [[do-with-transaction]] in a way that
  binds [[*current-connectable*]]."
  [f]
  {:pre [(fn? f)]}
  (^:once fn* [conn]
   (binding [*current-connectable* conn]
     (f conn))))

(m/defmethod do-with-connection :around ::default
  "Do some debug logging/context capture. Bind [[*current-connectable*]] to the connection `f` is called with inside of
  `f`."
  [connectable f]
  (assert (fn? f))
  ;; add the connection class or pretty representation rather than the connection type itself to avoid leaking sensitive
  ;; creds
  (let [connectable-class (if (instance? pretty.core.PrettyPrintable connectable)
                            (pretty/pretty connectable)
                            (protocols/dispatch-value connectable))]
    (log/debugf "Resolve connection %s" connectable-class)
    (u/try-with-error-context ["resolve connection" {::connectable connectable-class}]
      (next-method connectable (bind-current-connectable-fn f)))))

(defmacro with-connection
  "Execute `body` with an open connection. There are three ways to use this.

  With no args in the bindings vector, `with-connection` will use the *current connection* -- [[*current-connectable*]]
  if one is bound, or the *default connectable* if not. See docstring for [[toucan2.connection]] for more information.

  ```clj
  (t2/with-connection []
    ...)
  ```

  With one arg, `with-connection` still uses the *current connection*, but binds it to something (`conn` in the example
  below):

  ```clj
  (t2/with-connection [conn]
    ...)
  ```

  If you're using the default JDBC backend, `conn` will be an instance of `java.sql.Connection`. Since Toucan 2 is also
  written to work with other backend besides JDBC, `conn` does *not* include `java.sql.Connection` `:tag` metadata! If
  you're doing Java interop with `conn`, make sure to tag it yourself:

  ```clj
   (t2/with-connection [^java.sql.Connection conn]
     (let [metadata (.getMetaData conn)]
       ...))
  ```

  With a connection binding *and* a connectable:

  ```clj
  (t2/with-connection [conn ::my-connectable]
    ...)
  ```

  This example gets a connection by calling [[do-with-connection]] with `::my-connectable`, ignoring the *current
  connection*."
  {:arglists '([[connection-binding]             & body]
               [[connection-binding connectable] & body])}
  [[connection-binding connectable] & body]
  `(do-with-connection
    ~connectable
    (^:once fn* with-connection* [~(or connection-binding '_)] ~@body)))

(s/fdef with-connection
  :args (s/cat :bindings (s/spec (s/cat :connection-binding (s/? symbol?)
                                        :connectable        (s/? any?)))
               :body (s/+ any?))
  :ret  any?)

;;; method if this is called with something we don't know how to handle or if no default connection is defined. This is
;;; separate from `:default` so if you implement `:default` you don't accidentally have that get called for unknown
;;; connectables
(m/defmethod do-with-connection ::default
  [connectable _f]
  (throw (ex-info (format "Don't know how to get a connection from ^%s %s. Do you need to implement %s for %s?"
                          (some-> connectable class .getCanonicalName)
                          (pr-str connectable)
                          `do-with-connection
                          (protocols/dispatch-value connectable))
                  {:connectable connectable})))

;;; method called if there is no current connection.
(m/defmethod do-with-connection :default
  [_connectable _f]
  (throw (ex-info (str "No default Toucan connection defined. "
                       (format "You can define one by implementing %s for :default. "
                               `do-with-connection)
                       (format "You can also implement %s for a model, or bind %s."
                               'toucan2.model/default-connectable
                               `*current-connectable*))
                  {})))

(m/defmethod do-with-connection nil
  "`nil` means use the current connection.

  The difference between `nil` and using [[*current-connectable*]] directly is that this waits until it gets resolved
  by [[do-with-connection]] to get the value for [[*current-connectable*]]. For a reducible query this means you'll get
  the value at the time you reduce the query rather than at the time you build the reducible query."
  [_connectable f]
  (let [current-connectable (if (nil? *current-connectable*)
                              :default
                              *current-connectable*)]
    (do-with-connection current-connectable f)))

;;;; connection string support

(defn connection-string-protocol
  "Extract the protocol part of a `connection-string`.

  ```clj
  (connection-string-protocol \"jdbc:postgresql:...\")
  =>
  \"jdbc\"
  ```"
  [connection-string]
  (when (string? connection-string)
    (second (re-find #"^(?:([^:]+):)" connection-string))))

(m/defmulti do-with-connection-string
  "Implementation of [[do-with-connection]] for strings. Dispatches on the [[connection-string-protocol]] of the string,
  e.g. `\"jdbc\"` for `\"jdbc:postgresql://localhost:3000/toucan\"`."
  {:arglists            '([^java.lang.String connection-string f])
   :defmethod-arities   #{2}
   :dispatch-value-spec string?}
  (fn [connection-string _f]
    (connection-string-protocol connection-string)))

(m/defmethod do-with-connection String
  "Implementation for Strings. Hands off to [[do-with-connection-string]]."
  [connection-string f]
  (do-with-connection-string connection-string f))

;;; JDBC implementations live in [[toucan2.jdbc.connection]]

(m/defmulti do-with-transaction
  "`options` are options for determining what type of transaction we'll get. See dox for [[with-transaction]] for more
  information."
  {:arglists            '([connection₁ options f])
   :defmethod-arities   #{3}
   :dispatch-value-spec ::types/dispatch-value.keyword-or-class}
  u/dispatch-on-first-arg
  :default-value ::default)

(m/defmethod do-with-transaction :around ::default
  "Bind [[*current-connectable*]] to the connection `f` is called with inside of `f`."
  [connection options f]
  (log/debugf "do with transaction %s %s" options (some-> connection class .getCanonicalName symbol))
  (next-method connection options (bind-current-connectable-fn f)))

(defmacro with-transaction
  "Gets a connection with [[with-connection]], and executes `body` within that transaction.

  An `options` map, if specified, determine what sort of transaction we're asking for (stuff like the read isolation
  level and what not). One key, `:nested-transaction-rule`, is handled directly in Toucan 2; other options are passed
  directly to the underlying implementation, such as [[next.jdbc.transaction]].

  `:nested-transaction-rule` must be one of `#{:allow :ignore :prohibit}`, a set of possibilities borrowed from
  `next.jdbc`. For non-JDBC implementations, you should treat `:allow` as the default behavior if unspecified."
  {:style/indent 1, :arglists '([[conn-binding connectable options?] & body])}
  [[conn-binding connectable options] & body]
  `(with-connection [conn# ~connectable]
     (do-with-transaction conn# ~options (^:once fn* with-transaction* [~(or conn-binding '_)] ~@body))))

(s/def :toucan2.with-transaction-options/nested-transaction-rule
  (s/nilable #{:allow :ignore :prohibit}))

(s/def ::with-transaction-options
  (s/keys :opt-un [:toucan2.with-transaction-options/nested-transaction-rule]))

(s/fdef with-transaction
  :args (s/cat :bindings (s/spec (s/cat :connection-binding (s/? symbol?)
                                        :connectable        (s/? any?)
                                        :options            (s/? ::with-transaction-options)))
               :body (s/+ any?))
  :ret  any?)

;;; JDBC implementation lives in [[toucan2.jdbc.connection]]