Simple Guide: Local CockroachDB Backup and Restore Using Docker

Want to streamline your local CockroachDB development? This guide will show you how to easily back up and restore your CockroachDB database using Docker and a few simple commands. Learn how to manage your data and experiment fearlessly!

Automate CockroachDB Backup and Restore with Taskfile

Using Taskfile simplifies running common commands. We'll create tasks for backing up and restoring your local CockroachDB instance.

• Backup Task: Creates a backup of your local CockroachDB database.
• Restore Task: Restores your local CockroachDB database from a backup.

Here's a ready-to-use Taskfile.yml configuration:

version: 3
tasks:
  backup:
    desc: Backup the local CockroachDB database
    cmds:
      - task: backup-to
    vars:
      FOLDER: "backup/local-node-backup"
  restore:
    desc: Restore the local CockroachDB backup database
    cmds:
      - task: restore-from
    vars:
      FOLDER: "backup/local-node-backup"
  backup-to:
    requires:
      vars:
        - FOLDER
    cmds:
      - cmd: mkdir -p cockroach-extern
        ignore_error: true
      - |
        cockroach sql --insecure --host=localhost --port=26257 --execute="BACKUP INTO 'nodelocal://1/{{.FOLDER}}';"
  restore-from:
    requires:
      vars:
        - FOLDER
    cmds:
      - |
        cockroach sql --insecure --host=localhost --port=26257 --execute="DROP DATABASE IF EXISTS defaultdb;"
      - |
        cockroach sql --insecure --host=localhost --port=26257 --execute="RESTORE DATABASE defaultdb FROM LATEST IN 'nodelocal://1/{{.FOLDER}}';"

Docker Compose Setup for CockroachDB Development

Docker Compose simplifies managing multi-container applications. Below is the docker-compose.yml configuration to integrate local data folder in your CockroachDB setup.

services:
  crdb:
    image: cockroachdb/cockroach:latest-v25.1
    ports:
      - '26257:26257'
      - '8080:8080'
    command: start-single-node --insecure
    volumes:
      - crdb:/cockroach/cockroach-data
      - type: bind
        source: ./cockroach-extern
        target: /cockroach/cockroach-data/extern
volumes:
  crdb:

Binding a Local Folder to the CockroachDB Container

The critical part of the docker-compose.yml file is the volume binding. By binding a local folder, we enable easy access to backups.

- type: bind
  source: ./cockroach-extern
  target: /cockroach/cockroach-data/extern

This configuration maps the ./cockroach-extern folder on your host machine to the /cockroach/cockroach-data/extern directory inside the CockroachDB container. Any backups created within the container will be directly accessible in your local folder.

Simple Steps to Perform a CockroachDB Backup

Backing up your CockroachDB data is essential. Follow these steps for creating backups:

1. Execute the backup command:

   BACKUP TO 'nodelocal://1/cockroach-backup';
   

   Copy

2. What this command does:

   • This command instructs CockroachDB to back up all data.
   • The data will be stored into the cluster to the local directory of nodeID 1.
   • The backup will be stored under the cockroach-backup folder inside the /cockroach-data/extern directory.

3. Access Your Backup: After running the command, you'll find the backup data in the ./cockroach-extern/cockroach-backup folder on your local machine, thanks to the volume binding we set up earlier.

How to Restore a CockroachDB Database

Restoring your CockroachDB database is just as simple. If you want to create and restore database locally, follow these steps:

1. Run the restore command:

   RESTORE DATABASE defaultdb FROM LATEST IN 'nodelocal://1/cockroach-backup' WITH new_db_name = 'new_defaultdb';
   

   Copy

2. Understanding the restore:

   • The command restores the defaultdb database.
   • FROM LATEST tells CockroachDB to use the most recent backup in the specified directory.
   • WITH new_db_name = 'new_defaultdb' creates a new database named new_defaultdb with the restored data.

3. Access the Restored Database: After the restore is complete, connect to the new_defaultdb database to access your restored data.

Best Practices for Local CockroachDB Development Backups

• Regular Backups: Schedule regular backups to prevent data loss.
• Verify Backups: Occasionally restore a backup to a test environment to ensure data integrity.
• Automate the Process: Use Taskfile or similar tools to automate backup and restore procedures.
• Storage Considerations: For local development, storing backups on your local machine is fine. For production environments, consider using cloud storage solutions like AWS S3 or Google Cloud Storage.

By following this guide, you can confidently manage local CockroachDB backups and restores, making your development experience smoother.