CouchDB - CouchDB/GeoCouch

(GDAL/OGR >= 1.9.0)

This driver can connect to the a CouchDB service, potentially enabled with the GeoCouch spatial extension.

GDAL/OGR must be built with Curl support in order to the CouchDB driver to be compiled.

The driver supports read and write operations.

CouchDB vs OGR concepts

A CouchDB database is considered as a OGR layer. A CouchDB document is considered as a OGR feature.

OGR handles preferably CouchDB documents following the GeoJSON specification.

Dataset name syntax

The syntax to open a CouchDB datasource is :
where points to the root of a CouchDB repository and, optionally, layername is the name of a CouchDB database.

It is also possible to directly open a view :

The include_docs=true might be needed depending on the value returned by the emit() call in the map() function.


Some operations, in particular write operations, require authentication. The authentication can be passed with the COUCHDB_USERPWD environment variable set to user:password or directly in the URL.


The driver will forward any spatial filter set with SetSpatialFilter() to the server when GeoCouch extension is available. It also makes the same for (very simple) attribute filters set with SetAttributeFilter(). When server-side filtering fails, it will default back to client-side filtering.

By default, the driver will try the following spatial filter function "_design/ogr_spatial/_spatial/spatial", which is the valid spatial filter function for layers created by OGR. If that filter function does not exist, but another one exists, you can specify it with the COUCHDB_SPATIAL_FILTER configuration option.

Note that the first time an attribute request is issued, it might require write permissions in the database to create a new index view.


Features are retrieved from the server by chunks of 500 by default. This number can be altered with the COUCHDB_PAGE_SIZE configuration option.

Write support

Table creation and deletion is possible.

Write support is only enabled when the datasource is opened in update mode.

When inserting a new feature with CreateFeature(), and if the command is successful, OGR will fetch the returned _id and _rev and use them.

Write support and OGR transactions

The CreateFeature()/SetFeature() operations are by default issued to the server synchronously with the OGR API call. This however can cause performance penalties when issuing a lot of commands due to many client/server exchanges.

It is possible to surround the CreateFeature()/SetFeature() operations between OGRLayer::StartTransaction() and OGRLayer::CommitTransaction(). The operations will be stored into memory and only executed at the time CommitTransaction() is called.

Layer creation options

The following layer creation options are supported:


  • Listing the tables of a CouchDB repository:
    ogrinfo -ro "couchdb:"

  • Creating and populating a table from a shapefile:
    ogr2ogr -f couchdb "couchdb:" shapefile.shp

    See Also