cockroachkv

command module
v0.0.0-...-4ac3ba3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 28, 2017 License: Apache-2.0 Imports: 2 Imported by: 0

README

CockroachDB

CockroachDB is a scalable, survivable, strongly-consistent SQL database.

TeamCity CI GoDoc Project Status Gitter

What is CockroachDB?

CockroachDB is a distributed SQL database built on a transactional and strongly-consistent key-value store. It scales horizontally; survives disk, machine, rack, and even datacenter failures with minimal latency disruption and no manual intervention; supports strongly-consistent ACID transactions; and provides a familiar SQL API for structuring, manipulating, and querying data.

For more details, see our FAQ and original design document.

Status

CockroachDB is currently in beta. See our 1.0 Roadmap and Issues for a list of features planned or in development.

Docs

For guidance on installation, development, deployment, and administration, see our User Documentation.

Quickstart

  1. Install Cockroach DB.

  2. Start a local cluster with three nodes listening on different ports:

    $ ./cockroach start --background
    $ ./cockroach start --store=cockroach-data2 --port=26258 --http-port=8081 --join=localhost:26257 --background
    $ ./cockroach start --store=cockroach-data3 --port=26259 --http-port=8082 --join=localhost:26257 --background
    
  3. Start the built-in SQL client as an interactive shell:

    $ ./cockroach sql
    # Welcome to the cockroach SQL interface.
    # All statements must be terminated by a semicolon.
    # To exit: CTRL + D.
    
  4. Run some CockroachDB SQL statements:

    root@:26257> CREATE DATABASE bank;
    CREATE DATABASE
    
    root@:26257> SET DATABASE = bank;
    SET
    
    root@:26257> CREATE TABLE accounts (id INT PRIMARY KEY, balance DECIMAL);
    CREATE TABLE
    
    root@26257> INSERT INTO accounts VALUES (1234, 10000.50);
    INSERT 1
    
    root@26257> SELECT * FROM accounts;
    +------+----------+
    |  id  | balance  |
    +------+----------+
    | 1234 | 10000.50 |
    +------+----------+
    
  5. Checkout the admin UI by pointing your browser to http://<localhost>:8080.

  6. CockroachDB makes it easy to secure a cluster.

Client Drivers

CockroachDB supports the PostgreSQL wire protocol, so you can use any available PostgreSQL client drivers to connect from various languages. For recommended drivers that we've tested, see Install Client Drivers.

Deployment

  • Manual - Steps to deploy a CockroachDB cluster manually on multiple machines.

  • Cloud - Configuration files and instructions for deploying an insecure development or test cluster on GCE or AWS using Terraform.

Need Help?

  • CockroachDB Forum - Ask questions, find answers, and help other users.

  • Join us on Gitter - This is the most immediate way to connect with CockroachDB engineers.

  • For filing bugs, suggesting improvements, or requesting new features, help us out by opening an issue.

Contributing

We're an open source project and welcome contributions.

  1. See CONTRIBUTING.md to get your local environment set up.

  2. Take a look at our open issues, in particular those with the helpwanted label.

  3. Review our style guide and follow our code reviews to learn about our style and conventions.

  4. Make your changes according to our code review workflow.

Design

This is an overview. For an in-depth discussion of the design and architecture, see the full design doc.

For another quick design overview, see the CockroachDB tech talk slides.

Design Goals

CockroachDB is a distributed SQL database built on top of a transactional and consistent key:value store.

The primary design goals are support for ACID transactions, horizontal scalability and survivability, hence the name.

It aims to tolerate disk, machine, rack, and even datacenter failures with minimal latency disruption and no manual intervention.

CockroachDB nodes (RoachNodes) are symmetric; a design goal is homogeneous deployment (one binary) with minimal configuration.

How it Works in a Nutshell

CockroachDB implements a single, monolithic sorted map from key to value where both keys and values are byte strings (not unicode).

The map is composed of one or more ranges and each range is backed by data stored in RocksDB (a variant of LevelDB), and is replicated to a total of three or more CockroachDB servers. This enables CockroachDB to scale linearly — theoretically up to 4 exabytes (4E) of logical data.

Ranges are defined by start and end keys. Ranges are merged and split to maintain total byte size within a globally configurable min/max size interval. Range sizes default to target 64M in order to facilitate quick splits and merges and to distribute load at hotspots within a key range. Range replicas are intended to be located in disparate datacenters for survivability (e.g. { US-East, US-West, Japan }, { Ireland, US-East, US-West} , { Ireland, US-East, US-West, Japan, Australia }).

Single mutations to ranges are mediated via an instance of a distributed consensus algorithm to ensure consistency. We’ve chosen to use the Raft consensus algorithm. All consensus state is also stored in RocksDB.

A single logical mutation may affect multiple key/value pairs. Logical mutations have ACID transactional semantics. If all keys affected by a logical mutation fall within the same range, atomicity and consistency are guaranteed by Raft; this is the fast commit path. Otherwise, a non-locking distributed commit protocol is employed between affected ranges.

CockroachDB provides snapshot isolation (SI) and serializable snapshot isolation (SSI) semantics, allowing externally consistent, lock-free reads and writes--both from an historical snapshot timestamp and from the current wall clock time. SI provides lock-free reads and writes but still allows write skew. SSI eliminates write skew, but introduces a performance hit in the case of a contentious system. SSI is the default isolation; clients must consciously decide to trade correctness for performance. CockroachDB implements a limited form of linearalizability, providing ordering for any observer or chain of observers.

Similar to Spanner directories, CockroachDB allows configuration of arbitrary zones of data. This allows replication factor, storage device type, and/or datacenter location to be chosen to optimize performance and/or availability. Unlike Spanner, zones are monolithic and don’t allow movement of fine grained data on the level of entity groups.

Comparison with Other Databases

To see how key features of CockroachDB stack up against other databases, visit the CockroachDB in Comparison page hosted on our docs site.

See Also

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
pkg
acceptance/cluster
Package cluster is a generated protocol buffer package.
Package cluster is a generated protocol buffer package.
build
Package build is a generated protocol buffer package.
Package build is a generated protocol buffer package.
ccl
ccl/sqlccl
Package sqlccl is a generated protocol buffer package.
Package sqlccl is a generated protocol buffer package.
cli
cmd/generate-binary
This connects to a postgres server and crafts postgres-protocol message to encode its arguments into postgres' binary encoding.
This connects to a postgres server and crafts postgres-protocol message to encode its arguments into postgres' binary encoding.
cmd/github-pull-request-make
This utility detects new tests added in a given pull request, and runs them under stress in our CI infrastructure.
This utility detects new tests added in a given pull request, and runs them under stress in our CI infrastructure.
cmd/glock-diff-parser
This utility is useful when auditing dependency updates.
This utility is useful when auditing dependency updates.
cmd/gossipsim
Package simulation provides tools meant to visualize or test aspects of a Cockroach cluster on a single host.
Package simulation provides tools meant to visualize or test aspects of a Cockroach cluster on a single host.
config
Package config is a generated protocol buffer package.
Package config is a generated protocol buffer package.
gossip
Package gossip implements a protocol for sharing information between Cockroach nodes using an ad-hoc, peer-to-peer network.
Package gossip implements a protocol for sharing information between Cockroach nodes using an ad-hoc, peer-to-peer network.
internal/client
Package client and its KV API has been deprecated for external usage.
Package client and its KV API has been deprecated for external usage.
internal/rsg/yacc
Package yacc parses .y files.
Package yacc parses .y files.
kv
Package kv provides a key-value API to an underlying cockroach datastore.
Package kv provides a key-value API to an underlying cockroach datastore.
roachpb
Package roachpb is a generated protocol buffer package.
Package roachpb is a generated protocol buffer package.
rpc
Package rpc is a generated protocol buffer package.
Package rpc is a generated protocol buffer package.
security/securitytest
Package securitytest embeds the TLS test certificates.
Package securitytest embeds the TLS test certificates.
server
Package server implements the Cockroach storage node.
Package server implements the Cockroach storage node.
server/serverpb
Package serverpb is a generated protocol buffer package.
Package serverpb is a generated protocol buffer package.
server/status
Package status is a generated protocol buffer package.
Package status is a generated protocol buffer package.
sql
Package sql provides the user-facing API for access to a Cockroach datastore.
Package sql provides the user-facing API for access to a Cockroach datastore.
sql/distsqlrun
Package distsqlrun is a generated protocol buffer package.
Package distsqlrun is a generated protocol buffer package.
sql/sqlbase
Package sqlbase is a generated protocol buffer package.
Package sqlbase is a generated protocol buffer package.
storage
Package storage is a generated protocol buffer package.
Package storage is a generated protocol buffer package.
storage/engine
Package engine provides low-level storage.
Package engine provides low-level storage.
storage/engine/enginepb
Package enginepb is a generated protocol buffer package.
Package enginepb is a generated protocol buffer package.
storage/storagebase
Package storagebase is a generated protocol buffer package.
Package storagebase is a generated protocol buffer package.
ts
Package ts provides a basic time series datastore on top of the underlying CockroachDB key/value datastore.
Package ts provides a basic time series datastore on top of the underlying CockroachDB key/value datastore.
ts/tspb
Package tspb is a generated protocol buffer package.
Package tspb is a generated protocol buffer package.
ui
Package ui embeds into the Cockroach certain data such as web html and stylesheets.
Package ui embeds into the Cockroach certain data such as web html and stylesheets.
util
Package util is a generated protocol buffer package.
Package util is a generated protocol buffer package.
util/hlc
Package hlc implements the Hybrid Logical Clock outlined in "Logical Physical Clocks and Consistent Snapshots in Globally Distributed Databases", available online at http://www.cse.buffalo.edu/tech-reports/2014-04.pdf.
Package hlc implements the Hybrid Logical Clock outlined in "Logical Physical Clocks and Consistent Snapshots in Globally Distributed Databases", available online at http://www.cse.buffalo.edu/tech-reports/2014-04.pdf.
util/interval
Package interval implements an interval tree based on an augmented Left-Leaning Red Black tree.
Package interval implements an interval tree based on an augmented Left-Leaning Red Black tree.
util/leaktest
Package leaktest provides tools to detect leaked goroutines in tests.
Package leaktest provides tools to detect leaked goroutines in tests.
util/log
Package log implements logging analogous to the Google-internal C++ INFO/ERROR/V setup.
Package log implements logging analogous to the Google-internal C++ INFO/ERROR/V setup.
util/metric
Package metric provides server metrics (a.k.a.
Package metric provides server metrics (a.k.a.
util/sdnotify
Package sdnotify implements both sides of the systemd readiness protocol.
Package sdnotify implements both sides of the systemd readiness protocol.
util/tracing
Package tracing is a generated protocol buffer package.
Package tracing is a generated protocol buffer package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL