weverkley/bucardo repository overview

⁠Bucardo

This repository provides a Docker image for Bucardo⁠, a powerful asynchronous multi-master replication system for PostgreSQL. The image is based on Ubuntu and is automatically built and published to Docker Hub.

GitHub: weverkley/bucardo_docker_image⁠

⁠Table of Contents

• Features⁠
• Usage⁠
  • Configuration (bucardo.json)⁠
  • Running the Container
    • Using docker run
    • Using docker-compose
• Customizing the Build
• Configuration Details
  • The databases object
  • The syncs object
• Acknowledgements
• Copyright and License⁠

⁠Features

• Declarative Configuration: Define all your databases and synchronization tasks in a single bucardo.json file.
• Environment Variable Support: Keep your database passwords secure by loading them from environment variables.
• Flexible Sync Definitions: Sync all tables from a source (herd) or specify a list of tables (tables).
• Automated Setup: The container automatically configures Bucardo on startup based on your JSON file.

⁠Usage

⁠Configuration (bucardo.json)

First, create a bucardo.json configuration file. The container will mount and read this file on startup.

{
  "databases":[
    {
      "id": 3,
      "dbname": "example_db",
      "host": "host0.example.com",
      "user": "example_user",
      "pass": "secret",
      "port": 5432
    },{
      "id": 1,
      "dbname": "example_db",
      "host": "host1.example.com",
      "user": "example_user",
      "pass": "secret",
      "port": 5432
    },{
      "id": 2,
      "dbname": "example_db",
      "host": "host3.example.com",
      "user": "example_user",
      "pass": "secret",
      "port": 5432
    }],
  "syncs" : [
    {
      "sources": [3],
      "targets": [1,2],
      "herd": "all_from_source",
      "onetimecopy": 1
    },{
      "sources": [1,2],
      "targets": [3],
      "tables": "product, order",
      "onetimecopy": 0
    }
  ]
}

• Inside databases, describe all databases you desire to sync as a source and/or as a target;

• The ID attribute must be a unique integer per database, and has nothing to do your database but the way the container will identify it;

• Once your databases are described, you must describe your syncs;

• Each sync must have one or more sources, and one or more targets; and these have to be described following JSON standard Array notation;

• Each entity inside the sources and targets arrays represents an ID referring to the databases described beforehand;

• You must define what to sync. You can either use herd or tables:

  • herd: Provide a string with a name for the herd. All tables from the first source database will be added to this herd and synchronized.
  • tables: A string containing a comma-separated list of tables to be synchronized.

• Onetimecopy⁠ is used for full table copy:

  • 0 No full copy is done
  • 1 A full table copy is always performed
  • 2 A full copy is done in case the destination table is empty

1. Start the container:

docker run --name my_own_bucardo_container \
  -v <bucardo.json dir>:/media/bucardo \
  -d weverkley/bucardo

1. Check bucardo's status:

docker logs my_own_bucardo_container -f

⁠How to use it (env-based passwords)

Same as before. The only difference is:

• In the JSON database definition, type "env" for password instead of the database user password;

• When you create a container, inform the password as a environment variable named BUCARDO_DB, where ID is the ID you defined earlier in the bucardo.json:

  docker run --name my_own_bucardo_container \
      -v <bucardo.json dir>:/media/bucardo \
      -e BUCARDO_DB3="secret" \
      -d weverkley/bucardo
  

  Copy

⁠Acknowlegments

This image uses the following software components:

• Ubuntu 22.04;
• PostgreSQL 14;
• Bucardo;
• JQ.

⁠Copyright and License

This project is copyright 2025 Wever Kley [email protected]⁠.
Licensed under Apache 2.0 License.
Check the license file for details.