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 168 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/cli
  30. github.com/YuleiXiao/cockroach/kv
  31. github.com/YuleiXiao/cockroach/server
  32. github.com/YuleiXiao/cockroach/sql
  33. github.com/YuleiXiao/cockroach/storage
  34. github.com/YuleiXiao/cockroach/ts
  35. github.com/abhinavdahiya/cockroach/acceptance/cluster
  36. github.com/abhinavdahiya/cockroach/acceptance/terrafarm
  37. github.com/abhinavdahiya/cockroach/cli
  38. github.com/abhinavdahiya/cockroach/kv
  39. github.com/abhinavdahiya/cockroach/server
  40. github.com/abhinavdahiya/cockroach/sql
  41. github.com/abhinavdahiya/cockroach/sql/distsql
  42. github.com/abhinavdahiya/cockroach/sql/sqlbase
  43. github.com/abhinavdahiya/cockroach/sql/sqlutil
  44. github.com/abhinavdahiya/cockroach/storage
  45. github.com/abhinavdahiya/cockroach/testutils/localtestcluster
  46. github.com/abhinavdahiya/cockroach/testutils/serverutils
  47. github.com/abhinavdahiya/cockroach/testutils/testcluster
  48. github.com/abhinavdahiya/cockroach/ts
  49. github.com/andreweduffy/cockroach/acceptance/cluster
  50. github.com/andreweduffy/cockroach/acceptance/terrafarm
  51. github.com/andreweduffy/cockroach/cli
  52. github.com/andreweduffy/cockroach/kv
  53. github.com/andreweduffy/cockroach/server
  54. github.com/andreweduffy/cockroach/sql
  55. github.com/andreweduffy/cockroach/sql/distsql
  56. github.com/andreweduffy/cockroach/sql/sqlbase
  57. github.com/andreweduffy/cockroach/sql/sqlutil
  58. github.com/andreweduffy/cockroach/storage
  59. github.com/andreweduffy/cockroach/testutils/localtestcluster
  60. github.com/andreweduffy/cockroach/testutils/serverutils
  61. github.com/andreweduffy/cockroach/testutils/testcluster
  62. github.com/andreweduffy/cockroach/ts
  63. github.com/asubiotto/cockroach/cli
  64. github.com/asubiotto/cockroach/kv
  65. github.com/asubiotto/cockroach/server
  66. github.com/asubiotto/cockroach/sql
  67. github.com/asubiotto/cockroach/storage
  68. github.com/asubiotto/cockroach/ts
  69. github.com/bdarnell/cockroach/acceptance/cluster
  70. github.com/bdarnell/cockroach/acceptance/terrafarm
  71. github.com/bdarnell/cockroach/cli
  72. github.com/bdarnell/cockroach/kv
  73. github.com/bdarnell/cockroach/server
  74. github.com/bdarnell/cockroach/sql
  75. github.com/bdarnell/cockroach/sql/distsql
  76. github.com/bdarnell/cockroach/sql/sqlbase
  77. github.com/bdarnell/cockroach/sql/sqlutil
  78. github.com/bdarnell/cockroach/storage
  79. github.com/bdarnell/cockroach/testutils/localtestcluster
  80. github.com/bdarnell/cockroach/testutils/serverutils
  81. github.com/bdarnell/cockroach/testutils/testcluster
  82. github.com/bdarnell/cockroach/ts
  83. github.com/cockroachdb/cockroach/acceptance/cluster
  84. github.com/cockroachdb/cockroach/acceptance/terrafarm
  85. github.com/cockroachdb/cockroach/cli
  86. github.com/cockroachdb/cockroach/kv
  87. github.com/cockroachdb/cockroach/server
  88. github.com/cockroachdb/cockroach/sql
  89. github.com/cockroachdb/cockroach/sql/distsql
  90. github.com/cockroachdb/cockroach/sql/sqlbase
  91. github.com/cockroachdb/cockroach/sql/sqlutil
  92. github.com/cockroachdb/cockroach/storage
  93. github.com/cockroachdb/cockroach/testutils/localtestcluster
  94. github.com/cockroachdb/cockroach/testutils/serverutils
  95. github.com/cockroachdb/cockroach/testutils/testcluster
  96. github.com/cockroachdb/cockroach/ts
  97. github.com/d4l3k/cockroach/cli
  98. github.com/d4l3k/cockroach/kv
  99. github.com/d4l3k/cockroach/server
  100. github.com/d4l3k/cockroach/sql
  101. github.com/d4l3k/cockroach/storage
  102. github.com/d4l3k/cockroach/ts
  103. github.com/dlsniper/cockroach/acceptance/cluster
  104. github.com/dlsniper/cockroach/acceptance/terrafarm
  105. github.com/dlsniper/cockroach/cli
  106. github.com/dlsniper/cockroach/kv
  107. github.com/dlsniper/cockroach/server
  108. github.com/dlsniper/cockroach/sql
  109. github.com/dlsniper/cockroach/sql/distsql
  110. github.com/dlsniper/cockroach/sql/sqlbase
  111. github.com/dlsniper/cockroach/sql/sqlutil
  112. github.com/dlsniper/cockroach/storage
  113. github.com/dlsniper/cockroach/testutils/localtestcluster
  114. github.com/dlsniper/cockroach/testutils/serverutils
  115. github.com/dlsniper/cockroach/testutils/testcluster
  116. github.com/dlsniper/cockroach/ts
  117. github.com/kardianos/cockroach/acceptance/cluster
  118. github.com/kardianos/cockroach/acceptance/terrafarm
  119. github.com/kardianos/cockroach/cli
  120. github.com/kardianos/cockroach/sql
  121. github.com/kardianos/cockroach/sql/distsql
  122. github.com/kardianos/cockroach/sql/sqlbase
  123. github.com/kardianos/cockroach/sql/sqlutil
  124. github.com/kardianos/cockroach/storage
  125. github.com/kardianos/cockroach/testutils/localtestcluster
  126. github.com/kardianos/cockroach/testutils/serverutils
  127. github.com/kardianos/cockroach/testutils/testcluster
  128. github.com/kardianos/cockroach/ts
  129. github.com/panyingyun/cockroach/acceptance/cluster
  130. github.com/panyingyun/cockroach/acceptance/terrafarm
  131. github.com/panyingyun/cockroach/cli
  132. github.com/panyingyun/cockroach/kv
  133. github.com/panyingyun/cockroach/server
  134. github.com/panyingyun/cockroach/sql
  135. github.com/panyingyun/cockroach/sql/distsql
  136. github.com/panyingyun/cockroach/sql/sqlbase
  137. github.com/panyingyun/cockroach/sql/sqlutil
  138. github.com/panyingyun/cockroach/storage
  139. github.com/panyingyun/cockroach/testutils/localtestcluster
  140. github.com/panyingyun/cockroach/testutils/serverutils
  141. github.com/panyingyun/cockroach/testutils/testcluster
  142. github.com/panyingyun/cockroach/ts
  143. github.com/rushiagr/cockroach/acceptance/cluster
  144. github.com/rushiagr/cockroach/acceptance/terrafarm
  145. github.com/rushiagr/cockroach/cli
  146. github.com/rushiagr/cockroach/kv
  147. github.com/rushiagr/cockroach/server
  148. github.com/rushiagr/cockroach/sql
  149. github.com/rushiagr/cockroach/sql/distsql
  150. github.com/rushiagr/cockroach/sql/sqlbase
  151. github.com/rushiagr/cockroach/sql/sqlutil
  152. github.com/rushiagr/cockroach/storage
  153. github.com/rushiagr/cockroach/testutils/localtestcluster
  154. github.com/rushiagr/cockroach/testutils/serverutils
  155. github.com/rushiagr/cockroach/testutils/testcluster
  156. github.com/rushiagr/cockroach/ts
  157. github.com/sunya123/cockroach/cli
  158. github.com/sunya123/cockroach/kv
  159. github.com/sunya123/cockroach/server
  160. github.com/sunya123/cockroach/sql
  161. github.com/sunya123/cockroach/storage
  162. github.com/sunya123/cockroach/ts
  163. github.com/tamird/cockroach/cli
  164. github.com/tamird/cockroach/kv
  165. github.com/tamird/cockroach/server
  166. github.com/tamird/cockroach/sql
  167. github.com/tamird/cockroach/storage
  168. github.com/tamird/cockroach/ts

Imported only in test by 22 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/abhinavdahiya/cockroach/acceptance
  7. github.com/abhinavdahiya/cockroach/internal/client
  8. github.com/andreweduffy/cockroach/acceptance
  9. github.com/andreweduffy/cockroach/internal/client
  10. github.com/asubiotto/cockroach/acceptance
  11. github.com/bdarnell/cockroach/acceptance
  12. github.com/cockroachdb/cockroach/acceptance
  13. github.com/d4l3k/cockroach/acceptance
  14. github.com/dlsniper/cockroach/acceptance
  15. github.com/dlsniper/cockroach/internal/client
  16. github.com/kardianos/cockroach/acceptance
  17. github.com/panyingyun/cockroach/acceptance
  18. github.com/panyingyun/cockroach/internal/client
  19. github.com/rushiagr/cockroach/acceptance
  20. github.com/rushiagr/cockroach/internal/client
  21. github.com/sunya123/cockroach/acceptance
  22. 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