toucan2.execute — io.github.camsaul/toucan2 0.10.1-alpha

Code for executing queries and statements, and reducing their results.

The functions here meant for use on a regular basis are:

• query -- resolve and compile a connectable, execute it using a connection from a connectable, and immediately fully realize the results.

• query-one -- like query, but only realizes the first result.

• reducible-query -- like query, but returns a [[clojure.lang.IReduceInit]] that can be reduced later rather than immediately realizing the results.

• with-call-count -- helper macro to count the number of queries executed within a body.

Reducible query and pipeline.

Basic execution pipeline is something this

1. [[reduce-impl]]
   1. resolve modelable => model with toucan2.model/with-model
   2. resolve queryable => query with toucan2.query/with-resolved-query
2. reduce-uncompiled-query
   1. Compile query => compile-query with toucan2.compile/with-compiled-query
3. reduce-compiled-query
   1. Open conn from connectable with toucan2.connection/with-connection
4. reduce-compiled-query-with-connection
   1. Execute and reduce the query with the open connection.

query clj

(query queryable)

(query connectable queryable)

(query connectable modelable queryable)

Like reducible-query, but immediately executes and fully reduces the query.

(query ::my-connectable ["SELECT * FROM venues;"])
;; => [{:id 1, :name "Tempest"}
       {:id 2, :name "BevMo"}]

Like reducible-query, this may be used with either SELECT queries that return rows or things like UPDATE that normally return the count of rows updated.

query-one clj

(query-one queryable)

(query-one connectable queryable)

(query-one connectable modelable queryable)

Like query, and immediately executes the query, but realizes and returns only the first result.

(query-one ::my-connectable ["SELECT * FROM venues;"])
;; => {:id 1, :name "Tempest"}

Like reducible-query, this may be used with either SELECT queries that return rows or things like UPDATE that normally return the count of rows updated.

reduce-compiled-query clj

(reduce-compiled-query connectable model compiled-query rf init)

Reduce a compiled-query with rf and init, presumably by obtaining a connection with connectable and toucan2.connection/with-connection and executing the query.

The default implementation obtains a connection this way and then hands off to reduce-compiled-query-with-connection.

Normally you would never need to call or implement this yourself, but you can write a custom implementation if you want to do something tricky like skip query execution. See toucan2.tools.compile/compile for an example of doing this.

Dispatches off of [model compiled-query].

reduce-compiled-query-with-connection clj

(reduce-compiled-query-with-connection conn model compiled-query rf init)

Execute a compiled-query with an open connection (by default a java.sql.Connection, but the actual connection type may be different depending on the connectable used to get it), and [[clojure.core/reduce]] the results using rf and init.

The default implementation for java.sql.Connection is implemented by toucan2.jdbc.query/reduce-jdbc-query.

To support non-SQL databases you can provide your own implementation of this method; see toucan2.jdbc.query/reduce-jdbc-query for an example implementation.

Dispatches off of [conn model compiled-query].

reduce-uncompiled-query clj

(reduce-uncompiled-query connectable model query rf init)

Reduce an uncompiled query with rf and init.

The default implementation of this compiles the query with compile/with-compiled-query and then hands off to reduce-compiled-query, but you can write a custom implementation if you want to do something tricky like skip compilation to return a query directly. See toucan2.tools.identity-query for an example of doing this.

Dispatches off of [model query].

reducible-query clj

(reducible-query queryable)

(reducible-query connectable queryable)

(reducible-query connectable modelable queryable)

Create a reducible query that when reduced with resolve and compile queryable, open a connection using connectable and toucan2.connection/with-connection, execute the query, and reduce the results.

Note that this query can be something like a SELECT query, or something that doesn't normally return results, like an UPDATE; this works either way. Normally something like an UPDATE will reduce to the number of rows updated/inserted/deleted, e.g. [5].

You can specify modelable to execute the query in the context of a specific model; for queries returning rows, the rows will be returned as an toucan2.instance/instance of the resolved model.

Connection Resolution

If connectable is not specified, the query will be executed using a connection from the following options:

1. the current connectable, toucan2.connection/*current-connectable*, if bound;

2. the toucan2.model/default-connectable for the model, if modelable was specified, and this is non-nil;

3. the default connectable, :default, if it is specified by a :default method for toucan2.connection/do-with-connection

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 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.)

with-call-count clj macro

(with-call-count [call-count-fn-binding] & body)

Execute body, trackingthe number of database queries and statements executed. This number can be fetched at any time withing body by calling function bound to call-count-fn-binding:

(with-call-count [call-count]
  (select ...)
  (println "CALLS:" (call-count))
  (insert! ...)
  (println "CALLS:" (call-count)))
;; -> CALLS: 1
;; -> CALLS: 2