Helper functions for querying the DB and inserting or updating records using Toucan models.

CONFIGURATION

Quoting Style

The quoting style is the HoneySQL quoting style that should be used to quote identifiers. By default, this is :ansi, which wraps identifers in double-quotes. Alternatively, you can specify :mysql (backticks), or :sqlserver (square brackets)

Bind this to override the identifier quoting style. Provided for cases where you want to override the quoting style (such as when connecting to a different DB) without changing the default value.

Set the default quoting style that should be used to quote identifiers. Defaults to :ansi, but you can instead set it to :mysql or :sqlserver.

Fetch the HoneySQL quoting style that should be used to quote identifiers. One of :ansi, :mysql, or :sqlserver.

Returns the value of *quoting-style* if it is bound, otherwise returns the default quoting style, which is normally :ansi; this can be changed by calling set-default-quoting-style!.

Additional HoneySQL options

Automatically Convert Dashes & Underscores

Convert dashes to underscores in queries going into the DB, and underscores in results back to dashes coming out of the DB. By default, this is disabled. See the documentation in setup.md for more details.

Bind this to enable automatic conversion between dashes and underscores for indentifiers. Provided for cases where you want to override the behavior (such as when connecting to a different DB) without changing the default value.

Set the default value for allowing dashes in field names. Defaults to true.

Deterimine whether we should automatically convert dashes and underscores in identifiers.

Returns the value of *automatically-convert-dashes-and-underscores* if it is bound, otherwise returns the default-automatically-convert-dashes-and-underscores, which is normally false; this can be changed by calling set-default-automatically-convert-dashes-and-underscores!.

DB Connection

The default DB connection is used automatically when accessing the DB; it can be anything that would normally be passed to clojure.java.jdbc functions -- normally a connection details map, but alternatively something like a C3PO connection pool.

Bind this to override the default DB connection used by toucan.db functions. Provided for situations where you'd like to connect to a DB other than the primary application DB, or connect to it with different connection options.

Set the JDBC connecton details map for the default application DB connection. This connection is used by default by the various toucan.db functions.

db-connection-map is passed directly to clojure.java.jdbc; it can be anything that is accepted by it.

 (db/set-default-db-connection!
   {:classname   "org.postgresql.Driver"
    :subprotocol "postgresql"
    :subname     "//localhost:5432/my_db"
    :user        "cam"})

Set the default options to be used for all calls to clojure.java.jdbc/query or execute!.

TRANSACTION & CONNECTION UTIL FNS

Transaction connection to the application DB. Used internally by transaction.

Fetch the JDBC connection details for passing to clojure.java.jdbc. Returns *db-connection*, if it is set; otherwise *transaction-connection*, if we're inside a transaction (this is bound automatically); otherwise the default DB connection, set by set-default-db-connection!.

If no DB connection has been set this function will throw an exception.

Execute F inside a DB transaction. Prefer macro form transaction to using this directly.

Execute all queries within the body in a single transaction.

QUERY UTIL FNS

Should we disable logging for database queries? Normally false, but bind this to true to keep logging from getting too noisy during operations that require a lot of DB access, like the sync process.

Return the namespace symbol where we'd expect to find an model symbol.

 (model-symb->ns 'CardFavorite) -> 'my-project.models.card-favorite

Resolve the model associated with SYMB, calling require on its namespace if needed.

 (resolve-model-from-symbol 'CardFavorite) -> my-project.models.card-favorite/CardFavorite

Resolve a model if it's quoted. This also unwraps entities when they're inside vectores.

 (resolve-model Database)         -> #'my-project.models.database/Database
 (resolve-model [Database :name]) -> #'my-project.models.database/Database
 (resolve-model 'Database)        -> #'my-project.models.database/Database

The function that JDBC should use to quote identifiers for our database. This is passed as the :entities option to functions like jdbc/insert!.

Atom used as a counter for DB calls when enabled. This number isn't perfectly accurate, only mostly; DB calls made directly to JDBC won't be logged.

Execute F with DB call counting enabled. F is passed a single argument, a function that can be used to retrieve the current call count. (It's probably more useful to use the macro form of this function, with-call-counting, instead.)

Execute body and track the number of DB calls made inside it. call-count-fn-binding is bound to a zero-arity function that can be used to fetch the current DB call count.

 (db/with-call-counting [call-count] ...
   (call-count))

Print the number of DB calls executed inside body to stdout. Intended for use during REPL development.

Execute f with debug query logging enabled. Don't use this directly; prefer the debug-print-queries macro form instead.

Print the HoneySQL and SQL forms of any queries executed inside body to stdout. Intended for use during REPL development.

Compile honeysql-form to SQL. This returns a vector with the SQL string as its first item and prepared statement params as the remaining items.

Compile honeysql-from and call jdbc/query against the application database. Options are passed along to jdbc/query.

Compile honeysql-from and call jdbc/reducible-query against the application database. Options are passed along to jdbc/reducible-query. Note that the query won't actually be executed until it's reduced.

Qualify a field-name name with the name its entity. This is necessary for disambiguating fields for HoneySQL queries that contain joins.

 (db/qualify 'CardFavorite :id) -> :report_cardfavorite.id

Is field-name qualified (e.g. with its table name)?

Qualify field-name with its table name if it's not already qualified.

Get the fields that should be used in a query, destructuring entity if it's wrapped in a vector, otherwise calling default-fields. This will return nil if the model isn't wrapped in a vector and uses the default implementation of default-fields.

 (model->fields 'User) -> [:id :email :date_joined :first-name :last-name :last_login :is_superuser :is_qbnewb]
 (model->fields ['User :first-name :last-name]) -> [:first-name :last-name]
 (model->fields 'Database) -> nil

Replace underscores in k with dashes. In other words, converts a keyword from :snake_case to :lisp-case.

 (replace-underscores :2_cans) ; -> :2-cans

Replace the keys in any maps in x with the result of (f key). Recursively walks x using clojure.walk.

Perform post-processing for objects fetched from the DB. Convert results objects to entity record types and call the model's post-select method on them.

Includes projected fields and a from clause for honeysql-form. Will not override if already present.

Select objects from the database.

Like select, but doesn't offer as many conveniences, so prefer that instead; like select, simple-select callts post-select on the results, but unlike select, only accepts a single raw HoneySQL form as an argument.

(db/simple-select 'User {:where [:= :id 1]})

Select objects from the database.

Same as simple-select, but returns something reducible instead of a result set. Like simple-select, will call post-select on the results, but will do so lazily.

(transduce (filter can-read?) conj [] (simple-select-reducible 'User {:where [:= :id 1]}))

Select a single object from the database.

Like select-one, but doesn't offer as many conveniences, so prefer that instead; like select-one, simple-select-one callts post-select on the results, but unlike select-one, only accepts a single raw HoneySQL form as an argument.

(db/simple-select-one 'User (h/where [:= :first-name "Cam"]))

Compile honeysql-form and call jdbc/execute! against the application DB. options are passed directly to jdbc/execute! and can be things like :multi? (default false) or :transaction? (default true).

Generate a HoneySQL where form using key-value args.

 (where {} :a :b)        -> (h/merge-where {} [:= :a :b])
 (where {} :a [:!= b])   -> (h/merge-where {} [:!= :a :b])
 (where {} {:a [:!= b]}) -> (h/merge-where {} [:!= :a :b])

Generate a HoneySQL form, converting pairs of arguments with keywords into a where clause, and merging other HoneySQL clauses in as-is. Meant for internal use by functions like select. (So-called because it handles where plus other clauses).

 (where+ {} [:id 1 {:limit 10}]) -> {:where [:= :id 1], :limit 10}

UPDATE!

Update a single row in the database. Returns true if a row was affected, false otherwise. Accepts either a single map of updates to make or kwargs. entity is automatically resolved, and pre-update is called on kvs before the object is inserted into the database.

 (db/update! 'Label 11 :name "ToucanFriendly")
 (db/update! 'Label 11 {:name "ToucanFriendly"})

Convenience for updating several objects matching conditions-map. Returns true if any objects were affected. For updating a single object, prefer using update!, which calls entity's pre-update method first.

 (db/update-where! Table {:name  table-name
                          :db_id (:id database)}
   :active false)

Like update!, but filters out KVS with nil values.

INSERT!

Different possible keys that might come back for the ID of a newly inserted row. Differs by DB.

Get the ID of a row inserted by jdbc/db-do-prepared-return-keys.

Do a simple JDBC insert! of multiple objects into the database. Normally you should use insert-many! instead, which calls the model's pre-insert method on the row-maps; simple-insert-many! is offered for cases where you'd like to specifically avoid this behavior. Returns a sequences of IDs of newly inserted objects.

 (db/simple-insert-many! 'Label [{:name "Toucan Friendly"}
                                 {:name "Bird Approved"}]) ;;=> (38 39)

Insert several new rows into the Database. Resolves entity, and calls pre-insert on each of the row-maps. Returns a sequence of the IDs of the newly created objects.

Note: this does not call post-insert on newly created objects. If you need post-insert behavior, use insert! instead. (This might change in the future: there is an open issue to consider this).

 (db/insert-many! 'Label [{:name "Toucan Friendly"}
                          {:name "Bird Approved"}]) -> [38 39]

Do a simple JDBC insert of a single object. This is similar to insert! but returns the ID of the newly created object rather than the object itself, and does not call pre-insert or post-insert.

 (db/simple-insert! 'Label :name "Toucan Friendly") -> 1

Like insert!, simple-insert! can be called with either a single row-map or kv-style arguments.

Insert a new object into the Database. Resolves entity, calls its pre-insert method on row-map to prepare it before insertion; after insert, it fetches and the newly created object, passes it to post-insert, and returns the results.

For flexibility, insert! can handle either a single map or individual kwargs:

 (db/insert! Label {:name "Toucan Unfriendly"})
 (db/insert! 'Label :name "Toucan Friendly")

SELECT

All of the following functions are based off of the old sel macro and can do things like select certain fields by wrapping ENTITY in a vector and automatically convert kv-args to a where clause

Select a single object from the database.

 (select-one ['Database :name] :id 1) -> {:name "Sample Dataset"}

Select a single field of a single object from the database.

 (select-one-field :name 'Database :id 1) -> "Sample Dataset"

Select the :id of a single object from the database.

 (select-one-id 'Database :name "Sample Dataset") -> 1

Select the count of objects matching some condition.

 ;; Get all Users whose email is non-nil
 (count 'User :email [:not= nil]) -> 12

Select objects from the database.

 (select 'Database :name [:not= nil] {:limit 2}) -> [...]

Select objects from the database, returns a reducible.

 (transduce (map :name) conj [] (select 'Database :name [:not= nil] {:limit 2}))
    -> ["name1", "name2"]

Select values of a single field for multiple objects. These are returned as a set if any matching fields were returned, otherwise nil.

 (select-field :name 'Database) -> #{"Sample Dataset", "test-data"}

Select IDs for multiple objects. These are returned as a set if any matching IDs were returned, otherwise nil.

 (select-ids 'Table :db_id 1) -> #{1 2 3 4}

Select fields k and v from objects in the database, and return them as a map from k to v.

 (select-field->field :id :name 'Database) -> {1 "Sample Dataset", 2 "test-data"}

Select FIELD and :id from objects in the database, and return them as a map from field to :id.

 (select-field->id :name 'Database) -> {"Sample Dataset" 1, "test-data" 2}

Select field and :id from objects in the database, and return them as a map from :id to field.

 (select-id->field :name 'Database) -> {1 "Sample Dataset", 2 "test-data"}

EXISTS?

Easy way to see if something exists in the DB.

(db/exists? User :id 100)

DELETE!

Delete an object or objects from the application DB matching certain constraints. Returns true if something was deleted, false otherwise.

 (db/simple-delete! 'Label)                ; delete all Labels
 (db/simple-delete! Label :name "Cam")   ; delete labels where :name == "Cam"
 (db/simple-delete! Label {:name "Cam"}) ; for flexibility either a single map or kwargs are accepted

Unlike delete!, this does not call pre-delete on the object about to be deleted.

Delete of object(s). For each matching object, the pre-delete multimethod is called, which should do any cleanup needed before deleting the object, (such as deleting objects related to the object about to be deleted), or otherwise enforce preconditions before deleting (such as refusing to delete the object if something else depends on it).

 (delete! Database :id 1)

Functions for deserializing and hydrating fields in objects fetched from the DB.

Counts Destructuring & Restructuring

*DISCLAIMER*

This I wrote this code at 4 AM nearly 2 years ago and don't remember exactly what it is supposed to accomplish, or why. It generates a sort of path that records the wacky ways in which objects in a collection are nested, and how they fit into sequences; it then returns a flattened sequence of desired objects for easy modification. Afterwards the modified objects can be put in place of the originals by passing in the sequence of modified objects and the path.

Nonetheless, it still works (somehow) and is well-tested. But it's definitely overengineered and crying out to be replaced with a simpler implementation (clojure.walk would probably work here). PRs welcome!

Original Overview

At a high level, these functions let you aggressively flatten a sequence of maps by a key so you can apply some function across it, and then unflatten that sequence.

     +-------------------------------------------------------------------------+
     |                                                                         +--> (map merge) --> new seq
seq -+--> counts-of ------------------------------------+                      |
     |                                                  +--> counts-unflatten -+
     +--> counts-flatten -> (modify the flattened seq) -+

1. Get a value that can be used to unflatten a sequence later with counts-of.
2. Flatten the sequence with counts-flatten
3. Modify the flattened sequence as needed
4. Unflatten the sequence by calling counts-unflatten with the modified sequence and value from step 1
5. map merge the original sequence and the unflattened sequence.

For your convenience counts-apply combines these steps for you.

Return a sequence of counts / keywords that can be used to unflatten COLL later.

(counts-of [{:a [{:b 1} {:b 2}], :c 2}
            {:a {:b 3}, :c 4}] :a)
  -> [2 :atom]

For each x in COLL, return:

• (count (k x)) if (k x) is sequential
• :atom if (k x) is otherwise non-nil
• :nil if x has key k but the value is nil
• nil if x is nil.

Flatten COLL by K.

(counts-flatten [{:a [{:b 1} {:b 2}], :c 2}
                 {:a {:b 3}, :c 4}] :a)
  -> [{:b 1} {:b 2} {:b 3}]

Unflatten COLL by K using COUNTS from counts-of.

(counts-unflatten [{:b 2} {:b 4} {:b 6}] :a [2 :atom])
  -> [{:a [{:b 2} {:b 4}]}
      {:a {:b 6}}]

Apply F to values of COLL flattened by K, then return unflattened/updated results.

(counts-apply [{:a [{:b 1} {:b 2}], :c 2}
               {:a {:b 3}, :c 4}]
  :a #(update-in % [:b] (partial * 2)))

  -> [{:a [{:b 2} {:b 4}], :c 2}
      {:a {:b 3}, :c 4}]

Util Fns

Is this a valid argument to hydrate?

Append to a keyword.

 (kw-append :user "_id") -> :user_id

Return a map of hydration keywords to functions that should be used to hydrate them, e.g.

 {:fields #'my-project.models.table/fields
  :tables #'my-project.models.database/tables
  ...}

These functions are ones that are marked METADATA-KEY, e.g. ^:hydrate or ^:batched-hydrate.

Automagic Batched Hydration (via :model-keys)

Return map of hydration-key -> model e.g. :user -> User.

This is built pulling the hydration-keys set from all of our entities.

Get a map of hydration keys to corresponding models.

Can we do a batched hydration of RESULTS with key K?

Hydrate keyword DEST-KEY across all RESULTS by aggregating corresponding source keys (DEST-KEY_id), doing a single db/select, and mapping corresponding objects to DEST-KEY.

Function-Based Batched Hydration (fns marked ^:batched-hydrate)

Map of keys to functions marked ^:batched-hydrate for them.

Function-Based Simple Hydration (fns marked ^:hydrate)

Fetch a map of keys to functions marked ^:hydrate for them.

Hydrate keyword K in results by calling corresponding functions when applicable.

Resetting Hydration keys (for REPL usage)

Clear out the cached hydration keys. Useful when doing interactive development and defining new hydration functions.

Primary Hydration Fns

Hydrate a nested hydration form (vector) by recursively calling hydrate.

Hydrate a single keyword.

Hydrate a single hydration form.

Hydrate many hydration forms across a sequence of RESULTS by recursively calling hydrate-1.

Public Interface

                         hydrate <-------------+
                           |                   |
                       hydrate-many            |
                           | (for each form)   |
                       hydrate-1               | (recursively)
                           |                   |
                keyword? --+-- vector?         |
                   |             |             |
              hydrate-kw    hydrate-vector ----+
                   |
          can-automagically-batched-hydrate?
                         |
        true ------------+----------------- false
         |                                    |
automagically-batched-hydrate    can-fn-based-batched-hydrate?
                                             |
                           true -------------+------------- false
                            |                                 |
                 fn-based-batched-hydrate              simple-hydrate

Hydrate a single object or sequence of objects.

Automagic Batched Hydration (via hydration-keys)

hydrate attempts to do a batched hydration where possible. If the key being hydrated is defined as one of some model's hydration-keys, hydrate will do a batched db/select if a corresponding key ending with _id is found in the objects being batch hydrated.

(hydrate [{:user_id 100}, {:user_id 101}] :user)

Since :user is a hydration key for User, a single db/select will used to fetch Users:

(db/select User :id [:in #{100 101}])

The corresponding Users are then added under the key :user.

Function-Based Batched Hydration (via functions marked ^:batched-hydrate)

If the key can't be hydrated auto-magically with the appropriate :hydration-keys, hydrate will look for a function tagged with :batched-hydrate in its metadata, and use that instead. If a matching function is found, it is called with a collection of objects, e.g.

(defn with-fields
  "Efficiently add `Fields` to a collection of TABLES."
  {:batched-hydrate :fields}
  [tables]
  ...)

(let [tables (get-some-tables)]
  (hydrate tables :fields))     ; uses with-fields

By default, the function will be used to hydrate keys that match its name; as in the example above, you can specify a different key to hydrate for in the metadata instead.

Simple Hydration (via functions marked ^:hydrate)

If the key is not eligible for batched hydration, hydrate will look for a function or method tagged with :hydrate in its metadata, and use that instead; if a matching function is found, it is called on the object being hydrated and the result is assoced:

(defn ^:hydrate dashboard [{:keys [dashboard_id]}]
  (Dashboard dashboard_id))

(let [dc (DashboardCard ...)]
  (hydrate dc :dashboard))    ; roughly equivalent to (assoc dc :dashboard (dashboard dc))

As with :batched-hydrate functions, by default, the function will be used to hydrate keys that match its name; you can specify a different key to hydrate instead as the metadata value of :hydrate:

(defn ^{:hydrate :pk_field} pk-field-id [obj] ...) ; hydrate :pk_field with pk-field-id

Keep in mind that you can only define a single function/method to hydrate each key; move functions into the IModel interface as needed.

Hydrating Multiple Keys

You can hydrate several keys at one time:

(hydrate {...} :a :b)
  -> {:a 1, :b 2}

Nested Hydration

You can do recursive hydration by listing keys inside a vector:

(hydrate {...} [:a :b])
  -> {:a {:b 1}}

The first key in a vector will be hydrated normally, and any subsequent keys will be hydrated inside the corresponding values for that key.

(hydrate {...}
         [:a [:b :c] :e])
  -> {:a {:b {:c 1} :e 2}}

The defmodel macro, used to define Toucan models, and the IModel protocol and default implementations, which implement Toucan model functionality.

Configuration

Root Model Namespace

The root model namespace is the parent namespace of all Toucan models. Toucan knows how to automatically load namespaces where models live, which is handy for avoiding circular references; to facilitate this, Toucan models need to live in places that match an expected pattern.

For example, a model named UserFollow must live in the namespace <root-model-namespace>.user-follow.

The root model namespace defaults to models; in the example above, UserFollow would live in models.user-follow.

This is almost certainly not what you want; set your own value by calling set-root-namespace!:

(models/set-root-namespace! 'my-project.models)

After setting the default model root namespace as in the example above, Toucan will look for UserFollow in my-project.models.user-follow.

Set the root namespace where all models are expected to live.

 (set-root-namespace! 'my-project.models)

In this example, Toucan would look for a model named UserFollow in the namespace my-project.models.user-follow.

Fetch the parent namespace for all Toucan models.

Types

Model types are a easy way to define functions that should be used to transform values of a certain column when they come out from or go into the database.

For example, suppose you had a Venue model, and wanted the value of its :category column to automatically be converted to a Keyword when it comes out of the DB, and back into a string when put in. You could let Toucan know to take care of this by defining the model as follows:

(defmodel Venue :my_venue_table)

(extend (class Venue)
  models/IModel
  (merge models/IModelDefaults
         {:types (constantly {:category :keyword})}))

Whenever you fetch a Venue, Toucan will automatically apply the appropriate :out function for values of :category:

(db/select-one Venue) ; -> {:id 1, :category :bar, ...}

In the other direction, insert! and update! will automatically do the reverse, and call the appropriate :in function.

:keyword is the only Toucan type defined by default, but adding more is simple.

You can add a new type by calling add-type!:

;; add a :json type (using Cheshire) will serialize objects as JSON
;; going into the DB, and deserialize JSON coming out from the DB
(add-type! :json
  :in  json/generate-string
  :out #(json/parse-string % keyword))

In the example above, values of any columns marked as :json would be serialized as JSON before going into the DB, and deserialized from JSON when coming out of the DB.

Add a new type mapping for type named by key K. Supply mappings for the functions that should prepare value when it goes :in to the database, and for when it comes :out.

 ;; add a :json type (using Cheshire) will serialize objects as JSON
 ;; going into the DB, and deserialize JSON coming out from the DB
 (add-type! :json
   :in  json/generate-string
   :out #(json/parse-string % keyword))

Properties

Model properties are a powerful way to extend the functionality of Toucan models.

With properties, you can define custom functions that can modify the values (or even add new ones) of an object before it is saved (via the insert! and update! family of functions) or when it comes out of the DB (via the select family of functions).

Properties are global, which lets you define a single set of functions that can be applied to multiple models that have the same property, without having to define repetitive code in model methods such as pre-insert!.

For example, suppose you have several models with :created-at and :updated-at columns. Whenever a new instance of these models is inserted, you want to set :created-at and :updated-at to be the current time; whenever an instance is updated, you want to update :updated-at.

You could handle this behavior by defining custom implementations for pre-insert and pre-update for each of these models, but that gets repetitive quickly. Instead, you can simplfy this behavior by defining a new property that can be shared by multiple models:

(add-property! :timestamped?
  :insert (fn [obj _]
            (let [now (java.sql.Timestamp. (System/currentTimeMillis))]
              (assoc obj :created-at now, :updated-at now)))
  :update (fn [obj _]
            (assoc obj :updated-at (java.sql.Timestamp. (System/currentTimeMillis)))))

(defmodel Venue :my_venue_table)

(extend (class Venue)
  models/IModel
  (merge models/IModelDefaults
         {:properties (constantly {:timestamped? true})}))

In this example, before a Venue is inserted, a new value for :created-at and :updated-at will be added; before one is updated, a new value for :updated-at will be added.

Property functions can be defined for any combination of :insert, :update, and :select. If these functions are defined, they will be called as such:

(fn [object property-value])

where property-value is the value for the key in question returned by the model's implementation of properties.

In the example above, :timestamped? is set to true for Venue; since we're not interested in the value in the example above we simply ignore it (by binding it to _).

You can set the value to any truthy value you'd like, which can be used to customize behavior for different models, making properties even more flexible.

Define a new model property and set the functions used to implement its functionality. See documentation for more details.

 (add-property! :timestamped?
   :insert (fn [obj _]
             (let [now (java.sql.Timestamp. (System/currentTimeMillis))]
               (assoc obj :created-at now, :updated-at now)))
   :update (fn [obj _]
             (assoc obj :updated-at (java.sql.Timestamp. (System/currentTimeMillis)))))

IModel Interface

The IModel protocol defines the various methods that are used to provide custom behavior for various models.

This protocol contains the various methods model classes can optionally implement. All methods have a default implementation provided by IModelDefaults; new models created with the defmodel macro automatically implement this protocol using those default implementations. To override one or more implementations, use extend and merge your custom implementations with IModelDefaults:

 (defmodel MyModel)

 (extend (class MyModel)
   IModel
   (merge IModelDefaults {...}))

INTERNAL IMPL

Apply the appropriate type-fns for OBJ.

Used by internal functions like do-post-select.

these functions call (map-> model ...) twice to make sure functions like pre-insert/post-select didn't do something that accidentally removed the typing

Don't call this directly! Apply functions like pre-insert before inserting an object into the DB.

Don't call this directly! Apply internal functions like pre-update before updating an object in the DB.

Don't call this directly! Apply internal functions like post-select when an object is retrieved from the DB.

Default implementations for IModel methods.

Fetch an object with a specific ID or all objects of type ENTITY from the DB.

 (invoke-model Database)           -> seq of all databases
 (invoke-model Database 1)         -> Database w/ ID 1
 (invoke-model Database :id 1 ...) -> A single Database matching some key-value args

Is model a valid toucan model?

Check whether OBJ is an model (e.g. Database) or an object from the DB; if an model, call invoked-model; otherwise call get.

We use the same record type (e.g., DatabaseInstance) for both the "model" (e.g., Database) and objects fetched from the DB ("instances"). Model definitions have the key ::model assoced so we can differentiate. Invoking an instance calls get so you can do things like (db :name) as if it were a regular map.

DEFMODEL MACRO

Macro helper, generates

   (~'invoke [this#]
    (invoke-model-or-instance this#))
   (~'invoke [this# id#]
    (invoke-model-or-instance this# id#))
   (~'invoke [this# arg1# arg2#]
    (invoke-model-or-instance this# arg1# arg2#))
   ,,,

Make a symbol fully qualified by resolving it as a var in the current namespace.

 conj        ;;=> clojure.core/conj
 str/join    ;;=> clojure.string/join
 foo.bar/baz ;;=> foo.bar/baz

Take in forms as passed to defrecord or extend-type (protocol or interface name followed by method definitions), and return a map suitable for use with extend.

(IFn (invoke [this] this)) ;;=> {IFn {:invoke (fn [this] this)}}

Define a new "model". Models encapsulate information and behaviors related to a specific table in the application DB, and have their own unique record type.

defmodel defines a backing record type following the format <model>Instance. For example, the class associated with User is <root-namespace>.user/UserInstance. (The root namespace defaults to models but can be configured via set-root-namespace!)

This class is used for both the titular model (e.g. User) and for objects that are fetched from the DB. This means they can share the IModel protocol and simplifies the interface somewhat; functions like types work on either the model or instances fetched from the DB.

 (defmodel User :user_table)  ; creates class `UserInstance` and DB model `User`

 (db/select User, ...)  ; use with `toucan.db` functions. All results are instances of `UserInstance`

The record type automatically extends IModel with IModelDefaults, but you can override specific methods, or implement other protocols, by passing them to defmodel, the same way you would with defrecord.

 (defmodel User :user_table
   IModel
   (hydration-keys [_]
     [:user])
   (properties [_]
     {:timestamped true})
   (pre-insert [user]
     user))

This is equivalent to:

 (extend (class User)             ; it's somewhat more readable to write `(class User)` instead of `UserInstance`
   IModel (merge IModelDefaults
                  {...}))

Finally, the model itself is invokable. Calling with no args returns all values of that object; calling with a single arg can be used to fetch a specific instance by its integer ID.

 (Database)                       ; return a seq of *all* Databases (as instances of `DatabaseInstance`)
 (Database 1)                     ; return Database 1

Utility functions for writing tests with Toucan models.

TEMP OBJECTS

For your convenience Toucan makes testing easy with Temporary Objects. A temporary object is created and made available to some body of code, and then wiped from that database via a finally statement (i.e., whether the body completes successfully or not). This makes it easy to write tests that do not change your test database when they are ran.

Here's an example of a unit test using a temporary object created via with-temp:

;; Make sure newly created users aren't admins
(expect false
  (with-temp User [user {:first-name "Cam", :last-name "Saul"}]
    (is-admin? user)))

In this example, a new instance of User is created (via the normal insert! pathway), and bound to user; the body of with-temp (the test-something fncall) is executed. Immediately after, the user is removed from the Database, but the entire statement returns the results of the body (hopefully false).

Often a Model will require that many fields be NOT NULL, and specifying all of them in every test can get tedious. In the example above, we don't care about the :first-name or :last-name of the user. We can provide default values for temporary objects by implementing the WithTempDefaults protocol:

(defn- random-name
  "Generate a random name of 10 uppercase characters"
  []
  (apply str (map char (repeatedly 10 #(rand-nth (range (int \A) (inc (int \Z))))))))

(extend-protocol WithTempDefaults
  (class User)
  (with-temp-defaults [_] {:first-name (random-name), :last-name (random-name)}))

Now whenever we use with-temp to create a temporary User, a random :first-name and :last-name will be provided.

(with-temp User [user]
  user)
;; -> {:first-name "RIQGVIDTZN", :last-name "GMYROFEZYO", ...}

You can still override any of the defaults, however:

(with-temp User [user {:first-name "Cam"}]
  user)
;; -> {:first-name "Cam", :last-name "OVTAAJBVOF"}

Finally, Toucan provides a couple more advanced versions of with-temp. The first, with-temp*, can be used to create multiple objects at once:

(with-temp* [User         [user]
             Conversation [convo {:user_id (:id user)}]]
  ...)

Each successive object can reference the temp object before it; the form is equivalent to writing multiple with-temp forms.

The last helper macro is available if you use the expectations unit test framework:

;; Make sure our get-id function works on users
(expect-with-temp [User [user {:first-name "Cam"}]]
  (:id user)
  (get-id user))

This macro makes the temporary object available to both the "expected" and "actual" parts of the test. (PRs for similar macros for other unit test frameworks are welcome!)

Protocol defining the with-temp-defaults method, which provides default values for new temporary objects.

default impl

Internal implementation of with-temp (don't call this directly).

Create a temporary instance of ENTITY bound to BINDING-FORM, execute BODY, then deletes it via delete!.

Our unit tests rely a heavily on the test data and make some assumptions about the DB staying in the same clean state. This allows us to write very concise tests. Generally this means tests should "clean up after themselves" and leave things the way they found them.

with-temp should be preferrable going forward over creating random objects without deleting them afterward.

(with-temp EmailReport [report {:creator_id (user->id :rasta)
                                :name       (random-name)}]
  ...)

Like with-temp but establishes multiple temporary objects at the same time.

 (with-temp* [Database [{database-id :id}]
              Table    [table {:db_id database-id}]]
   ...)

EXPECTATIONS HELPER MACROS

Combines expect with a with-temp* form. The temporary objects established by with-temp* are available to both EXPECTED and ACTUAL.

 (expect-with-temp [Database [{database-id :id}]]
    database-id
    (get-most-recent-database-id))

Utility functions used by other Toucan modules.

Return keyword K as a string, including its namespace, if any (unlike name).

 (keyword->qualified-name :type/FK) -> "type/FK"

Locale-agnostic version of clojure.string/lower-case. clojure.string/lower-case uses the default locale in conversions, turning ID into ıd, in the Turkish locale. This function always uses the Locale/US locale.