9.3.1. /db
¶
-
HEAD
/{db}
¶ Returns the HTTP Headers containing a minimal amount of information about the specified database. Since the response body is empty, using the HEAD method is a lightweight way to check if the database exists already or not.
Parameters: - db – Database name
Status Codes: - 200 OK – Database exists
- 404 Not Found – Requested database not found
Request:
HEAD /test HTTP/1.1 Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Mon, 12 Aug 2013 01:27:41 GMT Server: CouchDB (Erlang/OTP)
-
GET
/{db}
¶ Gets information about the specified database.
Parameters: - db – Database name
Request Headers: - Accept –
- application/json
- text/plain
Response Headers: - Content-Type –
- application/json
- text/plain; charset=utf-8
Response JSON Object: - committed_update_seq (number) – The number of committed update.
- compact_running (boolean) – Set to
true
if the database compaction routine is operating on this database. - db_name (string) – The name of the database.
- disk_format_version (number) – The version of the physical format used for the data when it is stored on disk.
- data_size (number) – Actual data size in bytes of the database data.
- disk_size (number) – Size in bytes of the data as stored on the disk. Views indexes are not included in the calculation.
- doc_count (number) – A count of the documents in the specified database.
- doc_del_count (number) – Number of deleted documents
- instance_start_time (string) – Timestamp of when the database was opened, expressed in microseconds since the epoch.
- purge_seq (number) – The number of purge operations on the database.
- update_seq (number) – The current number of updates to the database.
Status Codes: - 200 OK – Request completed successfully
- 404 Not Found – Requested database not found
Request:
GET /receipts HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 258 Content-Type: application/json Date: Mon, 12 Aug 2013 01:38:57 GMT Server: CouchDB (Erlang/OTP) { "committed_update_seq": 292786, "compact_running": false, "data_size": 65031503, "db_name": "receipts", "disk_format_version": 6, "disk_size": 137433211, "doc_count": 6146, "doc_del_count": 64637, "instance_start_time": "1376269325408900", "purge_seq": 0, "update_seq": 292786 }
-
PUT
/{db}
¶ Creates a new database. The database name
{db}
must be composed by following next rules:- Name must begin with a lowercase letter (
a-z
) - Lowercase characters (
a-z
) - Digits (
0-9
) - Any of the characters
_
,$
,(
,)
,+
,-
, and/
.
If you’re familiar with Regular Expressions, the rules above could be written as
^[a-z][a-z0-9_$()+/-]*$
.Parameters: - db – Database name
Request Headers: - Accept –
- application/json
- text/plain
Response Headers: - Content-Type –
- application/json
- text/plain; charset=utf-8
- Location – Database URI location
Response JSON Object: - ok (boolean) – Operation status. Available in case of success
- error (string) – Error type. Available if response code is
4xx
- reason (string) – Error description. Available if response code is
4xx
Status Codes: - 201 Created – Database created successfully
- 400 Bad Request – Invalid database name
- 401 Unauthorized – CouchDB Server Administrator privileges required
- 412 Precondition Failed – Database already exists
Request:
PUT /db HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 201 Created Cache-Control: must-revalidate Content-Length: 12 Content-Type: application/json Date: Mon, 12 Aug 2013 08:01:45 GMT Location: http://localhost:5984/db Server: CouchDB (Erlang/OTP) { "ok": true }
If we repeat the same request to CouchDB, it will response with
412
since the database already exists:Request:
PUT /db HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 412 Precondition Failed Cache-Control: must-revalidate Content-Length: 95 Content-Type: application/json Date: Mon, 12 Aug 2013 08:01:16 GMT Server: CouchDB (Erlang/OTP) { "error": "file_exists", "reason": "The database could not be created, the file already exists." }
If an invalid database name is supplied, CouchDB returns response with
400
:Request:
PUT /_db HTTP/1.1 Accept: application/json Host: localhost:5984
Request:
HTTP/1.1 400 Bad Request Cache-Control: must-revalidate Content-Length: 194 Content-Type: application/json Date: Mon, 12 Aug 2013 08:02:10 GMT Server: CouchDB (Erlang/OTP) { "error": "illegal_database_name", "reason": "Name: '_db'. Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter." }
- Name must begin with a lowercase letter (
-
DELETE
/{db}
¶ Deletes the specified database, and all the documents and attachments contained within it.
Note
To avoid deleting a database, CouchDB will respond with the HTTP status code 400 when the request URL includes a ?rev= parameter. This suggests that one wants to delete a document but forgot to add the document id to the URL.
Parameters: - db – Database name
Request Headers: - Accept –
- application/json
- text/plain
Response Headers: - Content-Type –
- application/json
- text/plain; charset=utf-8
Response JSON Object: - ok (boolean) – Operation status
Status Codes: - 200 OK – Database removed successfully
- 400 Bad Request – Invalid database name or forgotten document id by accident
- 401 Unauthorized – CouchDB Server Administrator privileges required
- 404 Not Found – Database doesn’t exist
Request:
DELETE /db HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 12 Content-Type: application/json Date: Mon, 12 Aug 2013 08:54:00 GMT Server: CouchDB (Erlang/OTP) { "ok": true }
-
POST
/{db}
¶ Creates a new document in the specified database, using the supplied JSON document structure.
If the JSON structure includes the
_id
field, then the document will be created with the specified document ID.If the
_id
field is not specified, a new unique ID will be generated, following whatever UUID algorithm is configured for that server.Parameters: - db – Database name
Request Headers: - Accept –
- application/json
- text/plain
- Content-Type – application/json
- X-Couch-Full-Commit – Overrides server’s
commit policy
. Possible values are:false
andtrue
. Optional.
Query Parameters: - batch (string) – Stores document in batch mode Possible values:
ok
. Optional
Response Headers: - Content-Type –
- application/json
- text/plain; charset=utf-8
- ETag – Quoted new document’s revision
- Location – Document’s URI
Response JSON Object: - id (string) – Document ID
- ok (boolean) – Operation status
- rev (string) – Revision info
Status Codes: - 201 Created – Document created and stored on disk
- 202 Accepted – Document data accepted, but not yet stored on disk
- 400 Bad Request – Invalid database name
- 401 Unauthorized – Write privileges required
- 404 Not Found – Database doesn’t exist
- 409 Conflict – A Conflicting Document with same ID already exists
Request:
POST /db HTTP/1.1 Accept: application/json Content-Length: 81 Content-Type: application/json { "servings": 4, "subtitle": "Delicious with fresh bread", "title": "Fish Stew" }
Response:
HTTP/1.1 201 Created Cache-Control: must-revalidate Content-Length: 95 Content-Type: application/json Date: Tue, 13 Aug 2013 15:19:25 GMT ETag: "1-9c65296036141e575d32ba9c034dd3ee" Location: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d Server: CouchDB (Erlang/OTP) { "id": "ab39fe0993049b84cfa81acd6ebad09d", "ok": true, "rev": "1-9c65296036141e575d32ba9c034dd3ee" }
Specifying the Document ID¶
The document ID can be specified by including the _id
field in the
JSON of the submitted record. The following request will create the same
document with the ID FishStew
.
Request:
POST /db HTTP/1.1 Accept: application/json Content-Length: 98 Content-Type: application/json { "_id": "FishStew", "servings": 4, "subtitle": "Delicious with fresh bread", "title": "Fish Stew" }Response:
HTTP/1.1 201 Created Cache-Control: must-revalidate Content-Length: 71 Content-Type: application/json Date: Tue, 13 Aug 2013 15:19:25 GMT ETag: "1-9c65296036141e575d32ba9c034dd3ee" Location: http://localhost:5984/db/FishStew Server: CouchDB (Erlang/OTP) { "id": "FishStew", "ok": true, "rev": "1-9c65296036141e575d32ba9c034dd3ee" }
Batch Mode Writes¶
You can write documents to the database at a higher rate by using the batch option. This collects document writes together in memory (on a user-by-user basis) before they are committed to disk. This increases the risk of the documents not being stored in the event of a failure, since the documents are not written to disk immediately.
To use the batched mode, append the batch=ok
query argument to the
URL of the PUT
or POST /{db}
request. The CouchDB server will
respond with a HTTP 202 Accepted response code immediately.
Note
Creating or updating documents with batch mode doesn’t guarantee that all documents will be successfully stored on disk. For example, individual documents may not be saved due to conflicts, rejection by validation function or by other reasons, even if overall the batch was sucessfully submitted.
Request:
POST /db?batch=ok HTTP/1.1
Accept: application/json
Content-Length: 98
Content-Type: application/json
{
"_id": "FishStew",
"servings": 4,
"subtitle": "Delicious with fresh bread",
"title": "Fish Stew"
}
Response:
HTTP/1.1 202 Accepted
Cache-Control: must-revalidate
Content-Length: 28
Content-Type: application/json
Date: Tue, 13 Aug 2013 15:19:25 GMT
Location: http://localhost:5984/db/FishStew
Server: CouchDB (Erlang/OTP)
{
"id": "FishStew",
"ok": true
}