bucardo is the main interface to Bucardo - it is used to start, stop, and control Bucardo.
You can tell
bucardo where to find the main Bucardo database by use of
the following arguments:
Additional bucardo arguments include:
--quiet=0|1 eliminate most output?
--verbose=0|1 increase detail in output?
--debug=0|1 enable debug output?
--sendmail=0|1 send mail on interesting events? (startup, shutdown, and errors)
--logdest=stderr|syslog|none|filepath multiple allowed
--logextension='' suffix to add to log file name, e.g. ‘.log’ -> log.bucardo.log
--logseparate write separate log for each Bucardo process, name ending with <type>.pid
--logshowline in logs show origin line number in Bucardo source code
--logclean remove any existing file logs
--extraname='' any string to append to Bucardo process name, visible in tools like ps
Rather than enter those every time, you may place the arguments into a bucardorc file. All of the arguments below, except for “install”, require that enough options exist to find the main Bucardo database.
If you use
--logdest=syslog, the syslog facility LOCAL1 will be used by default. That is determined by a Bucardo setting in its configuration database, and can be changed to e.g. LOCAL7 like this:
bucardo set syslog_facility=log_local7
To start Bucardo, simply enter:
bucardo start "Reason for starting"
The reason is optional but recommended.
To stop Bucardo, simply enter:
bucardo stop "Reason for stopping"
Again, the reason is optional but recommended.
Restarting is just:
bucardo restart "Reason for restart"
To send a “ping” to the MCP of a running Bucardo, use:
bucardo ping [timeout]
If successful, an exit value of 0 will be returned. The string returned by this command is Nagios-friendly, and will start with either OK or CRITICAL. The optional timeout argument indicates how long to wait for a response before giving up and returning a critical failure. The default time is 15 seconds. To wait forever, enter a timeout of 0.
Bucardo stores important configuration variables in the database inside
bucardo_config table. See the Bucardo configuration
page for a complete list.
To view all of the configuration settings:
bucardo show all
To view one or more specific items, enter their names:
bucardo show kick_sleep log_showline
Note that names are actually regular expressions, so that entering:
bucardo show kid
will list all configuration parameters that have the letters ‘kid’ inside of them.
To change a configuration, use:
bucardo set name=value
For example, to change the syslog logging facility to LOG_LOCAL3:
bucardo set syslog_facility=LOG_LOCAL3
To tell a running Bucardo to re-read the configuration table:
Bucardo works by running one or more replication events called syncs.
The main interface for controlling these is
Syncs are fired by changes to the underlying tables, or manually started by kicking them. To kick a sync, use:
bucardo kick <syncname> [timeout]
The optional timeout argument tells how long
bucardo will wait for a response from Bucardo indicating that the sync has finished. If no timeout argument is given, the program sends the kick signal and returns immediately. If a value of “0” is given,
bucardo will wait indefinitely for the sync to finish, and also give a running tab of how long the sync has taken.
Multiple syncs arguments can be given. If not timeout is given, they will all be kicked at once. Otherwise, they will be kicked in the order given, each starting when the previous one has completed. For example, to kick the syncs “sales” and “marketing”, while while waiting for each to finish, you could use:
bucardo kick sales marketing 0
To reload a sync:
bucardo reload <syncname>
One or more named syncs can be reloaded this way. Each will be reloaded
in turn, and
bucardo will let you know when each has been reloaded.
When a sync is reloaded, the MCP will stop the existing sync,
reload information about the sync from the database, and start it up again.
This is typically used when you want to make changes to an existing sync
that is already running, e.g. the onetimecopy
To activate a sync that is not currently running, use:
bucardo activate <syncname>
To deactivate a sync that is currently active and running, use:
bucardo deactivate <syncname>
To view general status about the currently running Bucardo process, use:
This will list general information about each sync
bucardo status <syncname>
This will show detailed information about a specific sync, including the last time it successfully ran, the number of rows transferred, and the last time it failed.
To get a list of all syncs:
bucardo list syncs
This list will show the sync name, its type (fullcopy, pushdelta, or swap), the source relgroup, the target database (or database group), and current status. For more details on a specific sync, use the ‘status’ command above.
To get a list of all known databases:
bucardo list dbs
This will show the name of the database (as used by Bucardo, not its actual name in Postgres), its status, and the connection string used by Bucardo to connect to it.
To get a list of all known database groups:
bucardo list dbgroups
To list all known tables:
bucardo list tables
To list all known sequences:
bucardo list sequences
To list all relgroup:
bucardo list relgroup
To list only one or more specific relgroups, add their names:
bucardo list relgroup <relgroup>
To get a list of all tables that belong to a relgroup, use the verbose argument:
bucardo list relgroup <relgroup> --verbose
To add new items, the general syntax is:
bucardo add <thing> <name> additional_information
Bucardo needs to know how to connect to each database involved in replication. You can teach it about a new database by using:
bucardo add db <name> [options]
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.
The other optional arguments are entered in the format name=value and can include:
--force: Forces the database to be added without running a connection test.
For example, to add three new databases on different hosts:
bucardo add db sales1 dbname=sales host=int-db-sales1
bucardo add db sales2 dbname=sales host=int-db-sales2
bucardo add db sales3 dbname=sales host=int-db-sales3
Note: As a convenience, if the “user” value is its default value, “bucardo”, in the event that Bucardo cannot connect to the database, it will try connecting as “postgres” and create a superuser named “bucardo”. This is to make things easier for folks getting started with Bucardo, but will not work if it cannot connect as “postgres”, or if it the connection failed due to an authentication failure.
Databases can be grouped together, so that one source database can push to a group of target databases rather than a single database. To create a new named group:
bucardo add dbgroup name db1:source db2:source db3:target ...
This adds one or more databases to the named dbgroup. If the dbgroup doesn’t exist, it will be created. The database parameters should specify their roles, either “source” or “target”.
bucardo add dbgroup sales sales1:source sales2:target sales3:target
Bucardo needs to know about all tables that might be used in replication. Adding a tables is simply:
bucardo add table <tablename> db=dbname
The tablename can be schema qualified, but does not have to be. The “dbname” refers to the internal name Bucardo uses to identify databases. The “db=dbname” can be left off if there is only one database in the db table. Note that you only need to add tables from the source database(s).
An easier way to add tables is to simply run:
bucardo add all tables [db=dbname]
This will not actually change these tables or replicate them, it will merely tell Bucardo about them. Thus, it is safe to run this command at any time.
Bucardo can also replicate sequences that it knows about. To add a sequence:
bucardo add sequence <seqname> db=dbname
To add all sequences:
bucardo add all sequences [db=dbname]
All the notes that apply to ‘add table’ above apply here as well.
A relgroup is a named group of tables that are replicated together. To add a relgroup:
bucardo add relgroup <name> [table table]
To add a sync:
bucardo add sync <name> dbgroup=<dbgroupname> relgroup=<relgroup>
The name is simply an internal name used by Bucardo. Keep it short but descriptive: it is used quite often in day to day use. The source is the name of the relgroup that we are replicating from. The type is one of fullcopy, pushdelta, or swap. The target is either a database (targetdb=
As a shortcut for creating new syncs, you can also give a comma-separated list of tables, like so:
bucardo add sync abc dbgroup=<dbgroupname> tables=sales,marketing,userdb
This will create a relgroup of the same name as the sync if it does not already exist, add the tables to it, and then create the sync.
Some of the other options that can be added to ‘add sync’, in the format name=value:
To write a custom message to the log file that a current Bucardo process is writing to, use:
bucardo message "Your message here"
The message will be written by the MCP to the logs in the format:
MESSAGE (date): string
where date is the timestamp the message was added, and string was the message provided
Separate documentation exists for the following commands:
End Point Dev offers professional support for Bucardo, as well as specializing in developing, designing, and marketing effective websites. Since 1995, our diverse team of developers has shown that End Point can handle your organization’s greatest web and database challenges.