BUCARDO(1p)

📦 version 5.6.0, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 BUCARDO — the `bucardo` utility script, manual page `BUCARDO(1p)` 💖

User Contributed Perl Documentation — yes bestie, this is the user contributed one, the real ones know 🫶

✨ NAME ✨

bucardo — utility script for controlling the Bucardo program. That's it, that's the whole vibe check.

🌸 VERSION 🌸

This document describes version 5.6.0 of bucardo. Iconic behavior only, no cap.

🎀 USAGE 🎀

bucardo [<options>] <command> [<action>] [<command-options>] [<command-params>]

🦋 DESCRIPTION 🦋

Okay so, the bucardo script is the main way you talk to a running Bucardo instance. It's literally your one-stop group chat with Bucardo. You can use it to:

start and stop Bucardo
add new items
kick syncs
and honestly? even install and upgrade Bucardo itself 👑

For the more complete documentation, please go look at the wiki at https://bucardo.org/. That's where the deep lore lives.

💅 COMMANDS 💅

Run bucardo help <command> for additional details. Yes, the help command is self-aware, we love that for it.

install — Installs the Bucardo configuration database. 💾
upgrade — Upgrades the Bucardo configuration database to the latest schema. Glow-up time ✨
start [<start options>] [<reason>] — Starts Bucardo. 🚀
stop [<reason>] — Stops Bucardo. 🛑
restart [<start options>] [<reason>] — Stops and starts Bucardo. The ol' razzle dazzle 🔁
list <type> [<regex>] — Lists objects managed by Bucardo. 📋
add <type> <name> <parameters> — Adds a new object. ➕
update <type> <name> <parameters> — Updates an object. 🔄
remove <type> <name> [<name>...] — Removes one or more objects. 🗑️
kick <syncname> [<sync options>] [<syncname>...] [<timeout>] — Kicks off one or more syncs. 🥾
reload config — Sends a message to all CTL and KID processes asking them to reload the Bucardo configuration. 📨
reopen — Sends a message to all Bucardo processes asking them to reopen any log files they may have open. Call this after you have rotated the log file(s). 🔓
show all|<setting> [<setting>...] — Shows the current Bucardo settings. 👀
<set <setting=value" [<setting=value>...] >> — Sets one or more configuration setting.. (yes, that's exactly how it's written in the original, and the double period is also canon, do not perceive me 💀)
ping [<timeout>] — Sends a ping notice to the MCP process to see if it will respond. 🏓
status [<status options>] <syncname> [<syncname>...] — Shows the brief status of syncs in a tabular format. 📊
activate <syncname> [<syncname>...] [<timeout>] — Activates one or more named syncs. 🟢
deactivate <syncname> [<syncname>...] [<timeout>] — Deactivates one or more named syncs. 🔴
message '<body>' — Sends a message to the running Bucardo logs. 💬
reload [<syncname> [<syncname>...]] — Sends a message to one or more sync processes, instructing them to reload. 🔁
inspect <type> <name> [<name>...] — Inspects one or more objects of a particular type. 🔍
validate all|<syncname> [<syncname>...] — Validates one or more syncs. ✅
purge all|<table> [<table>...] — Purges the delta and track tables for one or more tables, for one or more databases. 🧹
delta [<database(s)>] — Show the delta counts for each source target. 📈
help [<command> [<action>]] — Shows help. 🆘

🌈 OPTIONS 🌈

-d, --db-name NAME — Database name.
-U, --db-user USER — Database user name.
-P, --db-pass PASS — Database password.
-h, --db-host HOST — Database server host name.
-p, --db-port PORT — Database server port number.
--bucardorc FILE — Use specified .bucardorc file.
--no-bucardorc — Do not use .bucardorc file.
--quiet — Incremental quiet. 🤫
--verbose — Incremental verbose mode. 🗣️
-?, --help — Output basic help and exit.
--version — Print the version number and exit.
--dryrun — Do not perform any actual actions. (Practice mode, we love a rehearsal 🙈)
--confirm — Require direct confirmation before changes. 🔒

🧚 COMMAND DETAILS 🧚

Most of the commands take parameters. These may be passed after the command name and, where appropriate, an object name. Parameters take the form of key/value pairs separated by an equal sign (=). For example:

bucardo add db sea_widgets dbname=widgets host=db.example.com

Here dbname and host are parameters.

Many of the commands also use command-line options, which are specified in the normal way. For example, the bucardo add db command could also be written as:

bucardo add db sea_widgets --dbname widgets --dbhost db.example.com

⚠️ However, parameters and options are not directly interchangeable in all cases. See the documentation for individual commands for their supported options. Don't just assume, bestie, check the receipts.

💾 install

bucardo install

Installs the Bucardo schema from the file bucardo.schema into an existing Postgres cluster. The user bucardo and database bucardo will be created first as needed. This is an interactive installer, but you can supply the following values from the command line:

--dbuser — defaults to postgres
--dbname — defaults to postgres
--dbport — defaults to 5432
--pid-dir — defaults to /var/run/bucardo/

⬆️ upgrade

bucardo upgrade

Upgrades an existing Bucardo installation to the current version of the bucardo database script. Requires that bucardo and the bucardo.schema file be the same version. All changes should be backwards compatible, but you may need to re-validate existing scripts to make sure changes get propagated to all databases. Fr fr, don't skip the re-validate step.

🚀 start

bucardo start "Reason"

Starts Bucardo. Fails if the MCP process is running (determined if its PID file is present). Otherwise, starts cleanly by first issuing the equivalent of a stop to ask any existing Bucardo processes to exit, and then starting a new Bucardo MCP process. A short reason and name should be provided — these are written to the reason_file file (./bucardo.restart.reason.txt by default) and sent in the email sent when Bucardo has been started up. It is also appended to the reason log, which has the same name as the the reason_file but ends in .log.

The options for the start command are:

--sendmail — Tells Bucardo whether or not to send mail on interesting events: startup, shutdown, and errors. Default is on.
--extra-name string — A short string that will be appended to the version string as output by the Bucardo process names. Mostly useful for debugging.
--log-destination destination — Determines the destination for logging output. The supported values are:
- stderr
- stdout
- syslog
- none
- A file system directory.

May be specified more than once, which is useful for, e.g., logging both to a directory and to syslog. If --log-destination is not specified at all, the default is to log to files in /var/log/bucardo.

--log-separate — Forces creation of separate log files for each Bucardo process of the form log.bucardo.X.Y, where X is the type of process (MCP, CTL, or KID), and Y is the process ID.
--log-extension string — Appends the given string to the end of the default log file name, log.bucardo. A dot is added before the name as well, so a log extension of rootdb would produce a log file named log.bucardo.rootdb.
--log-clean — Forces removal of all old log files before running. 🧼
--debug, --no-debug — Enable or disable debugging output. Disabled by default.
--exit-on-nosync, --no-exit-on-nosync — On startup, if Bucardo finds no active syncs, it normally will continue to run, requiring a restart once syncs are added. This is useful for startup scripts and whatnot.

If, however, you want it to exit when there are no active syncs, pass the --exit-on-nosync option. You can also be explicit that it should not exit when there are no syncs by passing --no-exit-on-nosync. This is the default value.

🛑 stop

bucardo stop "Reason"

Forces Bucardo to quit by creating a stop file which all MCP, CTL, and KID processes should detect and cause them to exit. Note that active syncs will not exit right away, as they will not look for the stop file until they have finished their current run. Typically, you should scan the list of processes after running this program to make sure that all Bucardo processes have stopped. One should also provide a reason for issuing the stop — usually this is a short explanation and your name. This is written to the reason_file file (./bucardo.restart.reason.txt by default) and is also used by Bucardo when it exits and sends out mail about its death. It is also appended to the reason log, which has the same name as the the reason_file but ends in .log.

🔁 restart

bucardo restart "Reason"

Stops bucardo, waits for the stop to complete, and then starts it again. Supports the same options as "start" (/start). Useful for start scripts. For getting just CTL and KID processes to recognize newly added, updated, or removed objects, use the reload command, instead. (Important distinction, don't come for me.)

📋 list

bucardo list <type> <regex>

Lists summary information about Bucardo objects. The supported types are:

database
dbgroup
relgroup
sync
table
sequence
customcode
customname
customcols
all

The all option will list information about all object types. 💯

The optional regex option can be used to filter the list to only those matching a regular expression. Filtered, curated, aesthetic.

➕ add

bucardo add <type> <name> <parameters>

Adds a new object to Bucardo. The type specifies the type of object to add, while the name should be the name of the object. The supported types include:

db
dbgroup
table
sequence
all tables
all sequences
relgroup
sync
customname
customcols

🗄️ add db

bucardo add db <name> dbname=actual_name port=xxx host=xxx user=xxx

Adds one or more new databases. The name is the name by which the database will be known to Bucardo, and must be unique. This may vary from the actual database name, as multiple hosts might have databases with the same name. Multiple databases can be added by separating the names with commas. Options that differ between the databases should be separated by a matching commas. Example:

bucardo add db alpha,beta dbname=sales host=aa,bb user=bucardo

This command will attempt an immediate test connection to the added database(s). The supported named parameters are:

dbname — The actual name of the database. Required unless using a service file or setting it via dbdsn.
type — The type of the database. Defaults to postgres. Currently supported values are:
- postgres
- drizzle
- mongo
- mysql
- maria
- oracle
- redis
- sqlite

...and that's only part 1, bestie — there's more where this came from 💜

"dbdsn" — a direct DSN to connect to a database. If this is set, it overrides ALL the other connection options, periodt.
"user" — the username Bucardo uses when connecting to this database. 👑
"pass" — the password Bucardo uses when connecting to this database. ngl bestie, it's recommended you use a .pgpass file instead of putting the password right here. 🔐
"host" — the host Bucardo uses when connecting to this database. Defaults to whatever $PGHOSTADDR or $PGHOST is set to, if they're around. 🌐
"port" — the port Bucardo uses when connecting to this database. Defaults to the value of the $PGPORT environment variable, if it exists. 🚪
"conn" — extra connection parameters, like "sslmode=require" for example. ✨
"service" — the service name Bucardo uses when connecting to this database. 🎀
"status" — the initial status of this database. Defaults to "active", but you can set it to "inactive" too. 💤
"dbgroup" — the name of the database group this database should belong to. 🫂
"addalltables" — automatically add every table from this database. 🪄
"addallsequences" — automatically add every sequence from this database. 🌈
"server_side_prepares", "ssp" — set to 1 or 0 to enable or disable server-side prepares. Defaults to 1. 🔧
"makedelta" — set to 1 or 0 to enable or disable makedelta. Defaults to 0. 💅

Additional parameters:

--force — forces the database to be added without running a connection test. No vibe check, just go. 😤

Note: as a lil convenience, if the "dbuser" value is its default value, bucardo, and Bucardo can't connect to the database, it'll try connecting as postgres and create a superuser named bucardo. This is to make life easier for folks getting started with Bucardo, but it will NOT work if it can't connect as postgres, or if the connection failed because of an authentication failure. 🙈

🗂️ add dbgroup

bucardo add dbgroup name db1:source db2:source db3:target ...

Adds one or more databases to the named dbgroup. If the dbgroup doesn't exist yet, boom, it gets created. The database parameters need to specify their roles, either source or target. 🎯

🗂️ add table

bucardo add table [schema].table db=actual_db_name

Adds a table object. The table info gets read from the specified database. Supported parameters:

"db" — the name of the database to read the table information from. It should be a name Bucardo already knows, thanks to a previous call to add database. Required, bestie.
"autokick" — boolean for whether the table should automatically send kick messages when it's modified. This overrides the "autokick" parameter of any syncs the table is part of. 🦵
"rebuild_index" — boolean for whether to rebuild indexes after every sync. Off by default. Optional. 🔨
"analyze_after_copy" — boolean for whether to analyze the table after every sync. Off by default. Optional. 🔍
"vacuum_after_copy" — boolean for whether to vacuum the table after every sync. Off by default. Optional. 🧹
"relgroup" — adds the table to the named relgroup. If the relgroup doesn't exist, it gets created. Optional. 🫶
"makedelta" — turns makedelta magic on or off. The value is a list of databases that need makedelta for this table. You can also set it to "on" to enable makedelta for all databases. Defaults to "off". ✨
"strict_checking" — boolean for whether to be strict when comparing the table between syncs. If the columns have different names or data types, validation fails. But maybe those columns are allowed to have different names or data types? If so, disable "strict_checking" and column differences become warnings instead of a failed validation. Defaults to true. ⚖️

🗂️ add sequence

bucardo add sequence [schema].sequence relgroup=xxx

"db" — the name of the database to read the sequence information from. Should be a name Bucardo knows, thanks to a previous call to add database. Required.
"relgroup" — adds the sequence to the named relgroup. If the relgroup doesn't exist, it gets created. Optional. 🎀

🗂️ add all tables

bucardo add all tables [relgroup=xxx] [pkonly]

Adds all the tables in all known databases, or in a specified database. It excludes tables in the pg_catalog, information_schema, and bucardo schemas. (Yes, this means you can't replicate the Bucardo configuration database using Bucardo. Sorry about that. 😭) Supported options and parameters:

"db", --db — name of the database to find all the tables to add from. If you don't provide it, tables get added from all known databases. 🌍
"schema", --schema, -n — limit to the tables in the specified comma-delimited list of schemas. You can specify this option more than once. 📋
"exclude-schema", --exclude-schema, -N — exclude tables in the specified comma-delimited list of schemas. You can specify this option more than once. 🚫
"table", --table, -t — limit to the specified tables. You can specify this option more than once. 🎯
"exclude-table", --exclude-table, -T — exclude the specified tables. You can specify this option more than once. 🙅
"relgroup", --relgroup — name of the relgroup to add new tables to. 🫂
"pkonly" — exclude tables without primary keys. 🔑

🗂️ add all sequences

bucardo add all sequences relgroup=xxx

Adds all the sequences in all known databases, or in a specified database. It excludes sequences in the pg_catalog, information_schema, and bucardo schemas. (Yes, again, this means you can't replicate the Bucardo configuration database using Bucardo. Sorry about that. 😭) Supported options and parameters:

"db", --db — name of the database to find all the sequences to add from. If you don't provide it, sequences get added from all known databases. 🌍
"schema", --schema, -n — limit to the sequences in the specified comma-delimited list of schemas. You can specify this option more than once. 📋
"exclude-schema", --exclude-schema, -N — exclude sequences in the specified comma-delimited list of schemas. You can specify this option more than once. 🚫
"relgroup", --relgroup — name of the relgroup to add new tables or sequences to. 🫶

🗂️ add relgroup

bucardo add relgroup name
bucardo add relgroup name table, sequence, ...

Adds a relgroup. After the name, pass in an optional list of tables and/or sequences and they get added to the group. 💖

🗂️ add sync

bucardo add sync name relgroup=xxx dbs=xxx

Adds a sync, which is a named replication event containing info about what to replicate from where to where. The main character of the whole operation, honestly. 👑 The supported parameters are:

"dbs" — the name of a dbgroup or a comma-delimited list of databases. All of the specified databases get synchronized. Required.
"dbgroup" — the name of a dbgroup. All the databases inside this group become part of the sync. If the dbgroup doesn't exist and a separate list of databases is given, the group gets created and populated. 🫂
"relgroup" — the name of a relgroup to synchronize. All the tables and/or sequences in the relgroup get synchronized. Required unless "tables" is specified.
"tables" — list of tables to add to the sync. This implicitly creates a relgroup with the same name as the sync. Required unless "relgroup" is specified.
"status" — indicates whether the sync is active. Must be either "active" or "inactive". Defaults to "active". 💫
"rebuild_index" — boolean for whether to rebuild indexes after every sync. Defaults to off. 🔨
"lifetime" — number of seconds a KID can live before being reaped. No limit by default. ⏳
"maxkicks" — number of times a KID may be kicked before being reaped. No limit by default. 🦵
"conflict_strategy" — the conflict resolution strategy to use in the sync. Supported values:
- "bucardo_source" — the rows on the source database always "win". In other words, in a conflict, Bucardo copies rows from source to target. 🏆
- "bucardo_target" — the rows on the target database always win. 👑
- "bucardo_skip" — any conflicting rows are simply not replicated. Not recommended for most cases. 🙈
- "bucardo_random" — each database has an equal chance of winning each time. This is the default. 🎲
- "bucardo_latest" — the row that was most recently changed wins. ⏰
- "bucardo_abort" — the sync is aborted on a conflict. 💀
"onetimecopy" — determines whether a sync should switch to a full copy mode for a single run. Supported values are:
- 0: off
- 1: always full copy
- 2: only copy tables that are empty on the target
"stayalive" — boolean for whether the sync processes (CTL) should be persistent. Defaults to false. 🫀
"kidsalive" — boolean for whether the sync child processes (KID) should be persistent. Defaults to false. 🧒
"autokick" — boolean for whether tables in the sync should automatically send kick messages when they're modified. May be overridden by the "autokick" parameter of individual tables. 🦵
"checktime" — an interval specifying the maximum time a sync should go before being kicked. Useful for busy systems where you don't want the overhead of notify triggers. ⏱️
"priority" — an integer indicating the priority of the sync. Lower numbers are higher priority. Currently used only for display purposes. 🏅
"analyze_after_copy" — boolean for whether to analyze tables after every sync. Off by default. Optional. 🔍
"overdue" — an interval specifying the amount of time after which the sync has not run that it should be considered overdue. "check_bucardo_sync" issues a warning when a sync hasn't been run in this amount of time. ⚠️
"expired" — an interval specifying the amount of time after which the sync has not run that it should be considered expired. "check_bucardo_sync" issues a critical message when a sync hasn't been run in this amount of time. 🚨
"track_rates" — boolean for whether to track synchronization rates. 📈
rebuild_index — a Boolean for whether we rebuild indexes after every single sync or not. Off by default. Optional, bestie. 🎀
strict_checking — a Boolean for whether we're being strict when comparing tables in the sync. If the columns have different names or data types, the validation just fails. But maybe those columns are allowed to have different names or data types? If so, turn strict_checking off and column differences become warnings instead of a validation fail. Defaults to true. 💅

✨ add customname ✨

bucardo add customname oldname newname [db=name] [sync=name]

Makes a new Bucardo custom name mapping. This is the glow-up that lets the tables in replication have different names on different databases. The oldname must include the schema as well as the table name (as long as the source database supports schemas, anyway). The optional params keep it scoped to one or more databases, and/or one or more syncs. Here's what you can pass:

sync — a sync to add the customname to. You can pass this multiple times. 🔁
database, db — a database to add the customname to. Also can be passed multiple times. 🔁

🌸 add customcols 🌸

bucardo add customcols tablename select_clause [sync=x db=x]

This one lets you pick the exact list of columns to select from when syncing. Instead of the default SELECT * behavior, you can specify literally any columns you want — including function call return values and things that aren't even in the source column list. The optional params scope it to one or more databases, and/or one or more syncs. Some examples, because examples are self-care:

bucardo add customcols public.foobar "select a, b, c"
bucardo add customcols public.foobar "select a, upper(b) AS b, c" db=foo
bucardo add customcols public.foobar "select a, b, c" db=foo sync=abc

Supported params:

sync — a sync to add the customcols to. May be specified multiple times. ✨
database, db — a database to add the customcols to. May be specified multiple times. ✨

🦋 add customcode 🦋

bucardo add customcode <name> <whenrun=value> <src_code=filename> [optional information]

Adds a customcode, which is a Perl subroutine that runs at certain points in the sync process. It might handle exceptions, handle conflicts, or just vibe at certain times with no expectation of functionality (like, say, before Bucardo drops triggers). Metadata about that point gets passed to the subroutine as a hash reference. 🫶

Supported parameters:

name — the name of the custom code object.
about — a short description of the custom code.
whenrun, when_run — a string saying when the custom code should run. Supported values include:
- before_txn
- before_check_rows
- before_trigger_drop
- after_trigger_drop
- after_table_sync
- exception
- conflict
- before_trigger_enable
- after_trigger_enable
- after_txn
- before_sync
- after_sync
getdbh — a Boolean for whether Perl DBI database handles should be handed to the custom code subroutine. If true, database handles show up under the dbh key of the hash reference passed to the subroutine. The value under this key will be a hash reference mapping database names to their respective handles.
sync — name of the sync to associate the custom code with. Cannot be used together with relation. 💀
relation — name of the table or sequence to associate the custom code with. Cannot be used together with sync. 💀
status — the current status of this customcode. Anything other than active means the code does not run.
priority — a number for the order in which to execute custom codes. Lower numbers = higher priority. Super useful for subroutines that set lastcode so they can cancel the execution of subsequent custom codes for the same when_run.
src_code — the file to read the custom code Perl source from.

The body of the Perl subroutine should live in the src_code file, and not inside a sub declaration. When it gets called, it's passed a single hash reference with these keys:

syncname — the name of the currently-executing sync.
version — the version of Bucardo executing the sync.
sourcename — the name of the source database.
targetname — the name of the target database.
sendmail — a code reference you can use to send email messages.
sourcedbh — a DBI database handle to the sync source database. Only provided to custom code executed by the controller.
rellist — an array reference of hash references, each one representing a relation in the sync. Only provided to custom code executed by the controller. The keys in the hash are the same as the parameters supported by add table and add sequence, as appropriate.
schemaname — the schema for the table that triggered the exception. Only provided to exception custom codes.
tablename — the name of the table that triggered the exception. Only provided to exception custom codes.
error_string — the string containing the actual error message. Only provided to exception custom codes.
deltabin — a hash reference with the name of each source database as a key and a list of all primary keys joined together with \0. Only provided to exception custom codes.
attempts — the number of times the sync has been attempted. Only provided to exception custom codes.
conflicts — a hash reference of conflicting rows. The keys are the primary key values, and the values are hash references with the names of the databases containing the conflicting rows and true values. Only provided to conflict custom codes.

The custom code subroutine may set any of these keys in the hash reference to change the behavior of the sync:

message — message to send to the logs.
warning — a warning to emit after the subroutine has returned.
error — an error to be thrown after the subroutine has returned.
nextcode — set it to send execution to the next custom code of the same type. Mainly useful for exception custom codes, and supported only by custom codes executed by the controller.
lastcode — set it to true and any subsequent custom codes of the same type get skipped. 👑
endsync — cancels the sync altogether.

An example, bestie, feast your eyes:

use strict;
use warnings;
use Data::Dumper;

my $info = shift;

# Let's open a file.
my $file = '/tmp/bucardo_dump.txt';
open my $fh, '>:encoding(UTF-8)', $file or do {
    $info->{warning} = "Cannot open $file: $!\n";
    return;
};

# Inspect $info for fun.
print $fh Dumper $info;
close $fh or $info->{warning} = "Error closing $file: $!\n";

# Log a message and return.
$info->{message} = 'IN UR DATABASEZ NORMALIZIN UR RELAYSHUNS';
return;

💜 update 💜

bucardo update <type> <name> <parameters>

Updates a Bucardo object. The type says which kind of object we're updating, and name should be the name of that object. The supported parameters for each type are the same ones as for add. The supported types are:

customcode
db
sync
table
sequence

⭐ update customcode ⭐

bucardo update customcode <name> setting=value

Updates an existing customcode. The stuff you can change:

about — a short description of the custom code.
getdbh — a Boolean for whether Perl DBI database handles should be handed to the custom code subroutine. If true, database handles show up under the dbh key of the hash reference passed to the subroutine. The value under this key will be a hash reference mapping database names to their respective handles.
name — the name of the custom code object.
priority — a number for the order in which to execute custom codes. Lower numbers = higher priority. Useful for subroutines that set lastcode so they can cancel the execution of subsequent custom codes for the same when_run.
src_code — the file to read the custom code Perl source from.
status — the current status of this customcode. Anything other than active means the code does not run.
whenrun — a string saying when the custom code should run. Supported values include:
- before_txn
- before_check_rows
- before_trigger_drop
- after_trigger_drop
- after_table_sync
- exception
- conflict
- before_trigger_enable
- after_trigger_enable
- after_txn
- before_sync
- after_sync

🌈 update db 🌈

bucardo udpate db <name> port=xxx host=xxx user=xxx pass=xxx

Updates a database. The name is the name the database is known by to Bucardo. Heads up: this can be different from the actual database name, because multiple hosts might have databases with the same name. 🙈

The supported named parameters are:

dbname, db — the actual name of the database.
type, dbtype — the type of the database. Currently supported values are:
- postgres
- drizzle
- mongo
- mysql
- maria
- oracle
- redis
- sqlite
username, dbuser, dbdsn — a direct DSN to connect to a database. This one overrides all other connection options if it's set.
user — the username Bucardo should use to connect to the database.
password, dbpass, pass — the password Bucardo should use when connecting to the database. 🤫
dbhost, pghost, host — the host name to connect to.
dbport, pgport, port — the port to connect to.
dbconn, pgconn, conn — additional connection parameters, e.g. sslmode=require. Optional.
status — status of the database in Bucardo. Must be either active or inactive.
dbgroup, server_side_prepares, ssp — enable or disable server-side prepares. Pass 1 to enable them or 0 to disable them.
makedelta — enable or disable makedelta for this database.
dbservice, service — the service name to use for a Postgres database. ✨
dbgroup — a comma-separated list of dbgroups to add the database to. Heads up bestie: the database gets removed from every other dbgroup it used to be in. It's giving "new group, who dis". 💅

💖 `update sync` 💖

bucardo update sync syncname relgroup=xxx dbs=xxx

Updates a sync — which is basically a named replication event that holds all the info about what to replicate from where to where. Here's everything you can pass it:

name — the name of the sync. Required, no skips. 👑
dbs — the name of a dbgroup, or a comma-delimited list of databases.
relgroup — the name of the relgroup to synchronize.
status — whether the sync is active or not. Gotta be either "active" or "inactive". ⚠️ Important tho: this does not change the current run status of the sync, it just marks whether it should be active or inactive on the next reload. If you actually wanna activate or deactivate a sync, use the activate sync and deactivate sync commands. Periodt.
rebuild_index — boolean, whether or not to rebuild indexes after every sync.
lifetime — number of seconds a KID can live before being reaped. 😭
maxkicks — number of times a KID may be kicked before being reaped.
isolation_level — the transaction isolation level this sync should use. The only choices are "serializable" and "repeatable read". That's it, that's the whole menu.
conflict_strategy — the conflict resolution strategy for the sync. Supported values:
- bucardo_source — rows on the "source" database always win. In a conflict, Bucardo copies rows from source to target.
- bucardo_target — rows on the "target" database always win. 🎀
- bucardo_latest — the row that was most recently changed wins.
- bucardo_abort — the sync just aborts on a conflict. 💀
onetimecopy — decides whether a sync should switch into full copy mode for a single run. Supported values:
- 0: off
- 1: always full copy
- 2: only copy tables that are empty on the target
stayalive — boolean, whether the sync processes (CTL) should be persistent.
kidsalive — boolean, whether the sync child processes (KID) should be persistent.
autokick — boolean, whether tables in the sync should automatically send kick messages when they're modified. Can be overridden by the autokick parameter of individual tables, iykyk.
checktime — an interval for the maximum time a sync should go before being kicked. Super useful for busy systems where you don't want the overhead of notify triggers. 🔥
priority — an integer for the priority of the sync. Lower numbers = higher priority. Currently it's only used for display purposes, so don't get too attached.
analyze_after_copy — boolean, whether to analyze tables after every sync. Off by default.
overdue — an interval for how long after a sync hasn't run it should be considered overdue. check_bucardo_sync throws a warning when a sync hasn't run in that amount of time. 🫶
expired — an interval for how long after a sync hasn't run it should be considered expired. check_bucardo_sync throws a critical message when a sync hasn't run in that amount of time. 🚨
track_rates — boolean, whether or not to track synchronization rates.
rebuild_index — boolean, whether or not to rebuild indexes after every sync. (Yes bestie, it's listed twice in the source. Not a typo on my end, I promise. 🙈)
strict_checking — boolean, whether to be strict when comparing tables in the sync. If the columns have different names or data types, validation fails. But maybe those columns are allowed to have different names or data types? Then turn strict_checking off and column differences become warnings instead of failing the validation. Defaults to true.

🌸 `update table` 🌸

bucardo update table [schema].table db=actual_db_name

Updates a table object. The table info gets read from the database you specify. Supported parameters:

db — the name of the database to read the table info from. Should be a name Bucardo already knows about.
schemaname — the name of the schema the table lives in.
tablename — the actual name of the table.
autokick — boolean, whether the table should automatically send kick messages when it's modified. This overrides the autokick parameter of any syncs the table is part of. 💅
rebuild_index — boolean, whether or not to rebuild indexes after every sync.
analyze_after_copy — boolean, whether or not to analyze the table after every sync.
vacuum_after_copy — boolean, whether or not to vacuum the table after every sync.
relgroup — adds the table to the named relgroup. Can be specified more than once. The table gets removed from any other relgroups. 🦋
makedelta — specifies which databases need makedelta enabled for this table.
strict_checking — boolean, whether to be strict when comparing the table between syncs. If the columns have different names or data types, validation fails. But maybe those columns are allowed to differ? Then turn strict_checking off and column differences become warnings instead of failing the validation. Defaults to true.

🎀 `update sequence` 🎀

bucardo update sequence [schema].sequence relgroup=xxx

db — the name of the database where the sequence lives.
schemaname — the name of the schema the sequence is found in.
relgroup — adds the sequence to the named relgroup. Can be specified more than once. The sequence gets removed from any other relgroups. ✨

💀 `remove` 💀

bucardo remove <item_type> <item_name>

Removes one or more objects from Bucardo. Valid item types are:

db or database — use the --force option to clear out related tables and groups instead of erroring out. ⚠️
dbgroup
relgroup
sync
table
sequence
customcols
customname
customcode

⚡ `kick` ⚡

bucardo kick <syncname(s)> [timeout]

Tells one or more named syncs to fire ASAP. Lowkey important tho: this just sends a request that the sync fire — it might not start right away if the same sync is already running, or if the source or target database has exceeded the number of allowed Bucardo connections. 😭

If the final argument is a number, it's treated as a timeout. If that number is zero, the bucardo command won't return until the sync has finished. For any other number, the sync waits at most that many seconds. If any sync hasn't finished before the timeout, you get an exit value of 1. Errors cause exit values of 2 or 3. In all other cases, exit value 0 is returned. ✨

If a timeout is given, the total completion time in seconds is also displayed. If the sync is going to multiple targets, the time each target takes from the start of the kick is shown as each target finishes. Options:

--retry — the number of times to retry a sync if it fails. Defaults to 0.
--retry-sleep — how long to sleep, in seconds, between each retry attempt.
--notimer — by default, kicks with a timeout argument give a running real-time summary of time elapsed using the backspace character. That might be unwanted if you're running a kick via, like, a cronjob 👀 — so turning --notimer on just prints the entire message without backspaces.

⏸️ `pause` ⏸️

bucardo pause <syncname(s)>
bucardo pause all
bucardo resume <syncname(s)>
bucardo resume all

Tells one or more named syncs to temporarily pause, or to resume from a previous pause. This only applies to active syncs and only takes effect if Bucardo is currently running. You can also use the keyword all to pause or resume every known active sync. 💖

🌈 `reload config` 🌈

bucardo reload config
bucardo reload config 30

Sends a message to all CTL and KID processes asking them to reload the Bucardo configuration. This configuration is a series of key/value pairs that configure Bucardo's behavior — not any of the objects managed by the add, remove, or update commands. Don't mix those up bestie.

By default, Bucardo sends the message and then exits. Pass an optional number and Bucardo will instead wait up to that length of time for all child processes to report completion. 🫶

👑 `set` 👑

bucardo set setting1=value [setting2=value]

Sets one or more rows in the configuration setting table. Setting names are case-insensitive. The available settings are:

autosync_ddl — which DDL changing conditions do we try to remedy automatically? Default: newcol.
bucardo_version — current version of Bucardo. Default: 5.6.0.
bucardo_vac — do we want the automatic VAC daemon to run? Default: 1.
bucardo_initial_version — the Bucardo version this schema was created with. Default: 5.6.0.
ctl_checkonkids_time — how often does the controller check on the kids' health? Default: 10.
ctl_createkid_time — how long do we sleep to allow kids-on-demand to get on their feet? Default: 0.5.
ctl_sleep — how long does the controller loop sleep? Default: 0.2.
default_conflict_strategy — default conflict strategy for all syncs. Default: bucardo_latest.
default_email_from — who the alert emails are sent as. Default: nobody@example.com.
default_email_host — which host to send email through. Default: localhost.
default_email_to — who to send alert emails to. Default: nobody@example.com.
email_debug_file — file to save a copy of all outgoing emails to. Default: None.
endsync_sleep — how long do we sleep when custom code requests an endsync? Default: 1.0.
flatfile_dir — directory to store the flatfile output inside of. Default: ".".
host_safety_check — regex to make sure we don't accidentally run where we should not. Default: None. 🛑
isolation_level — the transaction isolation level all syncs should use. Defaults to serializable. The only other valid option is repeatable read.
"kid_deadlock_sleep" — how long to sleep in seconds if we hit a deadlock error. Default: 0.5. Set to -1 to prevent the kid from retrying. 💀
"kid_nodeltarows_sleep" — how long do kids sleep if no delta rows are found? Default: 0.5. 😴
"kid_pingtime" — how often do we ping check the KID? Default: 60. 🏓
"kid_restart_sleep" — how long to sleep in seconds when restarting a kid? Default: 1. 🔄
"kid_serial_sleep" — how long to sleep in seconds if we hit a serialization error. Default: 0.5. Set to -1 to prevent the kid from retrying. 🚫
"kid_sleep" — how long does a kid loop sleep? Default: 0.5. 💤
"log_conflict_file" — name of the conflict detail log file. Default: "bucardo_conflict.log". 📝
"log_level" — how verbose to make the logging. Higher is more verbose. Default: "normal". 🔊
"log_microsecond" — show microsecond output in the timestamps? Default: 0. ⏱️
"log_showlevel" — show log level in the log output? Default: 0. 📊
"log_showline" — show line number in the log output? Default: 0. 📍
"log_showpid" — show PID in the log output? Default: 1. 🆔
"log_showtime" — show timestamp in the log output? 0=off, 1=seconds since epoch, 2=scalar gmtime, 3=scalar localtime. Default: 3. 🕒
"log_timer_format" — the "strftime" format to use to format the log timestamp when "log_showtime" is set to 2 or 3. Defaults to simply the scalar output of the time. 🕰️
"mcp_dbproblem_sleep" — how many seconds to sleep before trying to respawn. Default: 15. 😴
"mcp_loop_sleep" — how long does the main MCP daemon sleep between loops? Default: 0.2. 🔁
"mcp_pingtime" — how often do we ping check the MCP? Default: 60. 🏓
"mcp_vactime" — how often in seconds do we check that a VAC is still running? Default: 60. 🧐
"piddir" — directory holding Bucardo PID files. Default: "/var/run/bucardo". 📁
"reason_file" — file to hold reasons for stopping and starting. Default: "bucardo.restart.reason.txt". 📄
"reload_config_timeout" — number of seconds the "reload_config" command should wait for the reload to complete. Default: 30. ⏳
"semaphore_table" — table to let apps know a sync is ongoing. Default: "bucardo_status". 🚦
"statement_chunk_size" — how many primary keys to shove into a single statement. Default: 10000. 📦
"stats_script_url" — location of the stats script. Default: "http://www.bucardo.org/". 🌐
"stopfile" — name of the semaphore file used to stop Bucardo processes. Default: "fullstopbucardo". 🛑
"syslog_facility" — which syslog facility level to use. Default: "log_local1". 📋
"tcp_keepalives_count" — how many probes to send. 0 indicates sticking with system defaults. Default: 0. 📡
"tcp_keepalives_idle" — how long to wait between each keepalive probe. Default: 0. ⏲️
"tcp_keepalives_interval" — how long to wait for a response to a keepalive probe. Default: 0. ⏱️
"vac_run" — how often does the VAC process run? Default: 30. 🏃
"vac_sleep" — how long does VAC process sleep between runs? Default: 120. 😴
"warning_file" — file containing all log lines starting with "Warning". Default: "bucardo.warning.log". ⚠️

`show`

bucardo show all|changed|<setting> [<setting>...]

Shows the current Bucardo settings. Use the keyword "all" to see all the settings, "changed" to see settings different than the installed defaults, or specify one or more search terms. See "set" for complete details on the configuration settings. 👀

`config`

bucardo config show all|<setting> [<setting>...]
bucardo config set <setting=value> [<setting=value>...]

Deprecated interface for showing and setting configuration settings. Use the "show" and "set" commands, instead.

🚫 Bestie, this is deprecated. Just use show and set, okay?

`ping`

bucardo ping
bucardo ping 60
bucardo ping 0

Sends a ping notice to the MCP process to see if it will respond. By default, it will wait 15 seconds. A numeric argument will change this timeout. Using a 0 as the timeout indicates waiting forever. If a response was returned, the program will exit with a value of 0. If it times out, the value will be 1. Returns a Nagios like message starting with "OK" or "CRITICAL" for success or failure. 🏓

`status`

bucardo status [syncname(s)] [--sort=#] [--show-days] [--compress]

Shows the brief status of all known syncs in a tabular format. If given one or more sync names, shows detailed information for each one. To see detailed information for all syncs, simply use "status all".

When showing brief information, the columns are:

Name — the name of the sync
State — the state of the sync. Can be 'Good', 'Bad', 'Empty', 'No records found', 'Unknown', or the run state for a currently-running sync.
Last good — when the sync last successfully ran.
Time — how long it has been since the last sync success
Last I/U — the number of insert and deletes performed by the last successful sync. May also show the number of rows truncated (T) or conflicted (C), if applicable.
Last bad — when the sync last failed.
Time — how long it has been since the last sync failure

The options for "status" are:

--show-days — specifies whether or not do list the time interval with days, or simply show the hours. For example, "3d 12h 6m 3s" vs. "48h 6m 3s"
--compress — specifies whether or not to compress the time interval by removing spaces. Mostly used to limit the width of the 'status' display.
--sort=# — requests sorting of the 'status' output by one of the nine columns. Use a negative number to reverse the sort order.

`activate`

bucardo activate syncname [syncname2 syncname3 ...] [timeout]

Activates one or more named syncs. If given a timeout argument, it will wait until it has received confirmation from Bucardo that each sync has been successfully activated. ✨

`deactivate`

bucardo deactivate syncname [syncname2 syncname3 ...] [timeout]

Deactivates one or more named syncs. If given a timeout argument, it will wait until it has received confirmation from Bucardo that the sync has been successfully deactivated. 💤

`message`

bucardo message 'I WAS HERE'

Sends a message to the running Bucardo logs. This message will appear prefixed with "MESSAGE: ". If Bucardo is not running, the message will go to the logs the next time Bucardo runs and someone adds another message. 📝

`reload`

bucardo reload [syncname2 syncname3 ...]

Sends a message to one or more sync processes, instructing them to reload. Waits for each to reload before going on to the next. Reloading consists of deactivating a sync, reloading its information from the database, and activating it again. 🔄

`inspect`

bucardo inspect <type> <name> [<name2>...]

Inspects one or more objects of a particular type. The results are sent to "STDOUT". The supported types include:

"table"
"sync"
"relgroup"

`validate`

bucardo validate all|<sync> [<sync>...]

Validates one or more syncs. Use the keyword "all" to validate all syncs, or specify one or more syncs to validate.

📝 Note: this command executes a subset of all the validation done when a sync is started or activated.

`purge`

bucardo purge all|<table> [<table>...]

Purges the delta and track tables for one or more tables, for one or more databases. Use the keyword "all" to validate all tables, or specify one or more tables to validate. 🧹

`delta`

bucardo delta [total] [<database>...]

Show the current delta count for each source target. Provide a list of databases to limit it to just the given ones. Wildcards are allowed. Use the special name "totals" to show only the grand total. 📊

`help`

bucardo help
bucardo help <command>
bucardo help <command> <action>

Get help. General help can be returned, as well as help for a single command or a command and its action. Some examples:

bucard help list
bucard help add table

✨ OPTIONS DETAILS ✨

ngl, it's usually way easier to set most of these options at the top of your script, or just make an alias for them, because they're not gonna change very often — if at all. 💅

-d, --db-name — Name of the Bucardo database to which to connect.

bucardo --db-name widgets
bucardo -d bricolage

-U, --db-user — User name to use when connecting to the Bucardo database.

bucardo --db-user postgres
bucardo -U Mom

-P, --db-pass — Password to use when connecting to the Bucardo database.

bucardo --db-pass s3cr1t
bucardo -P lolz

-h, --db-host — Host name to use when connecting to the Bucardo database.

bucardo --db-host db.example.com
bucardo -h db2.example.net

-p, --db-port — Port number to connect to when connecting to the Bucardo database.

bucardo --db-port 7654

--bucardorc — Use the specified file for configuration instead of the default ./.bucardorc.

bucardo --bucardorc myrcfile

--no-bucardorc — Do not use the ./.bucardorc configuration file.
--verbose — Makes bucardo run verbosely. Default is off.
--quiet — Tells bucardo to be as quiet as possible. Default is off.
--help — Shows a brief summary of usage for bucardo.

📁 FILES 📁

In addition to command-line configurations, you can put any options inside of a file. The file .bucardorc in the current directory will be used if found. If not found, then the file ~/.bucardorc will be used. Finally, the file /etc/bucardorc will be used if available. The format of the file is option = value, one per line. Any line starting with a '#' will be skipped. Any values loaded from a bucardorc file will be overwritten by command-line options. All bucardorc files can be ignored by supplying a "--no-bucardorc" argument. A specific file can be forced with the "--bucardorc=file" option; if this option is set, bucardo will refuse to run unless that file can be read. 📂

🌍 ENVIRONMENT VARIABLES 🌍

The bucardo script uses $ENV{HOME} to look for a .bucardorc file. 🏠

🐛 BUGS 🐛

Bug reports and feature requests are always welcome, please visit bucardo.org (https://bucardo.org), file GitHub Issues (http://github.com/bucardo/bucardo/issues), or post to our email list (https://bucardo.org/mailman/listinfo/bucardo-general). 🫶

👀 SEE ALSO 👀

Bucardo

© COPYRIGHT ©

This program is free to use, subject to the limitations in the LICENSE file. 📜

This page was served by perl v5.32.1, dated 2021-06-30, and it's BUCARDO(1p) — periodt. 💅✨

📦 where this page comes from

debian bookworm: bucardo 5.6.0-4
debian trixie: bucardo 5.6.0-4
ubuntu jammy: bucardo 5.6.0-4
ubuntu noble: bucardo 5.6.0-4
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms