luciano/next-jdbc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add component usage to Getting Started

Browse source
This commit is contained in:
Sean Corfield 2020-04-29 19:28:59 -07:00
parent 8068afab5c
commit 900703a32a
2 changed files with 19 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
CHANGELOG.md
View file

@ -4,7 +4,7 @@ Only accretive/fixative changes will be made from now on.
The following changes have been made on **master** since the 1.0.424 release: The following changes have been made on **master** since the 1.0.424 release:
* Experimental support for Stuart Sierra's Component library, via `next.jdbc.connection/component`. Documentation coming soon! * Support for Stuart Sierra's Component library, via `next.jdbc.connection/component`. See updated **Getting Started** guide for usage.
* Add MySQL-specific result set streaming tip. * Add MySQL-specific result set streaming tip.
* Investigate possible solutions for #106 (mutable transaction thread safety) -- experimental `locking` on `Connection` object. * Investigate possible solutions for #106 (mutable transaction thread safety) -- experimental `locking` on `Connection` object.

40
doc/getting-started.md
View file

@ -324,35 +324,31 @@ You will generally want to create the connection pooled datasource at the start
You only need the type hints on `ds` if you plan to call methods on it via Java interop, such as `.close` (or using `with-open` to auto-close it) and you want to avoid reflection. You only need the type hints on `ds` if you plan to call methods on it via Java interop, such as `.close` (or using `with-open` to auto-close it) and you want to avoid reflection.
If you are using [Component](https://github.com/stuartsierra/component), a connection pooled datasource is a good candidate since it has a `start`/`stop` lifecycle: If you are using [Component](https://github.com/stuartsierra/component), a connection pooled datasource is a good candidate since it has a `start`/`stop` lifecycle. `next.jdbc` has support for Component built-in, via the `next.jdbc.connection/component` function which creates a Component-compatible entity which you can `start` and then invoke as a function with no arguments to obtain the `DataSource` within.
```clojure ```clojure
(ns ... (ns my.data.program
(:require [com.stuartsierra.component :as component] (:require [com.stuartsierra.component :as component]
...)) [next.jdbc :as jdbc]
[next.jdbc.connection :as connection])
(:import (com.zaxxer.hikari HikariDataSource)))
(defrecord Database [db-spec ^HikariDataSource datasource] ;; HikariCP requires :username instead of :user in the db-spec:
component/Lifecycle (def ^:private db-spec {:dbtype "..." :dbname "..." :username "..." :password "..."})
(start [this]
(if datasource
this ; already started
(assoc this :datasource (connection/->pool HikariDataSource db-spec))))
(stop [this]
(if datasource
(do
(.close datasource)
(assoc this :datasource nil))
this))) ; already stopped
(defn -main [& args] (defn -main [& args]
(let [db (component/start (map->Database {:db-spec db-spec}))] ;; connection/component takes the same arguments as connection/->pool:
(let [ds (component/start (connection/component HikariDataSource db-spec))]
(try (try
(jdbc/execute! (:datasource db) ...) ;; "invoke" the data source component to get the javax.sql.DataSource:
(jdbc/execute! (:datasource db) ...) (jdbc/execute! (ds) ...)
(do-other-stuff db args) (jdbc/execute! (ds) ...)
(into [] (map :column) (jdbc/plan (:datasource db) ...))) ;; can pass the data source component around other code:
(catch Throwable t) (do-other-stuff ds args)
(component/stop db))) (into [] (map :column) (jdbc/plan (ds) ...))
(finally
;; stopping the component will close the connection pool:
(component/stop ds)))))
``` ```
## Working with Additional Data Types ## Working with Additional Data Types