README.md

Quickstart example

Chillax is Quicklisp-installable, allowing for super-quick, painless
installation of Chillax and all its dependencies.

Make sure CouchDB is installed, and currently running. This example assumes that the server is
running in localhost, using the default 5984 port. Yason's alist encoder/decoder is used below to
make replies readable (by default, it uses hash tables as JSON objects, instead of alists, and
strings as keys).

Introduction

Chillax is a CouchDB abstraction layer for Common Lisp. It is not an
ORM or similar library, although it may be used to build such things.

Chillax also includes a CouchDB view server, which can be used to write CouchDB views in full,
native Common Lisp.

Chillax includes several systems:

chillax.asd - This is a 'DWIM' system. It includes the Yason server for parsing/encoding JSON
data. It also defines a single #:chillax package that includes the symbols in both
#:chillax.core and #:chillax.yason. If you don't know what you want, this is probably what
you want.

chillax.view-server.asd - The Chillax view server. This only depends on chillax.utils.

About this document

This README is not meant to document how to use CouchDB itself, or how to successfully design
applications with it. If you're new to CouchDB, it is recommended that you follow a guide (which can
be done while using Chillax).

Core API

Chillax is a thin, lispy layer on top of CouchDB's RESTful API. Its main purpose is to provide Lisp
functions to all of CouchDB's API calls, while translating certain things into Lisp data and
concepts. For example, Chillax takes care of checking CouchDB's HTTP response codes for sanity. When
error codes are returned, Chillax will signal Lisp corresponding Lisp conditions.

Additionally, Chillax is able to use any representation for CouchDB documents, provided the core
Chillax protocols are implemented for that representation, i.e, you can use hash tables, alists, or
instances of classes as your 'documents', and Chillax will automatically serialize/deserialize JSON
communications with CouchDB according to the protocol's implementation.

Note that, since Chillax really is just a thin layer, it abstracts very little beyond the
above. Most Chillax functions will simply return the de-JSON-ified CouchDB responses, and leave you
to digging through the response objects for the data you need.

Server API

Chillax's Server API provides access to server-level functionality. Server objects not only give
access to these database-independent features, but also act as mediators for all data that goes
through Chillax. Chillax's server objects are in charge, for example, of translating CouchDB's JSON
responses to and from whatever data format the user has chosen to use Lisp-side.

Server objects are created through appropriate protocol implementations. See STANDARD-SERVER, and
YASON-SERVER below for the included implementations. Additional or alternate functionality for
serialization can easily be implemented through Chillax's server protocol.

[function]server-uri server

Returns a string representation of the URL SERVER represents.

[function]all-dbs server

Requests a list of all existing databases from SERVER.

[function]config-info server

Requests the current configuration from SERVER.

[function]replicate server target &key create-target-p continuousp

Replicates the database in SOURCE to TARGET. SOURCE and TARGET can both be either database names
in the local server, or full URLs to local or remote databases. If CREATE-TARGET-P is true, the
target database will automatically be created if it does not exist. If CONTINUOUSP is true,
CouchDB will continue propagating any changes in SOURCE to TARGET.

[function]stats server

Requests general statistics from SERVER.

[function]active-tasks server

Lists all the currently active tasks on SERVER.

[function]get-uuids server &key (number 10)

Returns a list of NUMBER unique IDs requested from SERVER. The UUIDs generated by the server are
reasonably unique, but are not checked against existing UUIDs, so conflicts may still happen.

Database API

Connecting to a database in Chillax involves creating a database object with one of 3 constructors,
all of which accept a server object (see Server API above), and the name of the database.

Confirms that a particular CouchDB database exists. If so, returns a new database object that can
be used to perform operations on it. Will signal a DB-NOT-FOUND error if the database does not
already exist.

[function]db-create server name

Creates a new CouchDB database. Returns a database object that can be used to operate on it. Will
signal a DB-ALREADY-EXISTS error if there is already a database with the same NAME in SERVER.

[function]ensure-db server name

Either connects to an existing database, or creates a new one. Returns two values: If a new
database was created, (DB-OBJECT T) is returned. Otherwise, (DB-OBJECT NIL).

[function]db-info db

Fetches info about a given database from the CouchDB server.

[function]db-delete db

Deletes a CouchDB database.

[function]db-compact db

Triggers a database compaction.

[function]db-changes db

Returns the changes feed for DB

[function]db-uri db

Returns a string representing the full URI for DB.

Document API

All document arguments to these functions must be Lisp objects that the database's server is able to
encode to JSON. These functions will likewise return Lisp objects that represent the parsed JSON
responses from CouchDB. Exact representations will depend on the server being used.

Finds a CouchDB document in DB, named by ID. PARAMS should be an alist containing the parameters
for the HTTP GET request. If ATTACHMENTSP is TRUE, the document's attachments will be included in
their entirety in their base64-encoded version. It is not recommended you use this unless you really
know what you're doing. If ERRORP is NIL, GET-DOCUMENT will simply return NIL on 404.

[function]get-document-revision db doc-id &key (errorp t)

Quickly fetches the latest revision for DOC-ID. If ERRORP is NIL, this can be used to quickly test
the existence of a document.

[function]put-document db id doc &key batch-ok-p

Puts a document into DB, using ID. DOC must be Lisp data that DB's server is able to convert to
JSON.

[function]post-document db doc

POSTs a document into DB. CouchDB will automatically assign a UUID if the document does not
already exist. Note that using this function is discouraged in the CouchDB documentation, since it
may result in duplicate documents because of proxies and other network intermediaries. If what you
need is to create a new document with a generated id, consider using GET-UUIDS with PUT-DOCUMENT.

Uses _all_docs to quickly fetch the given DOC-IDs in a single request. Note that this function
will NOT signal a DOCUMENT-NOT-FOUND error when one or more DOC-IDs are not found. Instead, the
results will be returned, and it's the user's responsibility to deal with any missing docs.

[function]bulk-post-documents documents &key all-or-nothing-p

Allows you to update or submit multiple documents at the same time, using CouchDB's _bulk_docs
API. In order to delete a document through this API, the document must have a _document attribute
with JSON 'true' as its value (note that what gets translated into 'true' depends on the server).

DOCUMENTS must be a sequence or sequence-like (depending on what DATA->JSON will do to it).

If ALL-OR-NOTHING-P is true, the entire submission will fail if a single one fails."

Standalone Attachment API

CouchDB has an API for uploading and downloading standalone attachments.

String or sequence of octets - DATA will be sent as-is directly to the server (using EXTERNAL-FORMAT-OUT for strings).

Stream - The stream will be read until EOF is reached.

Pathname - The file the pathname denotes will be opened and its data uploaded.

Function designator - The corresponding function will be called with one argument, the stream to the server, to which it should send data.

If the document already exists, REV is required. This function can be used on non-existent
documents. If so, REV is not needed, and a document will be created automatically, and the
attachment associated with it.

The CONTENT-TYPE should be a string specifying the content type for DATA. (default: "application/octet-stream")

[function]get-attachment db doc-id attachment-name

Returns 3 values:

STREAM - An open flexi-stream that can be READ. In order to read straight binary data, you must first fetch the underlying stream with FLEXI-STREAMS:FLEXI-STREAM-STREAM.

MUST-CLOSE-P - A boolean. If TRUE, the user must CLOSE this stream themselves once reading is done.

CONTENT-LENGTH - Declared content length for the incoming data.

[function]delete-attachment db doc-id attachment-name doc-revision

Deletes an attachment from a document. DOC-REVISION must be the latest revision for the document.

[function]copy-attachment db doc-id attachment-name output-stream

Copies data from the named attachment to OUTPUT-STREAM. Returns the number of bytes copied.

Design Document API

Chillax currently includes a basic wrapper for Design Document-related operations. This API is
likely to expand in the future as good ideas reveal themselves. Design documents will still need to
be created through the regular document API.

Queries a temporary view. These views are meant to be for testing and development purposes, and
should not be used in actual code.

Core Protocol

You can use the core protocol to customize behavior of Chillax. Writing your own implementation for
this protocol is relatively simple and painless, and it allows you to do things such as use your own
custom JSON encoder/decoder, if Yason doesn't fit your needs. Classes that implement the protocols,
and their behavior, is documented here, as well.

JSOWN-SERVER is a subclass of STANDARD-SERVER, and the same initargs apply.

[function]call-with-key-container

This function is part of the chillax.jsown package.

Calls FUNCTION, which require zero arguments, in a context where CONTAINER will be used for
jsown:parse-with-container.

[macro]with-key-container

This macro is part of the chillax.jsown package.

Convenience macro for call-with-key-container.

Database Protocol

[generic function]database-server database

Returns the server object with which DATABASE is associated.

[generic function]database-name database

Returns the URL-encoded name of the database, a string. Note that CouchDB accepts certain
characters in database names -only- if they are URL-encoded (such as #\/). It is up to individual
implementations of DATABASE-NAME to implement this encoding.

Included protocol implementation

[standard class]standard-database

Minimal, class-based implementation of the database protocol.

View Server

The Chillax View Server allows you to write views in full-fledged Common Lisp. In order to use the
server, you must create a binary using code loaded by chillax.view-server.asd, and make
chillax-server::run-server the toplevel function.

Once you put the binary in a place visible to the CouchDB process, add the following to
/etc/couchdb/local.ini (or wherever your local.ini is located):

You can load anything you want into the view server image before dumping it, customize which package
it executes views in, etc. The source code is fairly short and easy to digest. It's designed to be
customizable for whatever your needs are.

Status

Currently, the view server only provides basic features. A future release of Chillax will bring it
back in sync with CouchDB's current line protocol.

Yason Problem

Note that, at least on some systems, versions of Yason prior
to commit
00b9a5c06b7c4113a48518a1f136637efb4458b9
will not work (in this commit, #\Return was added to the list of whitespace characters
recognized). Using these versions instead of 0.1 is recommended anyway for performance reasons.

History

The original author and current maintainer/developer of Chillax is
Kat Marchán; Ian McEwen
subsequently worked on CLOS bindings, since the original version was written for
Sheeple. Chillax has since been mostly rewritten (again) to
use a simple protocol-based extension API, allowing users to easily extend or alter Chillax's
behavior, with minimal code.