Namespace: joker.bolt

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms

Summary

Provides a small string-oriented API for the Bolt embedded key/value database.

Example:

user=> (def db (joker.bolt/open "bolt.db" 0600))
#'user/db
user=> (joker.bolt/create-bucket db "users")
nil
user=> (def id (joker.bolt/next-sequence db "users"))
#'user/id
user=> id
1
user=> (joker.bolt/put db "users" (str id) (joker.json/write-string {:id id :name "Joe Black"}))
nil
user=> (joker.json/read-string (joker.bolt/get db "users" (str id)))
{"id" 1, "name" "Joe Black"}

Index

• by-prefix
• close
• count-by-prefix
• create-bucket
• create-bucket-if-not-exists
• delete
• delete-bucket
• get
• next-sequence
• open
• put
• update
• view

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

(None.)

Variables

(None.)

Functions, Macros, and Special Forms

• by-prefix

  Function v1.0

  (by-prefix context bucket prefix)(by-prefix ^BoltContext context ^String bucket ^String prefix)
  (by-prefix context bucket prefix opts)(by-prefix ^BoltContext context ^String bucket ^String prefix ^Map opts)
  

  Returns key/value pairs from bucket whose keys start with prefix.
  
  context may be a BoltDB, which uses a new read transaction, or an active
  BoltTx. Results are returned as a vector of [key value] vectors in Bolt key
  order. Passing the empty string returns all key/value pairs in the bucket.
  
  opts may contain:
  - limit - maximum number of key/value pairs to return; must be non-negative
  
  Throws Error when bucket does not exist, limit is invalid, or the transaction
  fails.

  show types

• close

  Function v1.0

  (close db)(close ^BoltDB db)
  

  Closes db and releases its database resources.
  
  Blocks until open transactions finish, then releases the file lock. Throws
  Error if closing fails.

  show types

• count-by-prefix

  Function v1.0

  (count-by-prefix context bucket prefix)(count-by-prefix ^BoltContext context ^String bucket ^String prefix)
  

  Returns the number of keys in bucket that start with prefix.
  
  context may be a BoltDB, which uses a new read transaction, or an active
  BoltTx. Passing the empty string counts all keys in the bucket. Throws Error
  when bucket does not exist or the transaction fails.

  show types

• create-bucket

  Function v1.0

  (create-bucket context name)(create-bucket ^BoltContext context ^String name)
  

  Creates bucket name and returns nil.
  
  context may be a BoltDB, which uses a new write transaction, or a BoltTx from
  update. Throws Error if the bucket already exists, if name is blank or too
  long, if context is read-only, or if the transaction fails.

  show types

• create-bucket-if-not-exists

  Function v1.0

  (create-bucket-if-not-exists context name)(create-bucket-if-not-exists ^BoltContext context ^String name)
  

  Creates bucket name when needed and returns nil.
  
  context may be a BoltDB, which uses a new write transaction, or a BoltTx from
  update. Does nothing when the bucket already exists. Throws Error if name is
  blank or too long, if context is read-only, or if the transaction fails.

  show types

• delete

  Function v1.0

  (delete context bucket key)(delete ^BoltContext context ^String bucket ^String key)
  

  Removes key from bucket and returns nil.
  
  context may be a BoltDB, which uses a new write transaction, or a BoltTx from
  update. Missing keys are ignored. Throws Error when bucket does not exist,
  context is read-only, or the transaction fails.

  show types

• delete-bucket

  Function v1.0

  (delete-bucket context name)(delete-bucket ^BoltContext context ^String name)
  

  Deletes bucket name and returns nil.
  
  context may be a BoltDB, which uses a new write transaction, or a BoltTx from
  update. Throws Error when the bucket does not exist, context is read-only, or
  the transaction fails.

  show types

• get

  Function v1.0

  (get context bucket key)(get ^BoltContext context ^String bucket ^String key)
  

  Returns the string value stored at key in bucket.
  
  context may be a BoltDB, which uses a new read transaction, or an active
  BoltTx. Returns nil when key does not exist. Throws Error when bucket does not
  exist or the transaction fails.

  show types

• next-sequence

  Function v1.0

  (next-sequence context bucket)(next-sequence ^BoltContext context ^String bucket)
  

  Returns the next auto-incrementing integer for bucket.
  
  context may be a BoltDB, which uses a new write transaction, or a BoltTx from
  update. Each call advances the bucket sequence counter. Throws Error when the
  bucket does not exist, context is read-only, or the transaction fails.

  show types

• open

  Function v1.0

  (open filename mode)(open ^String filename ^Int mode)
  

  Opens the database file at filename and returns a BoltDB handle.
  
  If the file does not exist, it is created with mode before the process umask
  is applied. mode is normally written as an octal literal such as 0600.
  Throws Error when the database cannot be opened.
  
  The underlying database uses an exclusive file lock; because this wrapper uses
  Bolt's default options, open may wait indefinitely for another process to
  release the same database file.
  
  Example:
  (def db (joker.bolt/open "app.db" 0600))

  show types

• put

  Function v1.0

  (put context bucket key value)(put ^BoltContext context ^String bucket ^String key ^String value)
  

  Stores value at key in bucket and returns nil.
  
  context may be a BoltDB, which uses a new write transaction, or a BoltTx from
  update. Keys and values are strings stored as raw bytes. Replaces any previous
  value for key. Throws Error when bucket does not exist, context is read-only,
  key is blank or too large, value is too large, or the transaction fails.

  show types

• update

  Function v1.0

  (update db f)(update ^BoltDB db ^Callable f)
  

  Executes f in a managed read/write transaction and returns the result of f.
  
  f is called with a BoltTx that is valid only for the duration of the call.
  Database operations in f must use that transaction rather than db. A normal
  return commits the transaction, including when f returns nil or false. If f
  throws, the entire transaction is rolled back and the exception is rethrown.
  Throws Error if the transaction cannot be opened or committed.
  
  Example:
  (joker.bolt/update db
  (fn [tx]
  (joker.bolt/put tx "users" "1" "Joe")
  (joker.bolt/put tx "users" "2" "Jane")
  :saved))

  show types

• view

  Function v1.0

  (view db f)(view ^BoltDB db ^Callable f)
  

  Executes f in a managed read-only transaction and returns the result of f.
  
  f is called with a BoltTx that is valid only for the duration of the call.
  Database operations in f must use that transaction rather than db. The
  transaction is rolled back when f returns, or when f throws. Throws Error if
  the transaction cannot be opened or closed, and rethrows exceptions from f.
  
  Example:
  (joker.bolt/view db
  (fn [tx] (joker.bolt/get tx "users" "1")))

  show types