playbook.db — com.mschaef/playbook 0.2.4

An application's database: an embedded sql-file database, opened from configuration, with its query cache, scheduled-job support and backups.

This namespace needs sql-file, which playbook doesn't bring with it (it's a provided dependency): an application that uses it lists com.mschaef/sql-file among its own dependencies. Applications without a database don't load this namespace and don't need sql-file.

Configuration:

[:db :subname] - The database name; defaults to [:app :name]. The db.subname system property takes precedence over both. [:db :pool-size] - The most connections the pool keeps open (default 4, sql-file's default). Size it for the web server's request threads plus the scheduled jobs that can run at once. [:db :connection-timeout-sec] - How long to wait for a free connection before failing (default 30, HikariCP's default). A short timeout makes requests fail quickly, rather than queue, while the database is blocked (e.g. by the backup's CHECKPOINT DEFRAG). [:db :enable-query-cache] - Whether the query cache is on. [:db :backup-path] - Directory for scheduled backups (the :db-backup job); with none, there are no backups.

backup-jobs clj

(backup-jobs {:keys [archive]})

The scheduled jobs for backing up the database: a :db-backup job, if [:db :backup-path] is configured, and otherwise none. Each backup checkpoints and defragments the database, then writes an online backup to a new file under the backup path. Options:

:archive - Optional function of the backup file (a java.io.File), called after each backup: for example, to copy it elsewhere.

call-with-database clj

(call-with-database {:keys [schemas]} f)

Open the application's database (as a connection pool), installing the given schemas, and call f with it available through pool. Options:

:schemas - sql-file schema list, e.g. [["myapp" 0]]. Schema scripts are found under sql/ on the classpath.

call-with-query-cache clj

(call-with-query-cache f)

Call f with the application's query cache bound, when it's enabled. When it isn't, just call f.

clear-cache! clj

(clear-cache!)

Clear the application's query cache.

invalidate-cache! clj

(invalidate-cache! cache-name)

Clear what's cached under cache-name (see sql-file.query-cache) in the application's query cache.

job-wrapper clj

(job-wrapper job-fn)

Wrap a job function to run with a connection to the application's database and with its query cache bound: the :job-wrapper for playbook.service. Scheduled jobs run on the scheduler's threads, outside anything a request would bind, so without this a job's queries would have no connection and its cache invalidation would never reach the shared cache.

pool clj

(pool)

The application's database connection pool. Fails if no database is open (see with-database).

query-cache-enabled? clj

(query-cache-enabled?)

Whether the query cache is on: the [:db :enable-query-cache] configuration value.

query-middleware clj

The middleware for application queries, for yesql's defqueries: the current connection, the query cache (between the connection and the query mode, so cached results are already shaped), query mode, and logging.

with-database clj macro

(with-database options & body)

Run body with the application's database open; see call-with-database.