diff --git a/README.md b/README.md index efe556227..ef32bf756 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Build Status](https://gitlab.com/go-kivik/kivik/badges/master/pipeline.svg)](https://gitlab.com/go-kivik/kivik/pipelines) [![Codecov](https://img.shields.io/codecov/c/github/go-kivik/kivik.svg?style=flat)](https://codecov.io/gh/go-kivik/kivik) [![Go Report Card](https://goreportcard.com/badge/github.com/go-kivik/kivik)](https://goreportcard.com/report/github.com/go-kivik/kivik) [![GoDoc](https://godoc.org/github.com/go-kivik/kivik?status.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4) [![Website](https://img.shields.io/website-up-down-green-red/http/kivik.io.svg?label=website&colorB=007fff)](http://kivik.io) +[![Build Status](https://gitlab.com/go-kivik/kivik/badges/master/pipeline.svg)](https://gitlab.com/go-kivik/kivik/pipelines) [![Codecov](https://img.shields.io/codecov/c/github/go-kivik/kivik.svg?style=flat)](https://codecov.io/gh/go-kivik/kivik) [![Go Report Card](https://goreportcard.com/badge/github.com/go-kivik/kivik)](https://goreportcard.com/report/github.com/go-kivik/kivik) [![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4) [![Website](https://img.shields.io/website-up-down-green-red/http/kivik.io.svg?label=website&colorB=007fff)](http://kivik.io) # Kivik @@ -58,9 +58,8 @@ Consult the [CLI README](https://github.com/go-kivik/kivik/blob/master/cmd/kivik # Example Usage -Please consult the the [package documentation](https://godoc.org/github.com/go-kivik/kivik) -for all available API methods, and a complete usage documentation. And for -additional usage examples, [consult the wiki](https://github.com/go-kivik/kivik/wiki/Usage-Examples). +Please consult the the [package documentation](https://pkg.go.dev/github.com/go-kivik/kivik/v4) +for all available API methods, and a complete usage documentation, and usage examples. ```go package main diff --git a/couchdb/README.md b/couchdb/README.md index bfb66135c..e3a2f8474 100644 --- a/couchdb/README.md +++ b/couchdb/README.md @@ -1,4 +1,4 @@ -[![Build Status](https://travis-ci.org/go-kivik/couchdb.svg?branch=master)](https://travis-ci.org/go-kivik/couchdb) [![Codecov](https://img.shields.io/codecov/c/github/go-kivik/couchdb.svg?style=flat)](https://codecov.io/gh/go-kivik/couchdb) [![GoDoc](https://godoc.org/github.com/go-kivik/couchdb?status.svg)](http://godoc.org/github.com/go-kivik/couchdb) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/couchdb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/couchdb) # Kivik CouchDB @@ -7,11 +7,9 @@ CouchDB driver for [Kivik](https://github.com/go-kivik/kivik). ## Usage This package provides an implementation of the -[`github.com/go-kivik/kivik/v4/driver`](http://godoc.org/github.com/go-kivik/kivik/driver) +[`github.com/go-kivik/kivik/v4/driver`](http://pkg.go.dev/github.com/go-kivik/kivik/v4/driver) interface. You must import the driver and can then use the full -[`Kivik`](http://godoc.org/github.com/go-kivik/kivik) API. Please consult the -[Kivik wiki](https://github.com/go-kivik/kivik/wiki) for complete documentation -and coding examples. +[`Kivik`](http://pkg.go.dev/github.com/go-kivik/kivik/v4) API. ```go package main diff --git a/db_example_test.go b/db_example_test.go index 64022126d..fb0d45232 100644 --- a/db_example_test.go +++ b/db_example_test.go @@ -14,6 +14,7 @@ package kivik_test import ( "context" + "encoding/json" "fmt" kivik "github.com/go-kivik/kivik/v4" @@ -103,22 +104,83 @@ func ExampleDB_updateView() { } func ExampleDB_query() { - rows := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Params(map[string]interface{}{ + rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Params(map[string]interface{}{ "startkey": `"foo"`, // Quotes are necessary so the "endkey": `"foo` + kivik.EndKeySuffix + `"`, // key is a valid JSON object })) - if err := rows.Err(); err != nil { - panic(err) + defer rs.Close() + for rs.Next() { + var doc interface{} + if err := rs.ScanDoc(&doc); err != nil { + panic(err) + } + /* do something with doc */ } - for rows.Next() { + if rs.Err() != nil { + panic(rs.Err()) + } +} + +func ExampleDB_query_compound_key() { + rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Params(map[string]interface{}{ + "startkey": []string{"foo", "bar"}, + "endkey": []string{"foo", "bar" + kivik.EndKeySuffix}, + })) + defer rs.Close() + for rs.Next() { var doc interface{} - if err := rows.ScanDoc(&doc); err != nil { + if err := rs.ScanDoc(&doc); err != nil { panic(err) } /* do something with doc */ } - if rows.Err() != nil { - panic(rows.Err()) + if rs.Err() != nil { + panic(rs.Err()) + } +} + +func ExampleDB_query_literal_JSON_keys() { + rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Param( + "startkey", json.RawMessage(`{"foo":true}`), + )) + defer rs.Close() + for rs.Next() { + var doc interface{} + if err := rs.ScanDoc(&doc); err != nil { + panic(err) + } + /* do something with doc */ + } + if rs.Err() != nil { + panic(rs.Err()) + } +} + +func ExampleDB_multiple_queries() { + rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Param( + "queries", []interface{}{ + map[string]interface{}{ + "startkey": []string{"foo", "bar"}, + "endkey": []string{"foo", "bar" + kivik.EndKeySuffix}, + "include_docs": true, + }, + map[string]interface{}{ + "startkey": []string{"baz", "bar"}, + "endkey": []string{"baz", "bar" + kivik.EndKeySuffix}, + "include_docs": true, + }, + })) + defer rs.Close() + var rsIndex int + for rs.NextResultSet() { + rsIndex++ + for rs.Next() { + var doc interface{} + if err := rs.ScanDoc(&doc); err != nil { + panic(err) + } + /* do something with doc */ + } } } diff --git a/doc.go b/doc.go index 9058c3114..25622853c 100644 --- a/doc.go +++ b/doc.go @@ -31,6 +31,9 @@ The kivik driver system is modeled after the standard library's `sql` and the different database models implemented by SQL and NoSQL databases such as CouchDB. +The most methods, including those on [Client] and [DB] are safe to call +concurrently, unless otherwise noted. + # Working with JSON CouchDB stores JSON, so Kivik translates Go data structures to and from JSON as @@ -38,9 +41,6 @@ necessary. The conversion from Go data types to JSON, and vice versa, is handled automatically according to the rules and behavior described in the documentation for the standard library's [encoding/json] package. -One would be well-advised to become familiar with using `json` struct field -tags [encoding/json.Marshal] when working with JSON documents. - # Options Most client and database methods take optional arguments of the type [Option]. diff --git a/mockdb/README.md b/mockdb/README.md index ff4511808..3880f7a4d 100644 --- a/mockdb/README.md +++ b/mockdb/README.md @@ -1,3 +1,5 @@ +[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/x/mockdb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/mockdb) + # MockDB Package **mockdb** is a mock library implementing a Kivik driver. diff --git a/pouchdb/README.md b/pouchdb/README.md index 1174ae4b5..b129d16d9 100644 --- a/pouchdb/README.md +++ b/pouchdb/README.md @@ -1,4 +1,4 @@ -[![Build Status](https://travis-ci.org/go-kivik/pouchdb.svg?branch=master)](https://travis-ci.org/go-kivik/pouchdb) [![GoDoc](https://godoc.org/github.com/go-kivik/pouchdb?status.svg)](http://godoc.org/github.com/go-kivik/pouchdb) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/pouchdb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/pouchdb) # Kivik PouchDB @@ -17,11 +17,9 @@ with Kivik as an example. ## Usage This package provides an implementation of the -[`github.com/go-kivik/kivik/driver`](http://godoc.org/github.com/go-kivik/kivik/driver) +[`github.com/go-kivik/kivik/v4/driver`](http://pkg.go.dev/github.com/go-kivik/kivik/v4/driver) interface. You must import the driver and can then use the full -[`Kivik`](http://godoc.org/github.com/go-kivik/kivik) API. Please consult the -[Kivik wiki](https://github.com/go-kivik/kivik/wiki) for complete documentation -and coding examples. +[`Kivik`](http://pkg.go.dev/github.com/go-kivik/kivik/v4) API. ```go // +build js diff --git a/x/fsdb/README.md b/x/fsdb/README.md index 8b681c4e2..ebb1f0a86 100644 --- a/x/fsdb/README.md +++ b/x/fsdb/README.md @@ -1,4 +1,4 @@ -[![GoDoc](https://godoc.org/github.com/go-kivik/kivik/v4/x/fsdb?status.svg)](http://godoc.org/github.com/go-kivik/kivik/v4/x/fsdb) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/x/fsdb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/fsdb) # Kivik FSDB @@ -13,11 +13,9 @@ This is very much a work in progress. Things are expected to change quickly. ## Usage This package provides an implementation of the -[`github.com/go-kivik/kivik/driver`](http://godoc.org/github.com/go-kivik/kivik/driver) +[`github.com/go-kivik/kivik/driver`](http://pkg.go.dev/github.com/go-kivik/kivik/v4/driver) interface. You must import the driver and can then use the full -[`Kivik`](http://godoc.org/github.com/go-kivik/kivik) API. Please consult the -[Kivik wiki](https://github.com/go-kivik/kivik/wiki) for complete documentation -and coding examples. +[`Kivik`](http://pkg.go.dev/github.com/go-kivik/kivik/v4) API. ```go package main diff --git a/x/mango/README.md b/x/mango/README.md index 80e55c26e..6d8b429d4 100644 --- a/x/mango/README.md +++ b/x/mango/README.md @@ -1,4 +1,4 @@ -[![GoDoc](https://godoc.org/github.com/go-kivik/kivik/v4/x/mango?status.svg)](http://godoc.org/github.com/go-kivik/kivik/v4/x/mango) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/x/mango.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/mango) # Mango diff --git a/x/memorydb/README.md b/x/memorydb/README.md index 50d65beab..26db82296 100644 --- a/x/memorydb/README.md +++ b/x/memorydb/README.md @@ -1,4 +1,4 @@ -[![GoDoc](https://godoc.org/github.com/go-kivik/kivik/v4/x/memorydb?status.svg)](http://godoc.org/github.com/go-kivik/kivik/v4/x/memorydb) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/x/memorydb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/memorydb) # Kivik MemoryDB @@ -9,11 +9,9 @@ This driver stores documents in memory only, and is intended for testing purpose ## Usage This package provides an implementation of the -[`github.com/go-kivik/kivik/driver`](http://godoc.org/github.com/go-kivik/kivik/driver) +[`github.com/go-kivik/kivik/driver`](http://pkg.go.dev/github.com/go-kivik/kivik/v4/driver) interface. You must import the driver and can then use the full -[`Kivik`](http://godoc.org/github.com/go-kivik/kivik) API. Please consult the -[Kivik wiki](https://github.com/go-kivik/kivik/wiki) for complete documentation -and coding examples. +[`Kivik`](http://pkg.go.dev/github.com/go-kivik/kivik/v4) API. ```go package main