Connector to 'CouchDB'

Provides an interface to the 'NoSQL' database 'CouchDB' (<>). Methods are provided for managing databases within 'CouchDB', including creating/deleting/updating/transferring, and managing documents within databases. One can connect with a local 'CouchDB' instance, or a remote 'CouchDB' databases such as 'Cloudant'. Documents can be inserted directly from vectors, lists, data.frames, and 'JSON'. Targeted at 'CouchDB' v2 or greater.

  _ _ _ _ _ _ _ _ _ _ _
 /|                   |\
/ |_ _ _ _ _ _ _ _ _ _| \
\ /                    \/
 \ ___________________ /

Build Status rstudio mirror downloads cran version

An easy interface to CouchDB from R

Note: Check out R4couchdb, another R package to interact with CouchDB.

sofa is built targeting CouchDB v2 or greater.

CouchDB Info

Connect to CouchDB

This may be starting it on your terminal/shell


Or opening the CouchDB app on your machine, or running it in Docker. Whatever it is, start it up.

You can interact with your CouchDB databases as well in your browser. Navigate to http://localhost:5984/_utils

Install sofa



Development version from GitHub



Cushions? What? Since it's couch we gotta use cushions somehow. cushions are a connection class containing all connection info to a CouchDB instance. See ?Cushion for help.

As an example, connecting to a Cloudant couch:

z <- Cushion$new(
  host = "",
  transport = 'https',
  port = NULL,
  user = 'foobar',
  pwd = 'things'

Break down of parameters:

  • host: the base url, without the transport (http/https)
  • path: context path that is appended to the end of the url
  • transport: http or https
  • port: The port to connect to. Default: 5984. For Cloudant, have to set to NULL
  • user: User name for the service.
  • pwd: Password for the service, if any.
  • headers: headers to pass in all requests

If you call Cushion$new() with no arguments you get a cushion set up for local use on your machine, with all defaults used.

x <- Cushion$new()

Ping the server

#> $couchdb
#> [1] "Welcome"
#> $version
#> [1] "2.1.1"
#> $features
#> $features[[1]]
#> [1] "scheduler"
#> $vendor
#> $vendor$name
#> [1] "The Apache Software Foundation"

Nice, it's working.

Create a new database, and list available databases

#> $ok
#> [1] TRUE
db_create(x, dbname = 'sofadb')
#> $ok
#> [1] TRUE

see if its there now

#> [1] "cats"       "flights"    "sofadb"     "testing123"

Create documents

Write a document WITH a name (uses PUT)

doc1 <- '{"name":"sofa","beer":"IPA"}'
doc_create(x, doc1, dbname = "sofadb", docid = "a_beer")
#> $ok
#> [1] TRUE
#> $id
#> [1] "a_beer"
#> $rev
#> [1] "1-a48c98c945bcc05d482bc6f938c89882"

Write a json document WITHOUT a name (uses POST)

doc2 <- '{"name":"sofa","icecream":"rocky road"}'
doc_create(x, doc2, dbname = "sofadb")
#> $ok
#> [1] TRUE
#> $id
#> [1] "901e4bf214fb50db456d3ef8ec0516c9"
#> $rev
#> [1] "1-fd0da7fcb8d3afbfc5757d065c92362c"

More docs

See the vignettes for more documentation.


  • Please report any issues or bugs.
  • License: MIT
  • Get citation information for sofa in R doing citation(package = 'sofa')
  • Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.



sofa 0.3.0


  • Gains new functions db_index, db_index_create, and db_index_delete for getting an index, creating one, and deleting one
  • Gains function design_search_many to do many queries at once in a POST request (#56)
  • design_search reworked to allow user to do a GET request or POST request depending on if they use params parameter or body parameter - many parameters removed in the function definition, and are now to be passed to params or body (#56)
  • db_alldocs gains new parameter disk to optionally write data to disk instead of into the R session - should help when data is very large (if disk is used fxn returns a file path) (#64)


  • fix minor issues in vignette, and updated for working with CouchDB v2 and greater (#53) (#54) (#47)
  • replace httr with crul for HTTP requests (#52)
  • design_copy removed temporarily (#20) (#60)
  • new issue and pull request template


  • Fix to docs for design_search (#57) thanks @michellymenezes
  • Fix to db_query to make a single field passed to fields parameter work (#63) thanks @gtumuluri
  • Fix error in doc_attach_get (#58) thanks @gtumuluri

sofa 0.2.0


  • released to CRAN

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.4.0 by Scott Chamberlain, a year ago (devel) (docs)

Report a bug at

Browse source code at

Authors: Scott Chamberlain [aut, cre] , rOpenSci [fnd] (

Documentation:   PDF Manual  

MIT + file LICENSE license

Imports crul, jsonlite, R6, mime

Suggests testthat, knitr, rmarkdown

Suggested by nodbi.

See at CRAN