Skip to content
Learni
Voir tous les tutoriels
Bases de données

Comment installer et utiliser CockroachDB en 2026

12 minBEGINNER
Base de donnéesDockerNode.jsCockroachDBSQL distribué
Read in English

Introduction

CockroachDB est une base de données SQL distribuée, conçue pour la résilience et la scalabilité horizontale, compatible à 100% avec PostgreSQL. Contrairement aux bases traditionnelles comme MySQL qui peinent à scaler, CockroachDB répartit les données sur plusieurs nœuds sans point de défaillance unique, comme un essaim d'abeilles où chaque abeille peut prendre le relais.

En 2026, avec l'essor des apps cloud-native et microservices, elle est essentielle pour les devs qui veulent des DB géo-réparties avec forte disponibilité. Ce tutoriel débutant vous emmène de l'installation locale via Docker à la connexion d'une app Node.js, en passant par des requêtes SQL concrètes. À la fin, vous maîtriserez un setup production-ready en insecure mode pour tests. Importance : zéro downtime lors de pics de trafic, survival queries même si un nœud crash. Prêt à plonger dans le monde des DB distributed ? (128 mots)

Prérequis

  • Docker installé et lancé (version 20+).
  • Connaissances de base en SQL (SELECT, INSERT).
  • Node.js 18+ pour l'exemple d'app (optionnel).
  • Terminal Unix-like (WSL sur Windows).
  • 2 Go de RAM libre pour le conteneur.

Installation de CockroachDB via Docker

terminal-install.sh
docker run -d \
  --name=cockroachdb \
  -p 26257:26257 \
  -p 8080:8080 \
  -v $(pwd)/cockroach-data:/cockroach/cockroach-data \
  cockroachdb/cockroach:v24.1.0 start-single-node \
  --insecure \
  --listen-addr=0.0.0.0

Ce script lance un nœud unique CockroachDB en mode insecure (pour dev seulement) sur les ports 26257 (SQL) et 8080 (UI). Le volume persiste les données localement. Évitez --insecure en prod ; utilisez des certs. Vérifiez avec docker ps que le conteneur tourne.

Accès à l'interface web et vérification

Ouvrez http://localhost:8080 dans votre navigateur. Vous verrez le dashboard CockroachDB avec métriques en temps réel : CPU, stockage, queries/sec. Cliquez sur Explore pour voir les tables système.

Si le conteneur ne démarre pas, vérifiez les logs : docker logs cockroachdb. Analogie : c'est comme le cockpit d'un avion, tout est monitoré. Prochaine étape : shell SQL.

Connexion au shell SQL interactif

terminal-sql-shell.sh
docker exec -it cockroachdb \
  ./cockroach sql \
  --insecure \
  -e "SHOW DATABASES;"

On exécute le shell cockroach sql dans le conteneur pour lister les DB système (defaultdb, information_schema, etc.). L'option -e exécute une commande unique. Pour un shell interactif, omettez -e. Quittez avec \q. Piège : sans --insecure, certs requis.

Création de la base, table et utilisateur

setup.sql
CREATE DATABASE bank;

USE bank;

CREATE TABLE accounts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  balance INT NOT NULL DEFAULT 0,
  created_at TIMESTAMP DEFAULT now()
);

CREATE USER maxroach PASSWORD 'testpass';

GRANT ALL ON DATABASE bank TO maxroach;

GRANT ALL ON TABLE accounts TO maxroach;

Ce script crée une DB bank, une table accounts avec UUID auto-généré (idéal pour distributed), un user maxroach. Exécutez-le via docker exec -it cockroachdb ./cockroach sql --insecure < setup.sql. Pourquoi UUID ? Évite conflits lors de sharding. Vérifiez : SHOW TABLES;. Ne pas oublier GRANT pour l'app.

Insertion et lecture de données

Testez vos insertions : Imaginez une banque où les soldes se mettent à jour en temps réel sur plusieurs data centers. Exécutez les queries suivantes dans le shell pour peupler la table.

Insertion et requête de données

data.sql
USE bank;

INSERT INTO accounts (balance) VALUES (1000), (2500);

SELECT id, balance, created_at FROM accounts;

UPDATE accounts SET balance = balance + 500 WHERE id = (SELECT id FROM accounts LIMIT 1);

SELECT SUM(balance) FROM accounts;

On insère 2 comptes, lit tout, met à jour le premier (+500), et somme les soldes. Résultat attendu : 2 lignes initiales, puis somme 4000. CockroachDB gère les transactions ACID distribuées. Piège : pas de RETURNING ici, mais disponible comme Postgres.

Connexion depuis une app Node.js

Pour intégrer dans du code, utilisons le client pg (compatible Postgres). Créez un dossier node-app, initialisez npm.

Installation et script Node.js complet

terminal-node-setup.sh
mkdir node-app && cd node-app
npm init -y
npm install pg
npm install -g ts-node typescript @types/pg

Initialise un projet Node avec pg pour se connecter. TypeScript optionnel pour typage. Lancez ensuite le script TS suivant. Ports ouverts : 26257 pour TCP SQL.

App Node.js connectée à CockroachDB

app.ts
import { Client } from 'pg';

const client = new Client({
  host: 'localhost',
  port: 26257,
  database: 'bank',
  user: 'maxroach',
  password: 'testpass',
  ssl: false,
});

async function main() {
  await client.connect();
  console.log('Connecté à CockroachDB !');

  const res = await client.query('SELECT * FROM accounts');
  console.log('Comptes:', res.rows);

  await client.query('INSERT INTO accounts (balance) VALUES ($1)', [999]);
  console.log('Nouveau compte ajouté');

  await client.end();
}

main().catch(console.error);

Ce script TS complet se connecte, query la table, insère un compte. Lancez avec ts-node app.ts. ssl: false pour insecure. En prod, activez SSL et connection pooling. Vérifiez logs : liste comptes + nouveau ID UUID.

Bonnes pratiques

  • Toujours utiliser UUID ou SERIAL pour PK : Évite les collisions lors de scaling multi-nœuds.
  • Activez la sécurité : Remplacez --insecure par --certs-dir en prod.
  • Surveillez via UI : Consultez /#/metrics pour détecter les hotspots.
  • Backups automatisés : BACKUP INTO 's3://...' pour résilience.
  • Connection pooling : Utilisez pg-pool pour >100 connexions simultanées.

Erreurs courantes à éviter

  • Port 26257 bloqué : Vérifiez firewall ; docker run expose-le explicitement.
  • Mode insecure en prod : Exposé aux attaques ; générez certs avec cockroach cert.
  • Oubli de volume Docker : Données perdues au restart ; montez toujours -v.
  • Transactions longues : Timeout distribué ; batcher les inserts (>1000 rows ralentit).

Pour aller plus loin