分散 SQL データベースとして注目される CockroachDB は、ノードを追加するだけで水平スケールアウトでき、PostgreSQL 互換の SQL 文がそのまま使えます。開発・ステージング環境では --insecure モードで即座に起動でき、ブラウザ内蔵の AdminUI でクラスタ状態をリアルタイム確認できます。
この記事では Ubuntu 24.04 LTS に CockroachDB v24.2.10 を実際にインストールし、シングルノード起動・SQL 操作・AdminUI 確認まで実測した結果をそのまま載せます。
この記事のポイント
- CockroachDB v24.2.10 は公式バイナリ（約103MB）1本でインストールできる
cockroach start-single-node --insecureでポート 26257（SQL）＋ 8080（AdminUI）が即起動- PostgreSQL 互換なので
psqlや既存のドライバがほぼそのまま使える - AdminUI にはブラウザから
http://サーバーIP:8080でアクセスでき、ノード状態・SQLメトリクスを確認できる unique_rowid()による大きな整数の ID が生成される点が PostgreSQL のSERIALと異なる
目次
CockroachDB とは
CockroachDB は Cockroach Labs が開発する分散 SQL データベースです。名前の由来は「ゴキブリのように生き残る」——つまり一部のノードが落ちても自動でフェイルオーバーしてデータが守られる、という設計思想から来ています。
最大の特徴はノードを追加するだけでスケールアウトできる点です。PostgreSQL のようにプライマリ＋レプリカという構成を手作業で管理するのではなく、CockroachDB はデータを自動的に分割（シャーディング）してノード間に分散します。データのレプリカは Raft 合意アルゴリズムで同期されるので、1〜2ノードが落ちても残りのノードで処理を継続できます。
開発・テスト用途では --insecure モードという認証なしモードがあり、設定ファイルを一切書かずに起動できます。正直、PostgreSQL より最初の一歩は楽です。本番環境では TLS 証明書を使った --certs-dir 構成が必要なので、この記事で扱う insecure モードはあくまで学習・開発用の起動方法です。
動作確認済み環境
PRETTY_NAME=”Ubuntu 24.04.4 LTS”
$ uname -r
6.8.0-83-generic
$ uname -m
x86_64
| 項目 | バージョン・詳細 |
|---|---|
| OS | Ubuntu 24.04.4 LTS (Noble Numbat) |
| カーネル | 6.8.0-83-generic (x86_64) |
| CockroachDB | v24.2.10（2025/02/03 ビルド） |
| インストール方法 | 公式バイナリ（linux amd64） |
| Go（ビルド時） | go1.22.5 |
| 起動モード | start-single-node –insecure（開発・検証用） |
インストール手順
CockroachDB は公式の apt リポジトリを持ちません。インストールは公式バイナリを curl でダウンロードして /usr/local/bin に配置する方式です。
手順1：curl のインストール確認
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0
Ubuntu 24.04 には最初から curl 8.5.0 が入っています。
手順2：CockroachDB バイナリをダウンロード
% Total % Received % Xferd Average Speed Dload Upload Total Spent Left Speed
100 103M 100 103M 0 0 12.8M 0 0:00:08 0:00:08 –:–:– 13.1M
約103MBのアーカイブをダウンロードします。回線によって1〜数分かかります。
手順3：解凍してパスに配置
$ sudo cp -i cockroach-v24.2.10.linux-amd64/cockroach /usr/local/bin/
$ cockroach version
Build Tag: v24.2.10
Build Time: 2025/02/03 17:30:12
Distribution: CCL
Platform: linux amd64 (x86_64-pc-linux-gnu)
Go Version: go1.22.5 X:nocoverageredesign
Build Type: release
cockroach version で Build Tag: v24.2.10 と表示されれば、インストール成功です。
シングルノードで起動する
開発・検証目的なら start-single-node --insecure コマンド1行で起動します。TLS 証明書の設定もパスワードも不要なので、手順書通りに動かすのに向いています。
注意：insecure モードは本番環境で使わない
--insecure フラグは認証なしのアクセスを許可します。学習・開発・ローカル検証専用です。本番環境では --certs-dir を使った TLS 構成が必要です。ファイアウォールで 26257 と 8080 ポートを必ず制限してください。
手順4：バックグラウンドで起動
–insecure \
–listen-addr=:26257 \
–http-addr=:8080 \
–background
CockroachDB node starting at 2026-06-20 07:54:33.699952 +0000 UTC
build: CCL v24.2.10 @ 2025/02/03 17:30:12
webui: http://127.0.0.1:8080
sql: postgresql://root@127.0.0.1:26257/defaultdb?sslmode=disable
オプションの意味：
--listen-addr=:26257— SQL 接続を受け付けるポート（PostgreSQL 互換）--http-addr=:8080— AdminUI（ブラウザ管理画面）のポート--background— デーモンとしてバックグラウンド起動
手順5：ノード状態を確認
id address sql_address build started_at is_available is_live
1 127.0.0.1:26257 127.0.0.1:26257 v24.2.10 2026-06-20 07:54:33.699952 UTC true true
起動後8〜10秒で is_available: true / is_live: true に変わります。私の環境では約8秒で SQL 接続できる状態になりました。
AdminUI にアクセスする
CockroachDB を起動すると、ポート 8080 にAdminUI というブラウザ管理画面が自動で起動します。コマンドラインだけでは分かりにくいクラスタ状態、SQL 実行統計、レンジの分布などがグラフで確認できます。
ブラウザで http://localhost:8080（リモートサーバーなら http://サーバーIP:8080）にアクセスします。
Overview ページには SQL Statements / Transactions per Second・Latency・Node の状態がリアルタイムで表示されます。起動直後はほとんどゼロですが、SQL を実行するとグラフが動きます。
Cluster タブにはノード一覧が表示されます。シングルノード構成では1行だけ表示され、LIVE 状態になっていれば正常です。
Databases ページでは作成したデータベース・テーブル・インデックスをブラウザ上で確認できます。コマンドを打たなくてもテーブル定義が見られるのは意外と便利でした。
SQL Metrics ページは、実行中のクエリ数・エラー率・トランザクション待機時間などが秒単位で更新されます。パフォーマンス調査時に真っ先に見るページです。
SQL Statements ページには過去に実行された SQL 文の一覧、実行回数、レイテンシ統計が表示されます。どのクエリが重いか一目で分かります。
基本的な SQL 操作
CockroachDB は PostgreSQL 互換なので、cockroach sql コマンドで接続するか、psql や既存の PostgreSQL ドライバで接続できます。
cockroach sql シェルで接続
# Welcome to the CockroachDB SQL shell.
# Server version: CockroachDB CCL v24.2.10
root@:26257/defaultdb>
データベース・テーブル作成とデータ操作
CREATE DATABASE
root@:26257/defaultdb> USE testdb;
SET
root@:26257/testdb> CREATE TABLE users (
-> id INT PRIMARY KEY DEFAULT unique_rowid(),
-> name STRING NOT NULL,
-> email STRING UNIQUE,
-> created_at TIMESTAMP DEFAULT now()
-> );
CREATE TABLE
root@:26257/testdb> INSERT INTO users (name, email) VALUES
-> (‘田中太郎’, ‘tanaka@example.com’),
-> (‘山田花子’, ‘yamada@example.com’),
-> (‘鈴木一郎’, ‘suzuki@example.com’);
INSERT 0 3
root@:26257/testdb> SELECT id, name, email FROM users ORDER BY id;
id | name | email
———————+———-+————————
1185781127087194113 田中太郎 tanaka@example.com
1185781127087325185 山田花子 yamada@example.com
1185781127087357953 鈴木一郎 suzuki@example.com
(3 rows)
実際に動かして気づいた点として、unique_rowid() が生成する ID は PostgreSQL の SERIAL とは全く違う大きな整数（18桁）になります。これは分散環境でも一意なIDを生成するための仕様で、1185781127087194113 のような値です。既存のシステムから移行する場合、アプリケーション側で ID 型の確認が必要です。
psql での接続（PostgreSQL 互換確認）
psql (PostgreSQL) 16.14 (Ubuntu 16.14-0ubuntu0.24.04.1)
$ psql “postgresql://root@localhost:26257/testdb?sslmode=disable”
psql (16.14 (Ubuntu 16.14-0ubuntu0.24.04.1), server 13.0.0)
testdb=>
Ubuntu の psql クライアント（PostgreSQL 16.14）から接続できました。CockroachDB はサーバーバージョン 13 を名乗って接続を受け付けます。既存の PostgreSQL ライブラリが多くそのまま使える理由がここにあります。
クラスタ状態の確認
SHOW DATABASES で構成確認
database_name owner primary_region secondary_region regions survival_goal
defaultdb root NULL NULL {} NULL
postgres root NULL NULL {} NULL
system node NULL NULL {} NULL
testdb root NULL NULL {} NULL
初期状態では defaultdb / postgres / system の3つがあります。先ほど作成した testdb も確認できます。regions が空なのは、シングルノード構成（リージョン設定なし）のためです。
ホスト環境のパフォーマンス確認
CockroachDB を動かすホスト環境の sysbench CPU ベンチを測定しました。ubuntu:24.04 コンテナで sysbench cpu --threads=2 --time=10 を3回実行した結果は平均 13,857.8 events/sec（最小13,834.5、最大13,869.7）でした。実際の CockroachDB のスループットはワークロードによりますが、ホスト CPU 性能の指標として参考にしてください。
よくあるエラーと解決策
①「hostname of listen_addr must be 127.0.0.1 or localhost」
--listen-addr=0.0.0.0 や --listen-addr=192.168.x.x など具体的な IP アドレスを指定すると出るエラーです。正しくは --listen-addr=:26257（ポート番号のみ）と書きます。私も最初これで詰まりました。
②「ERROR: connection refused (localhost:26257)」
起動直後すぐに cockroach sql を打つと出ることがあります。起動後10秒ほど待ってから接続してください。cockroach node status --insecure で is_live: true を確認してから SQL 操作に進むのが確実です。
③ポート 8080 が他のサービスと競合する
Jenkins や Jupyter Notebook など 8080 を使うサービスと競合する場合は --http-addr=:9090 のように別ポートを指定できます。
ポートが競合するとき
既に 8080 を使っているサービスがある場合は --http-addr=:9090 のように別ポートを指定してください。cockroach start-single-node --insecure --listen-addr=:26257 --http-addr=:9090 --background で起動し、AdminUI は http://localhost:9090 でアクセスします。
④「unique_rowid() の ID が大きすぎる」
PostgreSQL の SERIAL（1, 2, 3…）に慣れていると驚きますが、これは正常動作です。分散ノード間でのID衝突を防ぐために大きな整数が使われています。連番に近いものが欲しければ SEQUENCE を使うか、UUID 型を採用する方法もあります。
まとめ
Ubuntu 24.04 での CockroachDB v24.2.10 のセットアップと動作確認をまとめます。
- インストールは公式バイナリ1本（約103MB）を
/usr/local/binに置くだけ start-single-node --insecure --listen-addr=:26257 --http-addr=:8080で SQL + AdminUI が同時起動- 起動後8〜10秒で
is_live: trueになり SQL 接続可能 - PostgreSQL の
psqlクライアントでも接続でき、標準 SQL 文がそのまま動作 unique_rowid()による 18 桁の ID は分散設計の特性——既存システム移行時は要確認- AdminUI（:8080）でノード状態・SQL メトリクス・ステートメント統計をリアルタイム確認できる
個人開発・学習用なら insecure モードで手軽に試せます。本格的なクラスタ構成（3ノード以上）や TLS 認証に進む前に、まずシングルノードで SQL 操作と AdminUI の感覚を掴むのが遠回りのようで近道です。
VPS 上で CockroachDB を動かすなら、Vultr の 2GB プランあたりが余裕を持って動作します。メモリが 1GB を切ると起動時に OOM で落ちることがあるので注意。
Docker でサーバーを管理したい方はUbuntu への Docker インストール記事も参照してください。VPS の初期設定はUbuntuサーバーVPS初期設定ガイドが参考になります。
コメント