Quickstart¶
This page gives a good introduction in how to get started with py-couchdb. This assumes you already have it installed. If you do not, head over to the Installation section.
Connect to a server¶
Connect to a couchdb server is very simple. Begin by importing pycouchdb
module and instance
a server class:
>>> import pycouchdb
>>> server = pycouchdb.Server()
Authentication¶
By default, py-couchdb connects to a http://localhost:5984/
but if your couchdb requieres
authentication, you can pass http://username:password@localhost:5984/
to server constructor:
>>> server = pycouchdb.Server("http://username:password@localhost:5984/")
py-couchdb have two methods for authentication: with session or basic auth. By default, “session” method is used but if you like, can specify the method on create a server instance:
>>> server = pycouchdb.Server("http://username:password@localhost:5984/",
authmethod="basic")
Create, obtain and delete a database¶
CouchDB can contains multiple databases. For access to one, this is a simple example:
>>> db = server.database("foo")
>>> db
<pycouchdb.client.Database object at 0x7fd4ae835dd0>
Can create one new db:
>>> server.create("foo2")
<pycouchdb.client.Database object at 0x7f9c46059310>
And can remove a database:
>>> server.delete("foo2")
If you intent remove not existent database, NotFound exception is raised. For more information see Exceptions API.
>>> server.delete("foo")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "./pycouchdb/client.py", line 42, in delete
raise NotFound("database {0} not found".format(name))
pycouchdb.exceptions.NotFound: database foo not found
Create, obtain and delete a document¶
The simplest way for get a document is using its id
.
>>> db = server.database("foo")
>>> doc = db.get("b1536a237d8d14f3bfde54b41b036d8a")
>>> doc
{'_rev': '1-d62e11770282e4fcc5f6311dae6c80ee', 'name': 'Bar',
'_id': 'b1536a237d8d14f3bfde54b41b036d8a'}
You can create an own document:
>>> doc = db.save({"name": "FOO"})
>>> doc
{'_rev': '1-6a1be826ddbd67649df8aa1e0bf12da1',
'_id': 'ef9e608db6434dd39ab3dc4cf35d22b7', 'name': 'FOO'}
Delete a document:
>>> db.delete("ef9e608db6434dd39ab3dc4cf35d22b7")
>>> "ef9e608db6434dd39ab3dc4cf35d22b7" not in db
True
Querying a database¶
With couchDB you can make two types of queries: temporary or view. This is a simple way to make a temporary query:
>>> map_func = "function(doc) { emit(doc.name, 1); }"
>>> db.temporary_query(map_func)
<generator object _query at 0x7f65bd292870>
>>> list(db.temporary_query(map_func))
[{'value': 1, 'id': '8b588fa0a3b74a299c6d958467994b9a', 'key': 'Fooo'}]
And this is a way to make a query using predefined views:
>>> _doc = {
... "_id": "_design/testing",
... "views": {
... "names": {
... "map": "function(doc) { emit(doc.name, 1); }",
... "reduce": "function(k, v) { return sum(v); }",
... }
... }
...}
>>> doc = db.save(_doc)
>>> list(db.query("testing/names", group='true'))
[{'value': 1, 'key': 'Fooo'}]
In order to make query with Python see Views on how to configure CouchDB. And this is a way to make a query using predefined views with Python:
>>> _doc = {
... "_id": "_design/testing",
... "language": "python3",
... "views": {
... "names": {
... "map": "def fun(doc): yield doc.name, 1",
... "reduce": "def fun(k, v): return sum(v)",
... }
... }
...}
>>> doc = db.save(_doc)
>>> list(db.query("testing/names", group='true', language='python3'))
[{'value': 1, 'key': 'Fooo'}]
Subscribe to a changes stream feed¶
CouchDB exposes a fantastic stream API for push change notifications, and with pycouchdb you can subscribe to these changes in a very simple way:
>>> def feed_reader(message, db):
... print(message)
...
>>> db.changes_feed(feed_reader)
changes_feed
blocks until a stream is closed or FeedReaderExited
is raised inside of reader function.
Also, you can make reader as class. This have some advantage, because it exposes often useful close callback.
Example:
>>> from pycouchdb.feedreader import BaseFeedReader
>>> from pycouchdb.exceptions import FeedReaderExited
>>>
>>> class MyReader(BaseFeedReader):
... def on_message(self, message):
... # self.db is a current Database instance
... # process message
... raise FeedReaderExited()
...
... def on_close(self):
... # This is executed after a exception
... # is raised on on_message method
... print("Feed reader end")
...
>>> db.changes_feed(MyReader())