README

CockroachDB is a cloud-native SQL database for building global, scalable cloud services that survive disasters.

TeamCity CI GoDoc Version 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 production-ready. See our 1.1 milestone 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 CockroachDB.

  2. Start a local cluster and talk to it via the built-in SQL client.

  3. Learn more about CockroachDB SQL.

  4. Use a PostgreSQL-compatible driver or ORM to build an app with CockroachDB.

  5. Explore core features, such as data replication, automatic rebalancing, and fault tolerance and recovery.

Client Drivers

CockroachDB supports the PostgreSQL wire protocol, so you can use any available PostgreSQL client drivers to connect from various languages.

Deployment

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

  • Cloud Deployment - Guides for deploying CockroachDB on various cloud platforms.

  • Orchestration - Guides for running CockroachDB with popular open-source orchestration systems.

Need Help?

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 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 on our website.

See Also

Expand ▾ Collapse ▴

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

Directories

Path Synopsis
pkg/acceptance
pkg/acceptance/cluster Package cluster is a generated protocol buffer package.
pkg/acceptance/localcluster
pkg/acceptance/localcluster/tc Package tc contains utility methods for using the Linux tc (traffic control) command to mess with the network links between cockroach nodes running on the local machine.
pkg/acceptance/terrafarm
pkg/base
pkg/build Package build is a generated protocol buffer package.
pkg/ccl
pkg/ccl/buildccl
pkg/ccl/cliccl
pkg/ccl/sqlccl Package sqlccl is a generated protocol buffer package.
pkg/ccl/storageccl
pkg/ccl/storageccl/engineccl
pkg/ccl/utilccl
pkg/ccl/utilccl/intervalccl
pkg/ccl/utilccl/licenseccl Package licenseccl is a generated protocol buffer package.
pkg/ccl/utilccl/sampledataccl
pkg/cli
pkg/cli/cliflags
pkg/cmd/allocsim
pkg/cmd/benchmark
pkg/cmd/cockroach-oss
pkg/cmd/docgen
pkg/cmd/generate-binary This connects to a postgres server and crafts postgres-protocol message to encode its arguments into postgres' binary encoding.
pkg/cmd/github-post
pkg/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.
pkg/cmd/gossipsim Package simulation provides tools meant to visualize or test aspects of a Cockroach cluster on a single host.
pkg/cmd/metacheck
pkg/cmd/protoc-gen-gogoroach
pkg/cmd/publish-artifacts
pkg/cmd/returncheck
pkg/cmd/teamcity-trigger
pkg/cmd/urlcheck
pkg/cmd/urlcheck/lib/urlcheck
pkg/cmd/zerosum
pkg/config Package config is a generated protocol buffer package.
pkg/gossip Package gossip implements a protocol for sharing information between Cockroach nodes using an ad-hoc, peer-to-peer network.
pkg/gossip/resolver
pkg/gossip/simulation
pkg/internal/client Package client and its KV API have been deprecated for external usage.
pkg/internal/rsg
pkg/internal/rsg/yacc Package yacc parses .y files.
pkg/keys
pkg/kv Package kv provides a key-value API to an underlying cockroach datastore.
pkg/roachpb Package roachpb is a generated protocol buffer package.
pkg/rpc Package rpc is a generated protocol buffer package.
pkg/security
pkg/security/securitytest Package securitytest embeds the TLS test certificates.
pkg/server Package server implements the Cockroach storage node.
pkg/server/diagnosticspb Package diagnosticspb is a generated protocol buffer package.
pkg/server/serverpb Package serverpb is a generated protocol buffer package.
pkg/server/status Package status is a generated protocol buffer package.
pkg/settings Package settings provides a central registry of runtime editable settings and accompanying helper functions for retrieving their current values.
pkg/settings/cluster Package cluster is a generated protocol buffer package.
pkg/sql Package sql provides the user-facing API for access to a Cockroach datastore.
pkg/sql/distsqlplan
pkg/sql/distsqlrun Package distsqlrun is a generated protocol buffer package.
pkg/sql/ir/base
pkg/sql/ir/example/base
pkg/sql/ir/irgen
pkg/sql/ir/irgen/analyzer
pkg/sql/ir/irgen/codegen
pkg/sql/ir/irgen/ir
pkg/sql/ir/irgen/parser
pkg/sql/ir/irgen/template
pkg/sql/jobs Package jobs is a generated protocol buffer package.
pkg/sql/mon
pkg/sql/parser
pkg/sql/pgbench
pkg/sql/pgbench/cmd/pgbenchsetup
pkg/sql/pgwire
pkg/sql/pgwire/pgerror Package pgerror is a generated protocol buffer package.
pkg/sql/privilege
pkg/sql/sqlbase Package sqlbase is a generated protocol buffer package.
pkg/sql/sqlutil
pkg/sqlmigrations
pkg/storage Package storage is a generated protocol buffer package.
pkg/storage/engine Package engine provides low-level storage.
pkg/storage/engine/enginepb Package enginepb is a generated protocol buffer package.
pkg/storage/storagebase Package storagebase is a generated protocol buffer package.
pkg/testutils
pkg/testutils/buildutil
pkg/testutils/distsqlutils
pkg/testutils/gossiputil
pkg/testutils/localtestcluster
pkg/testutils/serverutils
pkg/testutils/sqlutils
pkg/testutils/storageutils
pkg/testutils/testcluster
pkg/testutils/zerofields
pkg/ts Package ts provides a basic time series datastore on top of the underlying CockroachDB key/value datastore.
pkg/ts/tspb Package tspb is a generated protocol buffer package.
pkg/ui Package ui embeds into the Cockroach certain data such as web html and stylesheets.
pkg/util Package util is a generated protocol buffer package.
pkg/util/bufalloc
pkg/util/cache
pkg/util/caller
pkg/util/duration
pkg/util/encoding
pkg/util/envutil
pkg/util/fileutil
pkg/util/grpcutil
pkg/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.
pkg/util/httputil
pkg/util/humanizeutil
pkg/util/interval Package interval provides two implementations for an interval tree.
pkg/util/leaktest Package leaktest provides tools to detect leaked goroutines in tests.
pkg/util/log Package log implements logging analogous to the Google-internal C++ INFO/ERROR/V setup.
pkg/util/log/logflags
pkg/util/metric Package metric provides server metrics (a.k.a.
pkg/util/netutil
pkg/util/protoutil
pkg/util/randutil
pkg/util/retry
pkg/util/sdnotify Package sdnotify implements both sides of the systemd readiness protocol.
pkg/util/shuffle
pkg/util/stop
pkg/util/syncutil
pkg/util/syncutil/singleflight Package singleflight provides a duplicate function call suppression mechanism.
pkg/util/timeutil
pkg/util/tracing Package tracing is a generated protocol buffer package.
pkg/util/uint128
pkg/util/uuid