top

Package client and its KV API has been deprecated for external usage. Please use a postgres-compatible SQL driver (e.g. github.com/lib/pq). For more details, see http://www.cockroachlabs.com/blog/sql-in-cockroachdb-mapping-table-data-to-key-value-storage/.

Package client provides clients for accessing the various externally-facing Cockroach database endpoints.

DB Client

The DB client is a fully-featured client of Cockroach's key-value database. It provides a simple, synchronous interface well-suited to parallel updates and queries.

The simplest way to use the client is through the Run method. Run synchronously invokes the call, fills in the reply and returns an error. The example below shows a get and a put.

db, err := client.Open("rpcs://root@localhost:26257")
if err != nil {
	log.Fatal(err)
}
if err := db.Put("a", "hello"); err != nil {
	log.Fatal(err)
}
if gr, err := db.Get("a"); err != nil {
	log.Fatal(err)
} else {
	log.Printf("%s", gr.ValueBytes())  // "hello"
}

The API is synchronous, but accommodates efficient parallel updates and queries using Batch objects. An arbitrary number of calls may be added to a Batch which is executed using DB.Run. Note however that the individual calls within a batch are not guaranteed to have atomic semantics. A transaction must be used to guarantee atomicity. A simple example of using a Batch which does two scans in parallel and then sends a sequence of puts in parallel:

db, err := client.Open("rpcs://root@localhost:26257")
if err != nil {
	log.Fatal(err)
}

b1 := &client.Batch{}
b1.Scan("a", "c\x00", 1000)
b1.Scan("x", "z\x00", 1000)

// Run sends both scans in parallel and returns the first error or nil.
if err := db.Run(b1); err != nil {
	log.Fatal(err)
}

acResult := b1.Results[0]
xzResult := b1.Results[1]

// Append maximum value from "a"-"c" to all values from "x"-"z".
max := []byte(nil)
for _, row := range acResult.Rows {
	if bytes.Compare(max, row.ValueBytes()) < 0 {
		max = row.ValueBytes()
	}
}

b2 := &client.Batch{}
for _, row := range xzResult.Rows {
	b2.Put(row.Key, bytes.Join([][]byte{row.ValueBytes(), max}, []byte(nil)))
}

// Run all puts for parallel execution.
if err := db.Run(b2); err != nil {
	log.Fatal(err)
}

Transactions are supported through the DB.Txn() method, which takes a retryable function, itself composed of the same simple mix of API calls typical of a non-transactional operation. Within the context of the Txn() call, all method invocations are transparently given necessary transactional details, and conflicts are handled with backoff/retry loops and transaction restarts as necessary. An example of using transactions with parallel writes:

db, err := client.Open("rpcs://root@localhost:26257")
if err != nil {
	log.Fatal(err)
}

err := db.Txn(func(txn *client.Txn) error {
	b := txn.NewBatch()
	for i := 0; i < 100; i++ {
		key := fmt.Sprintf("testkey-%02d", i)
		b.Put(key, "test value")
	}

	// Note that the Txn client is flushed automatically when this function
	// returns success (i.e. nil). Calling CommitInBatch explicitly can
	// sometimes reduce the number of RPCs.
	return txn.CommitInBatch(b)
})
if err != nil {
	log.Fatal(err)
}

Note that with Cockroach's lock-free transactions, clients should expect retries as a matter of course. This is why the transaction functionality is exposed through a retryable function. The retryable function should have no side effects which are not idempotent.

Transactions should endeavor to use batches to perform multiple operations in a single RPC. In addition to the reduced number of RPCs to the server, this allows writes to the same range to be batched together. In cases where the entire transaction affects only a single range, transactions can commit in a single round trip.

Imported by 212 package(s)

  1. github.com/756445638/cockroach/acceptance/cluster
  2. github.com/756445638/cockroach/acceptance/terrafarm
  3. github.com/756445638/cockroach/cli
  4. github.com/756445638/cockroach/kv
  5. github.com/756445638/cockroach/server
  6. github.com/756445638/cockroach/sql
  7. github.com/756445638/cockroach/sql/distsql
  8. github.com/756445638/cockroach/sql/sqlbase
  9. github.com/756445638/cockroach/sql/sqlutil
  10. github.com/756445638/cockroach/storage
  11. github.com/756445638/cockroach/testutils/localtestcluster
  12. github.com/756445638/cockroach/testutils/serverutils
  13. github.com/756445638/cockroach/testutils/testcluster
  14. github.com/756445638/cockroach/ts
  15. github.com/Aishraj/cockroach/acceptance/cluster
  16. github.com/Aishraj/cockroach/acceptance/terrafarm
  17. github.com/Aishraj/cockroach/cli
  18. github.com/Aishraj/cockroach/kv
  19. github.com/Aishraj/cockroach/server
  20. github.com/Aishraj/cockroach/sql
  21. github.com/Aishraj/cockroach/sql/distsql
  22. github.com/Aishraj/cockroach/sql/sqlbase
  23. github.com/Aishraj/cockroach/sql/sqlutil
  24. github.com/Aishraj/cockroach/storage
  25. github.com/Aishraj/cockroach/testutils/localtestcluster
  26. github.com/Aishraj/cockroach/testutils/serverutils
  27. github.com/Aishraj/cockroach/testutils/testcluster
  28. github.com/Aishraj/cockroach/ts
  29. github.com/YuleiXiao/cockroach/acceptance/cluster
  30. github.com/YuleiXiao/cockroach/acceptance/terrafarm
  31. github.com/YuleiXiao/cockroach/cli
  32. github.com/YuleiXiao/cockroach/kv
  33. github.com/YuleiXiao/cockroach/server
  34. github.com/YuleiXiao/cockroach/sql
  35. github.com/YuleiXiao/cockroach/sql/distsql
  36. github.com/YuleiXiao/cockroach/sql/sqlbase
  37. github.com/YuleiXiao/cockroach/sql/sqlutil
  38. github.com/YuleiXiao/cockroach/storage
  39. github.com/YuleiXiao/cockroach/testutils/localtestcluster
  40. github.com/YuleiXiao/cockroach/testutils/serverutils
  41. github.com/YuleiXiao/cockroach/testutils/testcluster
  42. github.com/YuleiXiao/cockroach/ts
  43. github.com/a10y/cockroach/acceptance/cluster
  44. github.com/a10y/cockroach/acceptance/terrafarm
  45. github.com/a10y/cockroach/cli
  46. github.com/a10y/cockroach/kv
  47. github.com/a10y/cockroach/server
  48. github.com/a10y/cockroach/sql
  49. github.com/a10y/cockroach/sql/distsql
  50. github.com/a10y/cockroach/sql/sqlbase
  51. github.com/a10y/cockroach/sql/sqlutil
  52. github.com/a10y/cockroach/storage
  53. github.com/a10y/cockroach/testutils/localtestcluster
  54. github.com/a10y/cockroach/testutils/serverutils
  55. github.com/a10y/cockroach/testutils/testcluster
  56. github.com/a10y/cockroach/ts
  57. github.com/abhinavdahiya/cockroach/acceptance/cluster
  58. github.com/abhinavdahiya/cockroach/acceptance/terrafarm
  59. github.com/abhinavdahiya/cockroach/cli
  60. github.com/abhinavdahiya/cockroach/kv
  61. github.com/abhinavdahiya/cockroach/server
  62. github.com/abhinavdahiya/cockroach/sql
  63. github.com/abhinavdahiya/cockroach/sql/distsql
  64. github.com/abhinavdahiya/cockroach/sql/sqlbase
  65. github.com/abhinavdahiya/cockroach/sql/sqlutil
  66. github.com/abhinavdahiya/cockroach/storage
  67. github.com/abhinavdahiya/cockroach/testutils/localtestcluster
  68. github.com/abhinavdahiya/cockroach/testutils/serverutils
  69. github.com/abhinavdahiya/cockroach/testutils/testcluster
  70. github.com/abhinavdahiya/cockroach/ts
  71. github.com/aishraj/cockroach/acceptance/cluster
  72. github.com/aishraj/cockroach/acceptance/terrafarm
  73. github.com/aishraj/cockroach/cli
  74. github.com/aishraj/cockroach/kv
  75. github.com/aishraj/cockroach/server
  76. github.com/aishraj/cockroach/sql
  77. github.com/aishraj/cockroach/sql/distsql
  78. github.com/aishraj/cockroach/sql/sqlbase
  79. github.com/aishraj/cockroach/sql/sqlutil
  80. github.com/aishraj/cockroach/storage
  81. github.com/aishraj/cockroach/testutils/localtestcluster
  82. github.com/aishraj/cockroach/testutils/serverutils
  83. github.com/aishraj/cockroach/testutils/testcluster
  84. github.com/aishraj/cockroach/ts
  85. github.com/andreweduffy/cockroach/acceptance/cluster
  86. github.com/andreweduffy/cockroach/acceptance/terrafarm
  87. github.com/andreweduffy/cockroach/cli
  88. github.com/andreweduffy/cockroach/kv
  89. github.com/andreweduffy/cockroach/server
  90. github.com/andreweduffy/cockroach/sql
  91. github.com/andreweduffy/cockroach/sql/distsql
  92. github.com/andreweduffy/cockroach/sql/sqlbase
  93. github.com/andreweduffy/cockroach/sql/sqlutil
  94. github.com/andreweduffy/cockroach/storage
  95. github.com/andreweduffy/cockroach/testutils/localtestcluster
  96. github.com/andreweduffy/cockroach/testutils/serverutils
  97. github.com/andreweduffy/cockroach/testutils/testcluster
  98. github.com/andreweduffy/cockroach/ts
  99. github.com/asubiotto/cockroach/cli
  100. github.com/asubiotto/cockroach/kv
  101. github.com/asubiotto/cockroach/server
  102. github.com/asubiotto/cockroach/sql
  103. github.com/asubiotto/cockroach/storage
  104. github.com/asubiotto/cockroach/ts
  105. github.com/bdarnell/cockroach/acceptance/cluster
  106. github.com/bdarnell/cockroach/acceptance/terrafarm
  107. github.com/bdarnell/cockroach/cli
  108. github.com/bdarnell/cockroach/kv
  109. github.com/bdarnell/cockroach/server
  110. github.com/bdarnell/cockroach/sql
  111. github.com/bdarnell/cockroach/sql/distsql
  112. github.com/bdarnell/cockroach/sql/sqlbase
  113. github.com/bdarnell/cockroach/sql/sqlutil
  114. github.com/bdarnell/cockroach/storage
  115. github.com/bdarnell/cockroach/testutils/localtestcluster
  116. github.com/bdarnell/cockroach/testutils/serverutils
  117. github.com/bdarnell/cockroach/testutils/testcluster
  118. github.com/bdarnell/cockroach/ts
  119. github.com/cockroachdb/cockroach/acceptance/cluster
  120. github.com/cockroachdb/cockroach/acceptance/terrafarm
  121. github.com/cockroachdb/cockroach/cli
  122. github.com/cockroachdb/cockroach/kv
  123. github.com/cockroachdb/cockroach/server
  124. github.com/cockroachdb/cockroach/sql
  125. github.com/cockroachdb/cockroach/sql/distsql
  126. github.com/cockroachdb/cockroach/sql/sqlbase
  127. github.com/cockroachdb/cockroach/sql/sqlutil
  128. github.com/cockroachdb/cockroach/storage
  129. github.com/cockroachdb/cockroach/testutils/localtestcluster
  130. github.com/cockroachdb/cockroach/testutils/serverutils
  131. github.com/cockroachdb/cockroach/testutils/testcluster
  132. github.com/cockroachdb/cockroach/ts
  133. github.com/d4l3k/cockroach/cli
  134. github.com/d4l3k/cockroach/kv
  135. github.com/d4l3k/cockroach/server
  136. github.com/d4l3k/cockroach/sql
  137. github.com/d4l3k/cockroach/storage
  138. github.com/d4l3k/cockroach/ts
  139. github.com/dlsniper/cockroach/acceptance/cluster
  140. github.com/dlsniper/cockroach/acceptance/terrafarm
  141. github.com/dlsniper/cockroach/cli
  142. github.com/dlsniper/cockroach/kv
  143. github.com/dlsniper/cockroach/server
  144. github.com/dlsniper/cockroach/sql
  145. github.com/dlsniper/cockroach/sql/distsql
  146. github.com/dlsniper/cockroach/sql/sqlbase
  147. github.com/dlsniper/cockroach/sql/sqlutil
  148. github.com/dlsniper/cockroach/storage
  149. github.com/dlsniper/cockroach/testutils/localtestcluster
  150. github.com/dlsniper/cockroach/testutils/serverutils
  151. github.com/dlsniper/cockroach/testutils/testcluster
  152. github.com/dlsniper/cockroach/ts
  153. github.com/kardianos/cockroach/acceptance/cluster
  154. github.com/kardianos/cockroach/acceptance/terrafarm
  155. github.com/kardianos/cockroach/cli
  156. github.com/kardianos/cockroach/sql
  157. github.com/kardianos/cockroach/sql/distsql
  158. github.com/kardianos/cockroach/sql/sqlbase
  159. github.com/kardianos/cockroach/sql/sqlutil
  160. github.com/kardianos/cockroach/storage
  161. github.com/kardianos/cockroach/testutils/localtestcluster
  162. github.com/kardianos/cockroach/testutils/serverutils
  163. github.com/kardianos/cockroach/testutils/testcluster
  164. github.com/kardianos/cockroach/ts
  165. github.com/panyingyun/cockroach/acceptance/cluster
  166. github.com/panyingyun/cockroach/acceptance/terrafarm
  167. github.com/panyingyun/cockroach/cli
  168. github.com/panyingyun/cockroach/kv
  169. github.com/panyingyun/cockroach/server
  170. github.com/panyingyun/cockroach/sql
  171. github.com/panyingyun/cockroach/sql/distsql
  172. github.com/panyingyun/cockroach/sql/sqlbase
  173. github.com/panyingyun/cockroach/sql/sqlutil
  174. github.com/panyingyun/cockroach/storage
  175. github.com/panyingyun/cockroach/testutils/localtestcluster
  176. github.com/panyingyun/cockroach/testutils/serverutils
  177. github.com/panyingyun/cockroach/testutils/testcluster
  178. github.com/panyingyun/cockroach/ts
  179. github.com/rushiagr/cockroach/acceptance/cluster
  180. github.com/rushiagr/cockroach/acceptance/terrafarm
  181. github.com/rushiagr/cockroach/cli
  182. github.com/rushiagr/cockroach/kv
  183. github.com/rushiagr/cockroach/server
  184. github.com/rushiagr/cockroach/sql
  185. github.com/rushiagr/cockroach/sql/distsql
  186. github.com/rushiagr/cockroach/sql/sqlbase
  187. github.com/rushiagr/cockroach/sql/sqlutil
  188. github.com/rushiagr/cockroach/storage
  189. github.com/rushiagr/cockroach/testutils/localtestcluster
  190. github.com/rushiagr/cockroach/testutils/serverutils
  191. github.com/rushiagr/cockroach/testutils/testcluster
  192. github.com/rushiagr/cockroach/ts
  193. github.com/sunya123/cockroach/acceptance/cluster
  194. github.com/sunya123/cockroach/acceptance/terrafarm
  195. github.com/sunya123/cockroach/cli
  196. github.com/sunya123/cockroach/kv
  197. github.com/sunya123/cockroach/server
  198. github.com/sunya123/cockroach/sql
  199. github.com/sunya123/cockroach/sql/distsql
  200. github.com/sunya123/cockroach/sql/sqlbase
  201. github.com/sunya123/cockroach/sql/sqlutil
  202. github.com/sunya123/cockroach/storage
  203. github.com/sunya123/cockroach/testutils/localtestcluster
  204. github.com/sunya123/cockroach/testutils/serverutils
  205. github.com/sunya123/cockroach/testutils/testcluster
  206. github.com/sunya123/cockroach/ts
  207. github.com/tamird/cockroach/cli
  208. github.com/tamird/cockroach/kv
  209. github.com/tamird/cockroach/server
  210. github.com/tamird/cockroach/sql
  211. github.com/tamird/cockroach/storage
  212. github.com/tamird/cockroach/ts

Imported only in test by 25 package(s)

  1. github.com/756445638/cockroach/acceptance
  2. github.com/756445638/cockroach/internal/client
  3. github.com/Aishraj/cockroach/acceptance
  4. github.com/Aishraj/cockroach/internal/client
  5. github.com/YuleiXiao/cockroach/acceptance
  6. github.com/a10y/cockroach/acceptance
  7. github.com/abhinavdahiya/cockroach/acceptance
  8. github.com/abhinavdahiya/cockroach/internal/client
  9. github.com/aishraj/cockroach/acceptance
  10. github.com/aishraj/cockroach/internal/client
  11. github.com/andreweduffy/cockroach/acceptance
  12. github.com/andreweduffy/cockroach/internal/client
  13. github.com/asubiotto/cockroach/acceptance
  14. github.com/bdarnell/cockroach/acceptance
  15. github.com/cockroachdb/cockroach/acceptance
  16. github.com/d4l3k/cockroach/acceptance
  17. github.com/dlsniper/cockroach/acceptance
  18. github.com/dlsniper/cockroach/internal/client
  19. github.com/kardianos/cockroach/acceptance
  20. github.com/panyingyun/cockroach/acceptance
  21. github.com/panyingyun/cockroach/internal/client
  22. github.com/rushiagr/cockroach/acceptance
  23. github.com/rushiagr/cockroach/internal/client
  24. github.com/sunya123/cockroach/acceptance
  25. github.com/tamird/cockroach/acceptance

Imports 17 package(s)

  1. gopkg.in/inf.v0
  2. github.com/opentracing/basictracer-go
  3. github.com/cockroachdb/cockroach/util/tracing
  4. github.com/pkg/errors
  5. github.com/cockroachdb/cockroach/roachpb
  6. github.com/cockroachdb/cockroach/util/log
  7. google.golang.org/grpc
  8. github.com/cockroachdb/cockroach/util/hlc
  9. github.com/cockroachdb/cockroach/storage/engine/enginepb
  10. github.com/gogo/protobuf/proto
  11. github.com/cockroachdb/cockroach/util/caller
  12. github.com/cockroachdb/cockroach/util/duration
  13. golang.org/x/net/context
  14. github.com/cockroachdb/cockroach/util/uuid
  15. github.com/cockroachdb/cockroach/base
  16. github.com/cockroachdb/cockroach/rpc
  17. github.com/cockroachdb/cockroach/util/retry

Test imports 13 package(s)

  1. github.com/cockroachdb/cockroach/security/securitytest
  2. github.com/cockroachdb/cockroach/server
  3. github.com/cockroachdb/cockroach/storage/storagebase
  4. github.com/cockroachdb/cockroach/util/syncutil
  5. github.com/cockroachdb/cockroach/config
  6. github.com/cockroachdb/cockroach/security
  7. github.com/cockroachdb/cockroach/util/leaktest
  8. github.com/cockroachdb/cockroach/util/stop
  9. github.com/cockroachdb/cockroach/util/timeutil
  10. github.com/cockroachdb/cockroach/storage
  11. github.com/cockroachdb/cockroach/testutils/serverutils
  12. github.com/cockroachdb/cockroach/testutils
  13. github.com/cockroachdb/cockroach/util