SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from Fedora 8 bucardo-5.6.0-1.epel8.playground.noarch.rpm

BUCARDO

Section: User Contributed Perl Documentation (1)
Updated: 2020-02-04
Index 

NAME

bucardo - utility script for controlling the Bucardo program 

VERSION

This document describes version 5.6.0 of bucardo 

USAGE

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

DESCRIPTION

The bucardo script is the main interaction to a running Bucardo instance. Itcan be used to start and stop Bucardo, add new items, kick syncs, and eveninstall and upgrade Bucardo itself. For more complete documentation, pleaseview the wiki <https://bucardo.org/>. 

COMMANDS

Run "bucardo help <command>" for additional details
install
Installs the Bucardo configuration database.
upgrade
Upgrades the Bucardo configuration database to the latest schema.
start [<start options>] [<reason>]
Starts Bucardo.
stop [<reason>]
Stops Bucardo.
restart [<start options>] [<reason>]
Stops and starts Bucardo.
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 Bucardoconfiguration.
reopen
Sends a message to all Bucardo processes asking them to reopen any log filesthey 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..
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 moredatabases.
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.     --confirm             Require direct confirmation before changes.
 

COMMAND DETAILS

Most of the commands take parameters. These may be passed after the commandname and, where appropriate, an object name. Parameters take the form ofkey/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 thenormal way. For example, the "bucardo add db" command could also be writtenas:

  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. 

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 aninteractive 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 databasescript. Requires that bucardo and the bucardo.schema file be the same version. Allchanges should be backwards compatible, but you may need to re-validate existing scriptsto make sure changes get propagated to all databases. 

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 Bucardoprocesses to exit, and then starting a new Bucardo MCP process. A short reason and name shouldbe provided - these are written to the "reason_file" file (./bucardo.restart.reason.txt bydefault) and sent in the email sent when Bucardo has been started up. It is also appended tothe 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 theBucardo 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 adirectory and to syslog. If "--log-destination" is not specified at all, thedefault 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 isthe 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 torun, requiring a restart once syncs are added. This is useful for startupscripts 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 notexit when there are no syncs by passing "--no-exit-on-nosync". This is thedefault value.

 

stop

  bucardo stop "Reason"

Forces Bucardo to quit by creating a stop file which all MCP, CTL, and KID processes shoulddetect and cause them to exit. Note that active syncs will not exit right away, as theywill 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 Bucardoprocesses have stopped. One should also provide a reason for issuing the stop - usuallythis 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 andsends out mail about its death. It is also appended to the reason log, which has the same nameas 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. Forgetting just CTL and KID processes to recognize newly added, updated, orremoved objects, use the "reload" command, instead. 

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 thosematching a regular expression. 

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 typesinclude:

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 beknown to Bucardo, and must be unique. This may vary from the actual databasename, as multiple hosts might have databases with the same name. Multiple databasescan be added by separating the names with commas. Options that differ between thedatabases 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"
dbdsn
A direct DSN to connect to a database. Will override all other connection options if set.
user
The username Bucardo should use when connecting to this database.
pass
The password Bucardo should use when connecting to this database. It is recommendedthat you use a .pgpass file rather than entering the password here.
host
The host Bucardo should use when connecting to this database. Defaults to the value of the $PGHOSTADDRor $PGHOST environment variables, if present.
port
The port Bucardo should use when connecting to this database. Defaults to the value of the $PGPORTenvironment variable, if present.
conn
Additional connection parameters, e.g. "sslmode=require".
service
The service name Bucardo should use when connecting to this database.
status
Initial status of this database. Defaults to ``active'' but can be set to ``inactive''.
dbgroup
Name of the database group this database should belong to.
addalltables
Automatically add all tables from this database.
addallsequences
Automatically add all sequences 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.

Note: As a convenience, if the "dbuser" value is its default value,``bucardo'', in the event that Bucardo cannot connect to the database, it willtry connecting as ``postgres'' and create a superuser named ``bucardo''. This isto make things easier for folks getting started with Bucardo, but will notwork if it cannot connect as ``postgres'', or if it the connection failed due toan 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 dbgroupdoesn't exist, it will be created. The database parameters should specifytheir roles, either ``source'' or ``target''.

add table

  bucardo add table [schema].table db=actual_db_name

Adds a table object. The table information will be read from the specifieddatabase. Supported parameters:

db
The name of the database from which to read the table information. Should be aname known to Bucardo, thanks to a previous call to "add database". Required.
autokick
Boolean indicating whether or not the table should automatically send kickmessages when it's modified. Overrides the "autokick" parameter of any syncsof which the table is a part.
rebuild_index
Boolean indicating whether or not to rebuild indexes after every sync. Off bydefault. Optional.
analyze_after_copy
Boolean indicating whether or not to analyze the table after every sync. Offby default. Optional.
vacuum_after_copy
Boolean indicating whether or not to vacuum the table after every sync. Off bydefault. Optional.
relgroup
Adds the table to the named relgroup. If the relgroup does notexist, it will be created. Optional.
makedelta
Turns makedelta magic on or off. Value is a list of databases which need makedeltafor this table. Value can also be ``on'' to enable makedelta for all databases.Defaults to ``off''.
strict_checking
Boolean indicating whether or not to be strict when comparing the tablebetween syncs. If the columns have different names or data types, thevalidation will fail. But perhaps the columns are allowed to have differentnames or data types. If so, disable "strict_checking" and column differences willresult in warnings rather than failing the validation. Defaults to true.

add sequence

  bucardo add sequence [schema].sequence relgroup=xxx
db
The name of the database from which to read the sequence information. Shouldbe a name known to Bucardo, thanks to a previous call to "add database".Required.
relgroup
Adds the sequence to the named relgroup. If the relgroup does notexist, it will be 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.Excludes tables in the "pg_catalog", "information_schema", and "bucardo"schemas. (Yes, this means that you cannot replicate the Bucardo configurationdatabase using Bucardo. Sorry about that.) Supported options and parameters:

db
--db
Name of the database from which to find all the tables to add. If notprovided, tables will be added from all known databases.
schema
--schema
-n
Limit to the tables in the specified comma-delimited list of schemas. Theoptions may be specified more than once.
exclude-schema
--exclude-schema
-N
Exclude tables in the specified comma-delimited list of schemas. The optionsmay be specified more than once.
table
--table
-t
Limit to the specified tables. The options may be specified more than once.
exclude-table
--exclude-table
-T
Exclude the specified tables. The options may be specified more than once.
relgroup
--relgroup
Name of the relgroup to which to add new tables.
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.Excludes sequences in the "pg_catalog", "information_schema", and "bucardo"schemas. (Yes, this means that you cannot replicate the Bucardo configurationdatabase using Bucardo. Sorry about that.) Supported options and parameters:

db
--db
Name of the database from which to find all the sequences to add. If notprovided, sequences will be added from all known databases.
schema
--schema
-n
Limit to the sequences in the specified comma-delimited list of schemas. Theoptions may be specified more than once.
exclude-schema
--exclude-schema
-N
Exclude sequences in the specified comma-delimited list of schemas. Theoptions may be specified more than once.
relgroup
--relgroup
Name of the relgroup to which to add new tables or sequences.

add relgroup

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

Adds a relgroup. After the name, pass in an optional list of tablesand/or sequences and they will be added to the group.

add sync

  bucardo add sync name relgroup=xxx dbs=xxx

Adds a sync, which is a named replication event containing information aboutwhat to replicate from where to where. The supported parameters are:

dbs
The name of a dbgroup or comma-delimited list of databases. All of thespecified databases will be synchronized. Required.
dbgroup
The name of a dbgroup. All of the databases within this group will bepart of the sync. If the dbgroup does not exists and a separate listof databases is given, the group will be created and populated.
relgroup
The name of a relgroup to synchronize. All of the tables and/orsequences in the relgroup will be synchronized. Required unless "tables" isspecified.
tables
List of tables to add to the sync. This implicitly creates a relgroupwith the same name as the sync. Required unless "relgroup" is specified.
status
Indicates whether or not the sync is active. Must be either ``active'' or``inactive''. Defaults to ``active''.
rebuild_index
Boolean indicating whether or not 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 mostcases.
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 or not a sync should switch to a full copy mode for asingle run. Supported values are:
0: off
1: always full copy
2: only copy tables that are empty on the target
stayalive
Boolean indicating whether or not the sync processes (CTL) should bepersistent. Defaults to false.
kidsalive
Boolean indicating whether or not the sync child processes (KID) should bepersistent. Defaults to false.
autokick
Boolean indicating whether or not tables in the sync should automatically sendkick 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 beingkicked. Useful for busy systems where you don't want the overhead of notifytriggers.
priority
An integer indicating the priority of the sync. Lower numbers are higherpriority. Currently used only for display purposes.
analyze_after_copy
Boolean indicating whether or not to analyze tables after every sync. Off bydefault. Optional.
overdue
An interval specifying the amount of time after which the sync has not runthat it should be considered overdue. "check_bucardo_sync" issues a warningwhen a sync has not been run in this amount of time.
expired
An interval specifying the amount of time after which the sync has not runthat it should be considered expired. "check_bucardo_sync" issues a criticalmessage when a sync has not been run in this amount of time.
track_rates
Boolean indicating whether or not to track synchronization rates.
rebuild_index
Boolean indicating whether or not to rebuild indexes after every sync. Off bydefault. Optional.
strict_checking
Boolean indicating whether or not to be strict when comparing tables in thesync. If the columns have different names or data types, the validation willfail. But perhaps the columns are allowed to have different names or datatypes. If so, disable "strict_checking" and column differences will result inwarnings rather than failing the validation. Defaults to true.

add customname

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

Creates a new Bucardo custom name mapping. This allows the tables involved inreplication to have different names on different databases. The "oldname"must contain the schema as well as the table name (if the source databasesupports schemas). The optional parameters limit it to one or more databases,and/or to one or more syncs. Supported parameters:

sync
A sync to which to add the customname. May be specified multiple times.
database
db
A database for which to add the customname. May be specified multiple times.

add customcols

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

Specify the list of columns to select from when syncing. Rather than thedefault "SELECT *" behavior, you can specify any columns you want, includingthe use of function call return values and things not in the source columnlist. The optional parameters limit it to one or more databases, and/or to oneor more syncs. Some examples:

  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 parameters:

sync
A sync to which to add the customcols. May be specified multiple times.
database
db
A database for which to add the customcols. 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 can be run at certainpoints in the sync process. It might handle exceptions, handle conflicts, orjust run at certain times with no expectation of functionality (e.g., beforeBucardo drops triggers). Metadata about that point will be passed to thesubroutine 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 indicating when the custom code should be run. Supported valuesinclude:
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
Boolean indicating whether or not Perl DBI database handles should beprovided to the custom code subroutine. If true, database handles will beprovided 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 totheir respective handles.
sync
Name of the sync with which to associate the custom code. Cannot be used incombination with "relation".
relation
Name of the table or sequence with which to associate the custom code. Cannotbe used in combination with "sync".
status
The current status of this customcode. Anything other than ``active'' means thecode is not run.
priority
Number indicating the priority in which order to execute custom codes. Lower numbersare higher priority. Useful for subroutines that set "lastcode" in order tocancel the execution of subsequent custom codes for the same "when_run".
src_code
File from which to read the custom code Perl source.

The body of the Perl subroutine should be implemented in the "src_code" file,and not inside a "sub" declaration. When called, it will be passed a singlehash reference with the following 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 that can be used to send email messages.
sourcedbh
A DBI database handle to the sync source database. Provided only to customcode executed by the controller.
rellist
An array reference of hash references, each representing a relation in thesync. Provided only to custom code executed by the controller. The keys inthe 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. Provided only to``exception'' custom codes.
tablename
The name of the table that triggered the exception. Provided only to``exception'' custom codes.
error_string
The string containing the actual error message. Provided only to ``exception''custom codes.
deltabin
A hash reference with the name of each source database as a key and a list ofall primary keys joined together with ``\0''. Provided only to ``exception''custom codes.
attempts
The number of times the sync has been attempted. Provided only to ``exception''custom codes.
conflicts
A hash reference of conflicting rows. The keys are the primary key values, andthe values are hash references with the names of the databases containing theconflicting rows and true values. Provided only to ``conflict'' custom codes.

The custom code subroutine may set any of these keys in the hash reference tochange 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 to send execution to the next custom code of the same type. Mainly usefulto exception custom codes, and supported only by custom codes executed by thecontroller.
lastcode
Set to true to have any subsequent custom codes of the same type to beskipped.
endsync
Cancels the sync altogether.

An example:

  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" specifies the type of object to update,while the "name" should be the name of the object. The supported parametersfor each type are the same as those for ``add''. The supported types are:

customcode
db
sync
table
sequence

update customcode

  bucardo update customcode <name> setting=value

Updates an existing customcode. Items that can be changed are:

about
A short description of the custom code.
getdbh
Boolean indicating whether or not Perl DBI database handles should beprovided to the custom code subroutine. If true, database handles will beprovided 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 totheir respective handles.
name
The name of the custom code object.
priority
Number indicating the priority in which order to execute custom codes. Lower numbersare higher priority. Useful for subroutines that set "lastcode" in order tocancel the execution of subsequent custom codes for the same "when_run".
src_code
File from which to read the custom code Perl source.
status
The current status of this customcode. Anything other than ``active'' means thecode is not run.
whenrun
A string indicating when the custom code should be 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 by which the database is known toBucardo. This may vary from the actual database name, as multiple hosts mighthave 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. Will override all other connection options if 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 which to connect.
dbport
pgport
port
The port to which to connect.
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 disablethem.
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 which to add the database. Thedatabase will be removed from any other dbgroups of which it was previously amember.

update sync

  bucardo update sync syncname relgroup=xxx dbs=xxx

Updates a sync, which is a named replication event containing information aboutwhat to replicate from where to where. The supported parameters are:

name
The name of the sync. Required.
dbs
The name of a dbgroup or comma-delimited list of databases.
relgroup
The name of a relgroup to synchronize.
status
Indicates whether or not the sync is active. Must be either ``active'' or``inactive''. Note that this will not change the current run status of the sync,just mark whether it should be active or inactive on the next reload. Use the"activate sync" and <deactivate sync> commands to actually activate ordeactivate a sync.
rebuild_index
Boolean indicating 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.Only choices are ``serializable'' and ``repeatable read''
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_latest
The row that was most recently changed wins.
bucardo_abort
The sync is aborted on a conflict.
onetimecopy
Determines whether or not a sync should switch to a full copy mode for asingle run. Supported values are:
0: off
1: always full copy
2: only copy tables that are empty on the target
stayalive
Boolean indicating whether or not the sync processes (CTL) should bepersistent.
kidsalive
Boolean indicating whether or not the sync child processes (KID) should bepersistent.
autokick
Boolean indicating whether or not tables in the sync should automatically sendkick 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 beingkicked. Useful for busy systems where you don't want the overhead of notifytriggers.
priority
An integer indicating the priority of the sync. Lower numbers are higherpriority. Currently used only for display purposes.
analyze_after_copy
Boolean indicating whether or not to analyze tables after every sync. Off bydefault.
overdue
An interval specifying the amount of time after which the sync has not runthat it should be considered overdue. "check_bucardo_sync" issues a warningwhen a sync has not been run in this amount of time.
expired
An interval specifying the amount of time after which the sync has not runthat it should be considered expired. "check_bucardo_sync" issues a criticalmessage when a sync has not been run in this amount of time.
track_rates
Boolean indicating whether or not to track synchronization rates.
rebuild_index
Boolean indicating whether or not to rebuild indexes after every sync.
strict_checking
Boolean indicating whether or not to be strict when comparing tables in thesync. If the columns have different names or data types, the validation willfail. But perhaps the columns are allowed to have different names or datatypes. If so, disable "strict_checking" and column differences will result inwarnings rather than failing the validation. Defaults to true.

update table

  bucardo update table [schema].table db=actual_db_name

Updates a table object. The table information will be read from the specifieddatabase. Supported parameters:

db
The name of the database from which to read the table information. Should be aname known to Bucardo.
schemaname
The name of the schema in which the table is found.
tablename
The actual name of the table.
autokick
Boolean indicating whether or not the table should automatically send kickmessages when it's modified. Overrides the "autokick" parameter of any syncsof which the table is a part.
rebuild_index
Boolean indicating whether or not to rebuild indexes after every sync.
analyze_after_copy
Boolean indicating whether or not to analyze the table after every sync.
vacuum_after_copy
Boolean indicating whether or not to vacuum the table after every sync.
relgroup
Adds the table to the named relgroup. May be specified more than once.The table will be removed from any other relgroups.
makedelta
Specifies which databases need makedelta enabled for this table.
strict_checking
Boolean indicating whether or not to be strict when comparing the tablebetween syncs. If the columns have different names or data types, thevalidation will fail. But perhaps the columns are allowed to have differentnames or data types. If so, disable "strict_checking" and column differences willresult in warnings rather than 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 in which the sequence is found.
relgroup
Adds the sequence to the named relgroup. May be speci<fied more thanonce. The sequence will be 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 oferroring out.

*
"dbgroup"
*
"relgroup"
*
"sync"
*
"table"
*
"sequence"
*
"customcols"
*
"customname"
*
"customcode"
 

kick

  bucardo kick <syncname(s)> [timeout]

Tells one or more named syncs to fire as soon as possible. Note that this simply sends a request thatthe sync fire: it may not start right away if the same sync is already running, or if the source ortarget database has exceeded the number of allowed Bucardo connections. If the final argument is anumber, it is treated as a timeout. If this number is zero, the bucardo command will not returnuntil the sync has finished. For any other number, the sync will wait at most that number of seconds.If any sync has not finished before the timeout, an exit value of 1 will be returned. Errors willcause exit values of 2 or 3. In all other cases, an exit value of 0 will be returned.

If a timeout is given, the total completion time in seconds is also displayed. If the sync is going tomultiple targets, the time that each target takes from the start of the kick is also shown as eachtarget 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 oftime elapsed by using the backspace character. This may not be wanted ifrunning a kick, for example, via a cronjob, so turning --notimer on willsimply print 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. Thisonly applies to active syncs and only takes effect if Bucardo is currently running. Thekeyword 'all' can be used as well to pause or resume all known active syncs. 

reload config

  bucardo reload config  bucardo reload config 30

Sends a message to all CTL and KID processes asking them to reload the Bucardoconfiguration. This configuration is a series of key/value pairs thatconfigure Bucardo's behavior, and not any of the objects managed by the"add", "remove", or "update" commands.

By default, Bucardo will send the message and then exit. Pass an optionalnumber and Bucardo will instead wait up to that length of time for all childprocesses to report completion. 

set

  bucardo set setting1=value [setting2=value]

Sets one or more configuration setting table. Setting names arecase-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
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: "nobodyAATTexample.com".
default_email_host
Which host to send email through. Default: "localhost".
default_email_to
Who to send alert emails to. Default: "nobodyAATTexample.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 sync 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 thesettings, ``changed'' to see settings different than the installed defaults,or specify one or more search terms. See ``set'' for complete details on theconfiguration 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. 

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. Anumeric argument will change this timeout. Using a 0 as the timeout indicates waiting forever. If a responsewas 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, simplyuse ``status all''

When showing brief information, the columns are:

1. Name
The name of the sync
2. State
The state of the sync. Can be 'Good', 'Bad', 'Empty', 'No records found','Unknown', or the run state for a currently-running sync.
3. Last good
When the sync last successfully ran.
4. Time
How long it has been since the last sync success
5. Last I/U
The number of insert and deletes performed by the last successful sync. May also showthe number of rows truncated (T) or conflicted (C), if applicable.
6. Last bad
When the sync last failed.
7. 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 showthe 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 anegative 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 receivedconfirmation 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 receivedconfirmation 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: ''. IfBucardo is not running, the message will go to the logs the next time Bucardo runs and someoneadds 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 ofdeactivating a sync, reloading its information from the database, andactivating 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, orspecify one or more syncs to validate.

Note that this command executes a subset of all the validation done when async is started or activated. 

purge

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

Purges the delta and track tables for one or more tables, for one or moredatabases. Use the keyword ``all'' to validate all tables, or specify one ormore tables to validate. 

delta

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

Show the current delta count for each source target. Provide a list of databasesto 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 commandor a command and its action. Some examples:

  bucard help list  bucard help add table
 <