Skip to main content

​
Overview

This guide will walk you through starting a local CockroachDB cluster, connecting to it, and running your first SQL commands. You’ll have a working database in less than 10 minutes.
This quickstart uses a single-node cluster for development and testing. For production deployments, see the Installation Guide.

​
Prerequisites

  • A supported operating system (Linux, macOS, or Windows)
  • At least 2GB of available RAM
  • Terminal or command prompt access
1

Download CockroachDB

Download the latest CockroachDB binary for your platform:
curl https://binaries.cockroachdb.com/cockroach-latest.darwin-10.9-amd64.tgz | tar -xz
sudo cp -i cockroach-latest.darwin-10.9-amd64/cockroach /usr/local/bin/
Verify the installation:
cockroach version
2

Start a Single-Node Cluster

Start CockroachDB in insecure mode (for development only):
cockroach start-single-node --insecure --listen-addr=localhost:26257 --http-addr=localhost:8080
You should see output indicating the node is running:
CockroachDB node starting at 2024-03-03 12:00:00
build:               CCL v24.3.0
webui:               http://localhost:8080
sql:                 postgresql://root@localhost:26257/defaultdb?sslmode=disable
Keep this terminal window open. The node will continue running until you stop it with Ctrl+C.
What’s happening:
  • start-single-node: Starts a single-node cluster (automatically initializes)
  • --insecure: Runs without SSL/TLS (development only)
  • --listen-addr: SQL and RPC connections address
  • --http-addr: Admin UI address
3

Access the Admin UI

Open your browser and navigate to:
http://localhost:8080
The Admin UI provides:
  • Cluster health and metrics
  • Database and table information
  • Query performance statistics
  • Node details and topology
No authentication is required in insecure mode. For production, always use secure mode with proper certificates.
4

Open the SQL Shell

In a new terminal window, connect to the cluster using the built-in SQL client:
cockroach sql --insecure --host=localhost:26257
You’ll see a welcome message:
#
# Welcome to the CockroachDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
root@localhost:26257/defaultdb>
5

Run Your First SQL Commands

Let’s create a database, table, and insert some data:
CREATE DATABASE bank;
USE bank;
Expected output:
                   id                    | balance  |         created_at
-----------------------------------------+----------+-----------------------------
  5a4e4a3b-7c2d-4f8e-9a1c-3d2e1f0b5c6a | 1000.50  | 2024-03-03 12:05:32.123456
  7b5f5b4c-8d3e-5f9f-0b2d-4e3f2a1c6d7b | 2500.00  | 2024-03-03 12:05:32.123457
  9c6a6c5d-9e4f-6a0a-1c3e-5f4a3b2d7e8c | 750.25   | 2024-03-03 12:05:32.123458
(3 rows)
6

Try Advanced Features

CockroachDB supports advanced SQL features:
BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE balance > 1000;
UPDATE accounts SET balance = balance + 100 WHERE balance < 800;
COMMIT;

​
Common SQL Shell Commands

The CockroachDB SQL shell supports special commands: 
\q                  -- Exit the SQL shell
\d                  -- List all tables
\d table_name       -- Describe a table
\dt                 -- List all tables (PostgreSQL compatible)
\l                  -- List all databases
\c database_name    -- Connect to a database
\!                  -- Execute a shell command

​
Testing Distributed Transactions

Even in a single-node cluster, you can see CockroachDB’s transaction handling: 
-- Start a transaction
BEGIN;

-- Make changes
UPDATE accounts SET balance = balance + 100 WHERE balance < 1000;

-- Check the changes (visible only in this transaction)
SELECT * FROM accounts;

-- Roll back if needed
ROLLBACK;

-- Or commit to apply changes
COMMIT;
All transactions in CockroachDB are serializable by default, preventing anomalies like dirty reads, non-repeatable reads, and phantom reads.

​
Next Steps

Multi-Node Cluster

Start a local multi-node cluster to see replication in action

Production Installation

Deploy CockroachDB for production use

Build an App

Connect your application using client drivers

Learn SQL

Master CockroachDB SQL features and best practices

​
Stopping the Cluster

To stop the cluster:
  1. In the terminal running CockroachDB, press Ctrl+C
  2. Wait for the graceful shutdown to complete
# Clean up data (optional)
rm -rf cockroach-data/
Pro tip: For persistent development, keep your data directory and restart with the same command. Your data will be preserved.

​
Troubleshooting

If ports 26257 or 8080 are already in use, specify different ports:
cockroach start-single-node --insecure \
  --listen-addr=localhost:26258 \
  --http-addr=localhost:8081
Ensure the cluster is running and you’re connecting to the correct host and port:
cockroach sql --insecure --host=localhost:26257
CockroachDB requires sufficient disk space. Check available space:
df -h
Specify a custom store location if needed:
cockroach start-single-node --insecure --store=/path/to/storage

Build docs developers (and LLMs) love

Get started for freeTalk to us