README - Uniscala Couch
A couchdb driver for Scala, but not an object mapper.
About
Uniscala Couch is a low/mid-level driver for CouchDB written in the Scala
programming language. It doesn't attempt to map CouchDB JSON documents to and
from your domain/model Scala objects - it's not an object mapper.
Uniscala Couch require Scala 2.10 futures, so it's not compatible with Scala
2.9.x. It also depends on Netty 4, and Uniscala JSON. The latter is an
efficient JSON library built with document-oriented databases in mind, which
features a hierarchy of type-safe, immutable JSON data types implemented
as a complete set of case classes.
Feedback
We've created this driver because we needed it, and placed it here in the hope
others can make use of it. If you end up using it for a project, or you find
bugs or errors in the documentation, please let us know. If it ends up
being instrumental to an important project, please consider a donation
to Sustainable Software Pty Ltd.
Features
- (almost) full CouchDB HTTP API coverage - see 'CouchDB HTTP API Coverage' below
- asynchronous I/O using Netty 4 and Scala futures
- streaming view results (including view-like results such as all_docs
operations)
- streamed uploads for attachments
- backed by a JSON library with immutable, Scala collection-compliant JSON types
- object mapping is not forced upon the user
Sessions, OAuth and URL rewriting parts of the CouchDB API have not been
implemented at this time. The new_edits modes of operations are also not
currently available. Please let us know if there is a great demand for
any of these.
Stability
The driver is tested and stable, but yet to be used in any non-trivial
projects. It's possible that the API may change considerably once we start
using it in earnest.
License
Copyright 2012 Sustainable Software Pty Ltd.
Licensed under the Apache License, Version 2.0 (the "License").
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Contributors
Uniscala Couch is managed and developed by Sam Stainsby at
Sustainable Software Pty Ltd
Usage
See the Usage document.
API documentation
See the scaladoc.
Including the library in your project
Uniscala Couch releases are available in the mainstream repositories:
<dependency>
<groupId>net.uniscala</groupId>
<artifactId>uniscala-couch_2.10</artifactId>
<version>0.4</version>
</dependency>
in your pom.xml
, or using SBT, in your build.sbt
:
"net.uniscala" %% "uniscala-couch" % "0.4"
Building
Uniscala Couch is built in a fairly standard way using SBT.
History
- version 0.4
- upgrade from Netty version 4.0.0.Alpha8 to Netty 4.0.0.Beta3
- upgrade to Uniscala JSON 0.4
CouchDB HTTP API Coverage
Below, the API sections correspond to those in the Couch API specification -
refer to Complete HTTP API Reference on the CouchDB website.
Server-level miscellaneous methods
GET /
- implemented & tested
GET /favicon.ico
- implemented & tested
GET /_all_dbs
- implemented & tested
GET /_active_tasks
- implemented & tested
POST /_replicate
- implemented - not tested (legacy - use
_replicator
instead)
* /_replicator
- implemented (nothing special
implemented; use ordinary database API methods)
GET /_uuids
- implemented & tested
POST /_restart
- implemented & tested
GET /_stats
- implemented & tested
GET /_log
- implemented & tested
GET /_utils/file
- implemented & tested
Server configuration
GET /_config
- implemented & tested
GET /_config/section
- implemented & tested
GET /_config/section/key
- implemented & tested
PUT /_config/section/key
- implemented & tested
DELETE /_config/section/key
- implemented & tested
Authentication
NOTE: this section of the API doesn't refer to HTTP basic
authentication that may be needed to authorise other API methods. Basic
authentication is achieved by doing something like this:
val client = new CouchClient(credentialsOption = Some(BasicCredentials("admin", "changeme")))
GET /_session
- not implemented (not useful?)
POST /_session
- not implemented (not useful?)
DELETE /_session
- not implemented (not useful?)
GET /_oauth/access_token
- not implemented
GET /_oauth/authorize
- not implemented
POST /_oauth/authorize
- not implemented
* /_oauth/request_token
- not implemented
* /_users
- implemented - (nothing special
implemented; use ordinary database API methods)
Database methods
GET /db
- implemented & tested
PUT /db
- implemented & tested
DELETE /db
- implemented & tested
GET /db/_changes
- implemented & tested
POST /db/_compact
- implemented & tested
POST /db/_compact/design-doc
- implemented & tested
POST /db/_view_cleanup
- implemented & tested
POST /db/_temp_view
- implemented & tested
POST /db/_ensure_full_commit
- implemented & tested
POST /db/_bulk_docs
- implemented & tested (support for new_edits mode
is not implemented)
POST /db/_purge
- implemented - not tested
GET /db/_all_docs
- implemented & tested
POST /db/_all_docs
- implemented & tested
POST /db/_missing_revs
- implemented - not tested
POST /db/_revs_diff
- implemented - not tested
GET /db/_security
- implemented (nothing special
implemented; use ordinary database API methods)
PUT /db/_security
- implemented (nothing special
implemented; use ordinary database API methods)
GET /db/_revs_limit
- implemented & tested
PUT /db/_revs_limit
- implemented & tested
Database document methods
POST /db
- implemented & tested
GET /db/doc
- implemented & tested
HEAD /db/doc
- implemented & tested
PUT /db/doc
- implemented & tested
DELETE /db/doc
- implemented & tested
COPY /db/doc
- implemented & tested
GET /db/doc/attachment
- implemented & tested
PUT /db/doc/attachment
- implemented & tested
DELETE /db/doc/attachment
- implemented & tested
Special non-replicating documents
GET /db/_local/local-doc
- implemented & tested
PUT /db/_local/local-doc
- implemented & tested
DELETE /db/_local/local-doc
- implemented & tested
COPY /db/_local/local-doc
- implemented & tested
Special design documents
GET /db/_design/design-doc
- implemented & tested
PUT /db/_design/design-doc
- implemented & tested
DELETE /db/_design/design-doc
- implemented & tested
COPY /db/_design/design-doc
- implemented & tested
GET /db/_design/design-doc/attachment
- implemented & tested
PUT /db/_design/design-doc/attachment
- implemented & tested
DELETE /db/_design/design-doc/attachment
- implemented & tested
Special design document handlers
GET /db/_design/design-doc/_info
- implemented & tested
GET /db/_design/design-doc/_view/view-name
- implemented & tested
POST /db/_design/design-doc/_view/view-name
- implemented & tested
? /db/_design/design-doc/_show/show-name
- implemented & tested
? /db/_design/design-doc/_show/show-name/doc
- implemented & tested
GET /db/_design/design-doc/_list/list-name/view-name
-
implemented & tested
POST /db/_design/design-doc/_list/list-name/view-name
-
implemented & tested
GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name
-
implemented & tested
POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name
-
implemented & tested
? /db/_design/design-doc/_update/update-name
- implemented & tested
? /db/_design/design-doc/_update/update-name/doc
- implemented & tested
* /db/_design/design-doc/_rewrite/rewrite-name/anything
- not implemented