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 kivik provides a generic interface to CouchDB or CouchDB-like databases. 15 16 The kivik package must be used in conjunction with a database driver. The 17 officially supported drivers are: 18 19 - CouchDB: https://github.com/go-kivik/kivik/v4/couchdb 20 - PouchDB: https://github.com/go-kivik/kivik/v4/pouchdb (requires GopherJS) 21 - MockDB: https://github.com/go-kivik/kivik/v4/mockdb 22 23 The Filesystem and Memory drivers are also available, but in early stages of 24 development, and so many features do not yet work: 25 26 - FilesystemDB: https://github.com/go-kivik/kivik/v4/x/fsdb 27 - MemoryDB: https://github.com/go-kivik/kivik/v4/x/memorydb 28 29 The kivik driver system is modeled after the standard library's `sql` and 30 `sql/driver` packages, although the client API is completely different due to 31 the different database models implemented by SQL and NoSQL databases such as 32 CouchDB. 33 34 The most methods, including those on [Client] and [DB] are safe to call 35 concurrently, unless otherwise noted. 36 37 # Working with JSON 38 39 CouchDB stores JSON, so Kivik translates Go data structures to and from JSON as 40 necessary. The conversion from Go data types to JSON, and vice versa, is 41 handled automatically according to the rules and behavior described in the 42 documentation for the standard library's [encoding/json] package. 43 44 # Options 45 46 Most client and database methods take optional arguments of the type [Option]. 47 Multiple options may be passed, and latter options take precedence over earlier 48 ones, in case of a conflict. 49 50 [Params] and [Param] can be used to set options that are generally converted to 51 URL query parameters. Different backend drivers may also provide their own 52 unique options with driver-specific effects. Consult your driver's documentation 53 for specifics. 54 55 # Error Handling 56 57 Kivik returns errors that embed an HTTP status code. In most cases, this is the 58 HTTP status code returned by the server. The embedded HTTP status code may be 59 accessed easily using the HTTPStatus() method, or with a type assertion to 60 `interface { HTTPStatus() int }`. Example: 61 62 if statusErr, ok := err.(interface{ HTTPStatus() int }); ok { 63 status = statusErr.HTTPStatus() 64 } 65 66 Any error that does not conform to this interface will be assumed to represent 67 a http.StatusInternalServerError status code. 68 69 # Authentication 70 71 For common usage, authentication should be as simple as including the authentication credentials in the connection DSN. For example: 72 73 client, err := kivik.New("couch", "http://admin:abc123@localhost:5984/") 74 75 This will connect to `localhost` on port 5984, using the username `admin` and 76 the password `abc123`. When connecting to CouchDB (as in the above example), 77 this will use [cookie auth]. 78 79 Depending on which driver you use, there may be other ways to authenticate, as 80 well. At the moment, the CouchDB driver is the only official driver which offers 81 additional authentication methods. Please refer to the [CouchDB package documentation] 82 for details. 83 84 [cookie auth]: https://docs.couchdb.org/en/stable/api/server/authn.html?highlight=cookie%20auth#cookie-authentication 85 [CouchDB package documentation]: https://pkg.go.dev/github.com/go-kivik/kivik/v4/couchdb 86 */ 87 package kivik // import "github.com/go-kivik/kivik/v4" 88