Introduction to clj-bedquilt

clj-bedquilt is the clojure client library for BedquiltDB.

Installation

Add the following to :dependencies in project.clj:

[bedquilt "2.0.0"]

Prerequisites

• Clojure 1.7
• A PostgreSQL server with the bedquilt extension installed (http://bedquiltdb.readthedocs.org).

Further BedquiltDB Documentation

See the BedquiltDB Guide.

Basic usage

Require the bedquilt.core namespace:

(ns example.core
  (:require [bedquilt.core :as bq]))

Make a db spec, with which to connect to the PostgreSQL instance with bedquilt installed:

(def spec
  (bq/make-db-spec {:subname  "//localhost/bedquilt_test"
                    :user     "user"
                    :password "password"}))

This spec is really just a JDBC connection spec, the same as would be used with clojure.java.jdbc. The make-db-spec function just ensures the spec has the appropriate PostgreSQL-specific bits set.

Get a list of collections on the server:

(bq/list-collections spec)
;; => '("users" "documents")

Create a collection:

(bq/create-collection spec "things")
;; => true

Delete a collection:

(bq/delete-collection spec "things")
;; => true

Check if a collection exists:

(bq/collection-exists? spec "nope")
;; => false

Add constraints to a collection:

(bq/add-constraints spec
  "users"
  {"email" {"$required" true
            "$notnull" true
            "$type" "string"}
   "name"  {"$required" true}})
;; => true

Remove constraints to a collection:

(bq/remove-constraints spec
  "users"
  {"name"  {"$required" true}})
;; => true

Find documents in a collection:

(bq/find spec "users" {:age 22})
;; => '({:_id "123", :age 22, :name "Jim", ...},  {...}, ...)


(bq/find spec "users" {:address {:city "Glasgow"}}
                      {:sort [{:age 1}], :skip 2, :limit 4})

(bq/find-one spec "users" {:address {:city "Edinburgh"}})
;; => {:_id "242", ...}

(bq/find-one spec "users" {:address {:$in ["Edinburgh" "Glasgow"]}}
                          {:sort [{:$updated -1}]})
;; => {:_id "222", ...}

(bq/find-one-by-id spec "users" "462")
;; => {:_id "462", ...}

Get a count of documents in a collection:

(bq/count spec "things")
;; => 42

(bq/count spec "users" {:age 45})
;; => 2040

Get a list of distinct values under a given key path in a collection:

(bq/distinct spec "users" "address.city")
;; => '("Edinburgh" "London" ...)'

Insert a document in a collection:

(bq/insert spec "users" {:name "Jill"})
;; => "68e65f4a55246b0e5ce5d075"
;; (returns the _id field of the inserted document)

(bq/save spec "users" {:_id "..." :name "Mike"})
;; => "10a75a73d607a04044023010"

Update an existing document:

(let [doc (bq/find-one-by-id spec "users" "123")
      new-doc (assoc doc :age 24)]
  (bq/save spec "users" new-doc))
;; => "123"
;; (save either overwrites the document with the same _id, or inserts a new document)

Even better, do the same with a single connection:

(bq/with-connection [conn spec]
  (let [doc (bq/find-one-by-id conn "users" "123")
        new-doc (assoc doc :age 24)]
    (bq/save conn "users" new-doc)))

Remove documents from a collection:

(bq/remove spec "users" {:age 22})
;; => 45
;; (count of documents removed)

(bq/remove-one spec "users" {:address {:city "Edinburgh"}})
;; => 1

(bq/remove-one-by-id spec "users" "462")
;; => 1

(bq/remove-many-by-ids spec "users" ["one", "four", "nine"])
;; => 3

Connection Pooling

Because the spec parameter to the various bedquilt.core functions is just a jdbc connection spec, you can use the usual jdbc connection pooling methods with BedquiltDB. (Note, this use case is not currently covered by automated tests.)

See JDBC Connection Pooling on clojure-doc.org.