Python python-pouchdb

pouchdb is a javascript implementation of couchdb.
It was designed so that webapps could store info offline, then synchronize when online.
It is compatible with couchdb, and supports it's replication feature.

The module python-pouchdb is an entirely contained pouchdb. You do not need pouchdb or couchdb installed, and you do not need to run it in a browser (well not technically).

python-couchdb uses the real pouchdb behind the scenes using Qt's QtWebkit module in the background. Anything that would require a web browser is handled by that. This means that python-pouchdb is entirely cli-driven and entirely independent of a standalone javascript pouchdb server. awesome.

WARNING:

python-pouchdb depends on QtWebKit, which means that to use it you must be running an X11 server. You can work around this using a framebuffer.

ex:

xvfb-run ipython
>>> import pouchdb
>>> env = pouchdb.setup()
>>> env.PouchDb('test_database')
...

WARNING:

python-pouchdb does not support syncing with https addresses 

Documentation

homepage	https://python-pouchdb.marten-de-vries.nl/
official docs	https://pythonhosted.org/Python-PouchDB/pouchdb.html
bugtracker	https://bugs.launchpad.net/python-pouchdb

Usage

import pouchdb

env = pouchdb.setup( storageDir='/home/will/dev/pouchdb' )    # create/connect to a database/directory
env = pouchdb.setup( baseUrl='127.0.0.1:5984' )               # connect to existing couchdb
db  = env.PouchDB('testdb')                                   # creates/opens database within `env`
db.put({'_id': 'will', 'age': 30})                            # creates/modifies document named `_id`
db.put({                                                      # designs/views are created in the same way
	'_id': '_design/query_group',
	'views': {
		'first_query': {
			'map' : 'function(doc) {   emit( doc.id, doc.shoesize )  }'
			},
		'second_query': {
			'map' : 'function(doc) {   emit( doc.shoesize, doc.id )  }'
			}
		}
	})

db['testdb']                                                 ## prints all documents in database

# python pouchdb accepts raw json strings,
# or dictionaries in assignments.

Concepts

Core Concepts

In order to get a better understanding of pouchdb's concepts, you might want to refer to my documentation on Couchdb.

GQL

Google Query Language. An alternative way of querying your pouchdb/couchdb database. Basically, it brings a limited subset of SQL to the couchdb family databases.

In order to use this, you must install the GQL pouchdb plugin.

Components

environment

The environment is your connection to the database.

import pouchdb
env = pouchdb.setup(storageDir='/home/will/dev/pouchdb')
env.all_dbs()  # print all databases

Database

databases contain documents, and views.

## Database
db.all_docs()                       ## retrieve all documents in database
db.destroy()                        ## delete database
db.info()                           ## {'db_name':..., 'doc_count':..., 'update_seq':...}

Documents

Documents are what couchdb uses instead of tables. The central idea is that all information about a single thing is contained in one (JSON) document. Not all documents must share the same fields.

# Create/Update Documents

# retrieve document with ID
db.get(docid)

# document with at least {_id:, _rev:}
db.remove({'_id':'my_document', '_rev':'1-ljalksjfklj21...')  

# create a new document OR update an existing document.
# If the document exists, you must specify it's _rev.
db.put(dict, id=None, rev=None)
                                                                
# create a new document (pouchdb assigns ID)
db.post(dict)

Queries

# Queries
db.query('design/view',              startkey=..., endkey=... })  # after filtering results with a view, use query-parameters to filter your results.
db.query({'map':..., 'reduce': ...}, startkey=..., endkey=...})   # on-the-fly query (rather than precomputing on-change, computed at runtime. debug only)
db.gql()                                                          # Google Query Language (limited subset of SQL)

# result
{
    "total_rows": 3,
    "offset": 0,
    "rows": [
        {   "key": "2009/01/15 15:52:20",
            "id": "hello-world",
            "value": ["example", "a simple example"]
        },
			... 
    ]
}

Replication

# perform two-way sync
db.sync( 'http://127.0.0.1:5984/testdb' )
db.replicate_from( 'http://127.0.0.1:5984/testdb' )
db.replicate_to(   'http://127.0.0.1:5984/testdb' )

Working with Couchdb

env = pouchdb.setup( storageDir='test' )  ## you create ONE env for both your couchdb and pouchdb
db  = env.PouchDB( 'testdb' )             ## db object for local database
db.sync( 'http://127.0.0.1:5984/testdb' ) ## sync local 'testdb' with remote couchdb's 'testdb'