1 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 2 // use this file except in compliance with the License. You may obtain a copy of 3 // the License at 4 // 5 // http://www.apache.org/licenses/LICENSE-2.0 6 // 7 // Unless required by applicable law or agreed to in writing, software 8 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 9 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 10 // License for the specific language governing permissions and limitations under 11 // the License. 12 13 /* 14 Package couchdb is a driver for connecting with a CouchDB server over HTTP. 15 16 # General Usage 17 18 Use the `couch` driver name when using this driver. The DSN should be a full 19 URL, likely with login credentials: 20 21 import ( 22 kivik "github.com/go-kivik/kivik/v4" 23 _ "github.com/go-kivik/kivik/v4/couchdb" // The CouchDB driver 24 ) 25 26 client, err := kivik.New("couch", "http://username:password@127.0.0.1:5984/") 27 28 # Options 29 30 The CouchDB driver generally interprets [github.com/go-kivik/kivik/v4.Params] 31 keys and values as URL query parameters. Values of the following types will be 32 converted to their ppropriate string representation when URL-encoded: 33 34 - bool 35 - string 36 - []string 37 - int, uint, uint8, uint16, uint32, uint64, int8, int16, int32, int64 38 39 Passing any other type will return an error. 40 41 CouchDB also accepts a few special-case options defined in this package. 42 43 # Authentication 44 45 The CouchDB driver supports a number of authentication methods. For most uses, 46 you don't need to worry about authentication at all--just include authentication 47 credentials in your connection DSN: 48 49 client, _ := kivik.New("couch", "http://user:password@localhost:5984/") 50 51 This will use Cookie authentication by default (or BasicAuth if compiled with 52 GopherJS). 53 54 To use one of the explicit authentication mechanisms, pass one of the 55 authentication options to [New]. For example: 56 57 client, _ := kivik.New("couch", "http://localhost:5984/", couchdb.BasicAuth("bob", "secret")) 58 59 # Connection Options 60 61 Calls to [github.com/go-kivik/kivik/v4.New] may include options. 62 [OptionUserAgent] and [OptionHTTPClient] are the only options honored. Example: 63 64 client, _ := kivik.New("couch", "http://localhost:5984/", 65 couchdb.OptionUserAgent("My Custom User Agent String"), 66 couchdb.OptionHTTPClient(&http.Client{ 67 Timeout: 15, // A shorter request timeout 68 }), 69 ) 70 71 # Multipart PUT 72 73 Normally, to include an attachment in a CouchDB document, it must be base-64 74 encoded, which leads to increased network traffic and higher CPU load. CouchDB 75 also supports the option to [upload multiple attachments] in a single request 76 using the 'multipart/related' content type. 77 78 This is supported by the Kivik CouchDB driver as well. To take advantage of this 79 capability, the `doc` argument to [github.com/go-kivik/kivik/v4.DB.Put] must 80 be either: 81 82 - a map of type `map[string]interface{}`, with a key called `_attachments', 83 and value of type [github.com/go-kivik/kivik/v4.Attachments] or pointer 84 to [github.com/go-kivik/kivik/v4.Attachments] 85 - a struct, with a field having the tag `json:"_attachment"`, and the field 86 having the type [github.com/go-kivik/kivik/v4.Attachments] or pointer to 87 [github.com/go-kivik/kivik/v4.Attachments]. 88 89 With this in place, the CouchDB driver will switch to `multipart/related` mode, 90 sending each attachment in binary format, rather than base-64 encoding it. 91 92 To function properly, each attachment must have an accurate 93 [github.com/go-kivik/kivik/v4.Attachment.Size] value. If 94 [github.com/go-kivik/kivik/v4.Attachment.Size] is unset, the entirely attachment 95 may be read to determine its size, prior to sending it over the network, leading 96 to delays and unnecessary I/O and CPU usage. The simplest way to ensure 97 efficiency is to use [NewAttachment]. See the documentation on that function 98 for proper usage. 99 100 Example: 101 102 file, _ := os.Open("/path/to/photo.jpg") 103 atts := &kivik.Attachments{ 104 "photo.jpg": NewAttachment("photo.jpg", "image/jpeg", file), 105 } 106 doc := map[string]interface{}{ 107 "_id": "user123", 108 "_attachments": atts, 109 } 110 rev, err := db.Put(ctx, "user123", doc) 111 112 To disable the `multipart/related` capabilities entirely, you may pass the 113 [OptionNoMultipartPut] option. This will fallback to the default of 114 inline base-64 encoding the attachments. Example: 115 116 rev, err := db.Put(ctx, "user123", doc", couchdb.OptionNoMultipartPut()) 117 118 # Server config for CouchDB 1.x 119 120 CouchDB allows querying the server configuration via the /_config endpoint. This 121 is supported with the [github.com/go-kivik/kivik/v4.DB.Config], 122 [github.com/go-kivik/kivik/v4.DB.ConfigSection], 123 [github.com/go-kivik/kivik/v4.DB.ConfigValue], 124 [github.com/go-kivik/kivik/v4.DB.SetConfigValue], and 125 [github.com/go-kivik/kivik/v4.DB.DeleteConfigKey] methods. Each of these methods 126 accepts a node argument, but CouchDB 1.x does not support per-node configuration 127 via this endpoint. If you are still using CouchDB 1.x, leave the node argument 128 empty, and this driver will revert to CouchDB-compatible operation. 129 130 [upload multiple attachments]: http://docs.couchdb.org/en/stable/api/document/common.html#creating-multiple-attachments 131 */ 132 package couchdb 133