Bbolt to Postgres Migration

Bindplane BBolt store has been deprecated since February 2025 and will be removed in January 2026. Follow these steps to migrate to Postgres as soon as possible.

Objective

Export resources from a Bindplane project using a BBolt backing database and import them into the same project, but with a Postgres backing database.

Prerequisites

The following requirements must be met:

• Bindplane v1.98.0 or newer. If on an older version, upgrade before attempting a migration.

Procedure

The migration procedure has the following steps:

1. Install and Configure Postgres

2. Stop the Bindplane service

3. Backup the bbolt database file

4. Configure Bindplane Postgres Store

5. Run the migration command

6. Start the service

1. Install Postgres

Follow the Postgres Installation Guide and the Postgres Configuration documentation for Postgres installation and configuration instructions.

2. Stop the Bindplane service

The Postgres migration requires Bindplane to be stopped. Managed collectors will continue to operate their configuration.

sudo systemctl stop bindplane

3. Backup the BBOLT Database file

To be safe, backup the bbolt database file. In this example, the database file is copied to the root user's home directory.

sudo cp /var/lib/bindplane/storage/bindplane.db ~/bindplane.db.bak

4. Configure Bindplane Postgres Store

Edit /etc/bindplane/config.yaml with your text editor of choice. Update store.type to postgres. Add the store.postgres options with your Postgres host, port, database, username, and password. Leave all other store options in place.

store:
  type: postgres
  postgres:
    host: localhost
    port: "5432"
    database: bindplane
    username: bindplane
    password: your_password

5. Migration Command

After updating the configuration file, run the migrate-store command. Root permissions are required in order to read the Bindplane server's configuration file. The migrate command will copy resources from the bbolt database file to the configured Postgres database.

sudo bindplane migrate-store --config /etc/bindplane/config.yaml

The migration is succesful if the output looks like this:

Performing migration from boltstore to postgres
Checking if database is empty... Done
Seeding eula versions... Done
Migrating eulas... Done
Migrating accounts... Done
Migrating users... Done
Migrating resource store... Done
Migrating library resources... Done
Migrating configs... Done
Migrating agent resources... Done
Migrating api keys... Done
Migrating agents... Done
Successfully performed database migration

6. Start Bindplane

With Bindplane configured to use Postgres and the migration complete, you can start the service.

sudo systemctl start bindplane
sudo systemctl status bindplane

Validate

Log into the Bindplane project and ensure the configurations and destinations are present.

If you need to access the BBolt server, you can set store.type back to bbolt and restart the server to see the changes take effect.

Previously connected collectors will need to be updated with the new project's secret key. Follow the Migrate Collectors documentation.

Troubleshooting

Logging

If you encounter issues, please review the log output for the service:

• sudo journalctl -f --unit bindplane

• sudo tail -F /var/log/bindplane/bindplane.log

Re-run Migration

If you need to re-run the migrate-store command, you can safely drop the database and start over.

1. Log into Postgres and run DROP DATABASE bindplane;

2. Follow the Postgres Configuration procedure again, to re-create the database and assign permissions

3. Re-run the migration command.