Short primer on using attachment in CouchDB

CouchDB_attachments.md

Short primer on using attachment in CouchDB

In db "koi" create a doc named "tesla"

$ http put :5984/koi/tesla name=alice
{
    "id": "tesla", 
    "ok": true, 
    "rev": "1-2350796167caec1f6ba70e9145a9e102"
}

$ http :5984/koi/tesla
{
    "_id": "tesla", 
    "_rev": "1-2350796167caec1f6ba70e9145a9e102", 
    "name": "alice"
}

Upload an attachment to the doc

$ echo "text file content" > a.txt

$ http put :5984/koi/tesla/a.txt rev==1-2350796167caec1f6ba70e9145a9e102 < a.txt 
{
    "id": "tesla", 
    "ok": true, 
    "rev": "2-54e94ce961300e7ae3d25fc1b13a2116"
}

$ http :5984/koi/tesla
{
    "_attachments": {
        "a.txt": {
            "content_type": "application/json", 
            "digest": "md5-EIkN28jhWNBVf8Ondxv9Dw==", 
            "length": 18, 
            "revpos": 2, 
            "stub": true
        }
    }, 
    "_id": "tesla", 
    "_rev": "2-54e94ce961300e7ae3d25fc1b13a2116", 
    "name": "alice"
}

$ http :5984/koi/tesla/a.txt --print bh
HTTP/1.1 200 OK
Accept-Ranges: none
Cache-Control: must-revalidate
Content-Encoding: gzip
Content-Length: 38
Content-MD5: EIkN28jhWNBVf8Ondxv9Dw==
Content-Type: application/json
Date: Fri, 26 May 2017 16:08:19 GMT
ETag: "EIkN28jhWNBVf8Ondxv9Dw=="
Server: CouchDB/2.0.0 (Erlang OTP/17)

text file content

Content-Type been application/json due to session settings on my httpie

Update the doc and keep attachment's stub included

$ http :5984/koi/tesla | jq . > tesla.json
$ vi tesla.json
...
change name to "bob"
...

$ http put :5984/koi/tesla < tesla.json 
{
    "id": "tesla", 
    "ok": true, 
    "rev": "3-6b258cd3c34acf223a6938162a121be5"
}

$ http :5984/koi/tesla
{
    "_attachments": {
        "a.txt": {
            "content_type": "application/json", 
            "digest": "md5-EIkN28jhWNBVf8Ondxv9Dw==", 
            "length": 18, 
            "revpos": 2, 
            "stub": true
        }
    }, 
    "_id": "tesla", 
    "_rev": "3-6b258cd3c34acf223a6938162a121be5", 
    "name": "bob"
}

$ http :5984/koi/tesla/a.txt --print bh
HTTP/1.1 200 OK
Accept-Ranges: none
Cache-Control: must-revalidate
Content-Encoding: gzip
Content-Length: 38
Content-MD5: EIkN28jhWNBVf8Ondxv9Dw==
Content-Type: application/json
Date: Fri, 26 May 2017 16:11:55 GMT
ETag: "EIkN28jhWNBVf8Ondxv9Dw=="
Server: CouchDB/2.0.0 (Erlang OTP/17)

text file content

Update the doc again, but this time miss the attachment's stub

$ http put :5984/koi/tesla rev==3-6b258cd3c34acf223a6938162a121be5 name=chuck
{
    "id": "tesla", 
    "ok": true, 
    "rev": "4-56a2bca6fd37c45350d8665bb28114d6"
}


$ http :5984/koi/tesla
{
    "_id": "tesla", 
    "_rev": "4-56a2bca6fd37c45350d8665bb28114d6", 
    "name": "chuck"
}

$ http :5984/koi/tesla/a.txt --print bh
HTTP/1.1 404 Object Not Found
Cache-Control: must-revalidate
Content-Length: 64
Content-Type: application/json
Date: Fri, 26 May 2017 16:13:30 GMT
Server: CouchDB/2.0.0 (Erlang OTP/17)
X-Couch-Request-ID: 81dc829717
X-CouchDB-Body-Time: 0

{
    "error": "not_found", 
    "reason": "Document is missing attachment"
}

Try to put attachment back to the doc using previous stub

$ vi tesla.json
...
update rev to "4-56a2bca6fd37c45350d8665bb28114d6" and set name to "chuck"
...

$ http put :5984/koi/tesla < tesla.json
{
    "error": "missing_stub", 
    "reason": "Invalid attachment stub in tesla for a.txt"
}

# nope, sorry, this doesn't work

Put the attachment back by re-uploading. We still can access it until prev revs of the doc are available

$ http :5984/koi/tesla/a.txt rev==3-6b258cd3c34acf223a6938162a121be5 --print bh
HTTP/1.1 200 OK
Accept-Ranges: none
Cache-Control: must-revalidate
Content-Encoding: gzip
Content-Length: 38
Content-MD5: EIkN28jhWNBVf8Ondxv9Dw==
Content-Type: application/json
Date: Fri, 26 May 2017 17:05:14 GMT
ETag: "EIkN28jhWNBVf8Ondxv9Dw=="
Server: CouchDB/2.0.0 (Erlang OTP/17)

text file content


$ http :5984/koi/tesla/a.txt rev==3-6b258cd3c34acf223a6938162a121be5 > a.txt

$ http put :5984/koi/tesla/a.txt rev==4-56a2bca6fd37c45350d8665bb28114d6 < a.txt
{
    "id": "tesla", 
    "ok": true, 
    "rev": "5-8da9b2c511e6eccffaeb58d96ddcb7b3"
}

$ http :5984/koi/tesla
{
    "_attachments": {
        "a.txt": {
            "content_type": "application/json", 
            "digest": "md5-EIkN28jhWNBVf8Ondxv9Dw==", 
            "length": 18, 
            "revpos": 5, 
            "stub": true
        }
    }, 
    "_id": "tesla", 
    "_rev": "5-8da9b2c511e6eccffaeb58d96ddcb7b3", 
    "name": "chuck"
}

$ http :5984/koi/tesla/a.txt --print bh
HTTP/1.1 200 OK
Accept-Ranges: none
Cache-Control: must-revalidate
Content-Encoding: gzip
Content-Length: 38
Content-MD5: EIkN28jhWNBVf8Ondxv9Dw==
Content-Type: application/json
Date: Fri, 26 May 2017 17:11:16 GMT
ETag: "EIkN28jhWNBVf8Ondxv9Dw=="
Server: CouchDB/2.0.0 (Erlang OTP/17)

text file content