CouchQL 0.1
An SQL-like interface to CouchDB
================================

Copyright 2009 Andrew Wilkinson <andrewjwilkinson@gmail.com>

Contents
========

1. What is CouchQL?
2. How do I use CouchQL?
3. What SQL syntax does CouchQL support?
4. I found a bug! What now?
5. How can I get CouchQL?
6. Credits.
7. License

1. What is CouchQL?
===================

CouchQL is provides an SQL-like interface for querying a CouchDB database.
CouchDB (http://couchdb.apache.org/) is a distributed, fault-tolerant and
schema-free document-oriented database accessible via a RESTful HTTP/JSON API.
It's built in query language is a javascript-based map/reduce system. This is
extremly flexible and very powerful, but is often overly complicated. CouchQL is
designed to provide a simpler interface using a language that most developers
are familiar with, SQL. What CouchQL loses in flexibility and power it gains in
simplicity.

2. How do I use CouchQL?
========================

CouchQL extends the Python bindings to CouchDB
(http://code.google.com/p/couchdb-python/) using the standard Python API for
accessing an RDBMS.

>>> import couchdb
>>> import couchql # Activate couchql
>>> server = couchdb.server("http://localhost:5984")
>>> db = server["db-name"]
>>> c = db.cursor()
>>> c.execute("SELECT * FROM _ WHERE x > %s", (5, ))
>>> for doc in c.fetchall():
>>>     # process doc

3. What SQL syntax does CouchQL support?
========================================

Currently CouchQL only supports a few small subset of SQL. This will grow over
coming releases, but for now you can only run SELECT queries. You are also
limited to selecting all columns (*), which in CouchQL means return the complete
document. The database must be an underscore, which represents the database
which the cursor was created from. In future releases you will be able to
specify a database name here. The where clause can contain any number of exprs
as long as they are joined by ANDs.

4. I found a bug! What now?
===========================

Please report any bugs to our Google Code bug tracker
(http://code.google.com/p/couchql/issues/list). Please try and include as much
information as possible about the bug, including the SQL used, the documents
you're processing and what the expected result is. If you get a traceback please
include that, or if the result is wrong let us what what you did get.

CouchQL is developed using test-driven development so if you can turn your bug
into a test case which fails that would be very much appreciated. Patches to fix
bugs are also very welcome, but please try to include at lease one test case in
the patch.

5. How can I get CouchQL?
=========================

CouchQL can be checked out of subversion by following the instructions on Google
Code (http://code.google.com/p/couchql/source/checkout). Release tarballs can be
downloaded from http://code.google.com/p/couchql/downloads/list.

The simplest method to install CouchQL is to use easy_install to download it
automatically from the Python Package Index
(http://pypi.python.org/pypi/couchql/). Simply type "easy_install couchql" to
get started.

6. Credits
==========

CouchQL was created by Andrew Wilkinson <andrewjwilkinson@gmail.com>

CouchQL wouldn't exist without the excellent work that Damien Katz
(http://damienkatz.net/) and the rest of the CouchDB developers have put into
creating an seriously excellent next-generation database.

7. License
==========

CouchQL is released under the Apache 2.0 license. See the file LICENSE for more
details.
