From 8ba25b2ca7f1a981fabfaafdf6d982e04131055c Mon Sep 17 00:00:00 2001 From: Jonathan Hall Date: Tue, 24 Oct 2023 22:37:47 +0200 Subject: [PATCH 1/4] Mention concurrency safetey in docs. Fixes #575 --- doc.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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]. From 9f5ff3e7f99a6cfda6d26e97971f84472bde3322 Mon Sep 17 00:00:00 2001 From: Jonathan Hall Date: Tue, 24 Oct 2023 22:48:41 +0200 Subject: [PATCH 2/4] Add multi-query example. Fixes #612 --- db_example_test.go | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/db_example_test.go b/db_example_test.go index 64022126d..f79c8714f 100644 --- a/db_example_test.go +++ b/db_example_test.go @@ -103,22 +103,47 @@ 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) - } - for rows.Next() { + 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_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 */ + } } } From 706240177d08a388ab75eccf817c766e803d264b Mon Sep 17 00:00:00 2001 From: Jonathan Hall Date: Tue, 24 Oct 2023 22:57:27 +0200 Subject: [PATCH 3/4] Add more doc examples from wiki --- db_example_test.go | 61 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 49 insertions(+), 12 deletions(-) diff --git a/db_example_test.go b/db_example_test.go index f79c8714f..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" @@ -120,20 +121,56 @@ func ExampleDB_query() { } } -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, - }, +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 := rs.ScanDoc(&doc); err != nil { + panic(err) + } + /* do something with doc */ + } + 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++ From 68d17aebb5c3128fc5ada41b7a42d0637c8a1484 Mon Sep 17 00:00:00 2001 From: Jonathan Hall Date: Tue, 24 Oct 2023 23:04:06 +0200 Subject: [PATCH 4/4] Update doc links --- README.md | 7 +++---- couchdb/README.md | 8 +++----- mockdb/README.md | 2 ++ pouchdb/README.md | 8 +++----- x/fsdb/README.md | 8 +++----- x/mango/README.md | 2 +- x/memorydb/README.md | 8 +++----- 7 files changed, 18 insertions(+), 25 deletions(-) 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/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