Skip to content
Reflex Reflex Reflex Docs

Couch

library

Talks to the CouchDB server that is configured in the project settings (URL, user name and password under Project settings > CouchDB in Reflex). The four functions map to the HTTP verbs, and every path is relative to that URL, so Couch.get("mydb/doc-1") requests URL/mydb/doc-1. Things to know: every function returns a table with status, json and table. Non-2xx statuses such as 404 or 409 (revision conflict) are returned, not raised; only connection failures raise an error. When a user name or password is configured, every request carries Basic authentication (a missing user name or password counts as empty); there is no way to use other credentials from Lua. Updating or deleting a document needs its current revision (_rev in the body, or ?rev= for delete). A table passed as body is encoded as JSON.

  • Kind Library, a global in every script
  • Category APIs & Data
  • Functions 4

Functions

  • get CouchResponse Sends a GET request to CouchDB: reads a document, a view, _all_docs, database info and so on.
  • put CouchResponse Sends a PUT request to CouchDB: creates a document under a chosen id, or updates it when the body contains the current _rev (otherwise CouchDB answers 409).
  • post CouchResponse Sends a POST request to CouchDB: creates a document with a generated id (POST to the database), or runs a query such as mydb/_find (Mango) or mydb/_bulk_docs.
  • delete CouchResponse Sends a DELETE request to CouchDB: deletes a document (the current revision is required as ?rev=REV in the path) or a whole database (Couch.delete("mydb")).

get()

Section titled “get()”
Couch.get(query: string)→CouchResponseCouch.get(query: string, table: table)→CouchResponse

Sends a GET request to CouchDB: reads a document, a view, _all_docs, database info and so on. The second argument is optional and, when given, is sent as a JSON body (rarely needed for GET). Only the characters [ ] space and " are escaped in the path, so URL-encode other special characters yourself.

Parameters

query string
Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10
table table optional
Request body: a table that is sent as JSON (application/json)

Returns

CouchResponse The response of a CouchDB request made with Couch.
Fields of CouchResponse
status number
HTTP status code, for example 200, 201 or 404
json string
the response body as pretty-printed JSON text
table table
the response body decoded into a Lua table (the same data as json)
All table shapes

Example

Read a document and list documents

local doc = Couch.get("mydb/order-1001")
Assert.equals(200, doc.status)
print(doc.table.customer, doc.table.total)


local all = Couch.get("mydb/_all_docs?include_docs=true&limit=10")
for _, row in ipairs(all.table.rows) do
    print(row.id)
end

put()

Section titled “put()”
Couch.put(query: string)→CouchResponseCouch.put(query: string, table: table)→CouchResponse

Sends a PUT request to CouchDB: creates a document under a chosen id, or updates it when the body contains the current _rev (otherwise CouchDB answers 409). Also used to create a database (Couch.put("newdb")). On success the response table has the new revision as table.rev.

Parameters

query string
Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10
table table optional
Request body: a table that is sent as JSON (application/json)

Returns

CouchResponse The response of a CouchDB request made with Couch.
Fields of CouchResponse
status number
HTTP status code, for example 200, 201 or 404
json string
the response body as pretty-printed JSON text
table table
the response body decoded into a Lua table (the same data as json)
All table shapes

Example 

local created = Couch.put("mydb/order-1001", { type = "order", customer = "ACME", total = 42.5 })
Assert.equals(201, created.status)


local current = Couch.get("mydb/order-1001")
local updated = Couch.put("mydb/order-1001", {
    _rev = current.table._rev,
    type = "order",
    customer = "ACME",
    total = 45,
})
Assert.equals(201, updated.status)

post()

Section titled “post()”
Couch.post(query: string)→CouchResponseCouch.post(query: string, table: table)→CouchResponse

Sends a POST request to CouchDB: creates a document with a generated id (POST to the database), or runs a query such as mydb/_find (Mango) or mydb/_bulk_docs. The body table is sent as JSON.

Parameters

query string
Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10
table table optional
Request body: a table that is sent as JSON (application/json)

Returns

CouchResponse The response of a CouchDB request made with Couch.
Fields of CouchResponse
status number
HTTP status code, for example 200, 201 or 404
json string
the response body as pretty-printed JSON text
table table
the response body decoded into a Lua table (the same data as json)
All table shapes

Example 

local found = Couch.post("mydb/_find", { selector = { type = "order", total = { ["$gt"] = 40 } }, limit = 20 })
Assert.equals(200, found.status)
for _, doc in ipairs(found.table.docs) do
    print(doc._id, doc.total)
end

delete()

Section titled “delete()”
Couch.delete(query: string)→CouchResponseCouch.delete(query: string, table: table)→CouchResponse

Sends a DELETE request to CouchDB: deletes a document (the current revision is required as ?rev=REV in the path) or a whole database (Couch.delete("mydb")). The status is 200, or 409 when the revision is outdated.

Parameters

query string
Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10
table table optional
Request body: a table that is sent as JSON (application/json)

Returns

CouchResponse The response of a CouchDB request made with Couch.
Fields of CouchResponse
status number
HTTP status code, for example 200, 201 or 404
json string
the response body as pretty-printed JSON text
table table
the response body decoded into a Lua table (the same data as json)
All table shapes

Example 

local doc = Couch.get("mydb/order-1001")
local deleted = Couch.delete("mydb/order-1001?rev=" .. doc.table._rev)
Assert.equals(200, deleted.status)