DragonFly On-Line Manual Pages

BUCARDO(1) User Contributed Perl Documentation BUCARDO(1)

NAME
bucardo - utility script for controlling the Bucardo program

VERSION
This document describes version 5.3.1 of bucardo

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

DESCRIPTION
The bucardo script is the main interaction to a running Bucardo
instance. It can be used to start and stop Bucardo, add new items, kick
syncs, and even install and upgrade Bucardo itself. For more complete
documentation, please view the wiki <http://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 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..

"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.

"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 .bucarorc 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.

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.

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.

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.

list
bucardo list <type> <regex>

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

o "database"

o "dbgroup"

o "relgroup"

o "sync"

o "table"

o "sequence"

o "customcode"

o "customname"

o "customcols"

o "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.

Aliases:

"l"
"lsit"
"liast"
"lisy"
"lit"

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 pass=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

The supported named parameters are:

"dbname"
"db"
The actual name of the database. Required.

"type"
"dbtype"
The type of the database. Defaults to "postgres". Currently
supported values are:

o "postgres"

o "drizzle"

o "mongo"

o "mysql"

o "maria"

o "oracle"

o "redis"

o "sqlite"

"username"
"dbuser"
"user"
The username Bucardo should use to connect to the database.
Optional.

"password"
"dbpass"
"pass"
The password Bucardo should use when connecting to the database.
Optional.

"dbhost"
"pghost"
"host"
The host name to which to connect. Defaults to the value of the
$PGHOSTADDR or $PGHOST environment variables, if present. Optional.

"dbport"
"pgport"
"port"
The port to which to connect. Defaults to the value of the $PGPORT
environment variable, if present. Optional.

"dbconn"
"pgconn"
"conn"
Additional connection parameters, e.g., "sslmode=require".
Optional.

"status"
Initial status of the database in Bucardo. Must be either "active"
or "inactive". Defaults to "active".

"dbgroup"
Bucardo dbgroup to which to add the database. Optional.

"addalltables"
Automatically adds all tables once the database has been added.
Optional.

"addallsequences"
Automatically adds all sequences once the database has been added.
Optional.

"server_side_prepares"
"ssp"
Enable or disable server-side prepares. Pass 1 to enable them or 0
to disable them. Defaults to 1.

"makedelta"
Enable or disable makedelta for this database. Defaults to 0.

"dbservice"
"service"
The service name to use for a Postgres database. Optional.

Note: As a convenience, if the "dbuser" 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.

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, it will be created. The database parameters should specify their
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
specified database. Supported parameters:

"db"
The name of the database from which to read the table information.
Should be a name known to Bucardo, thanks to a previous call to
"add database". Required.

"autokick"
Boolean indicating whether or not the table should automatically
send kick messages when it's modified. Overrides the "autokick"
parameter of any syncs of which the table is a part.

"rebuild_index"
Boolean indicating whether or not to rebuild indexes after every
sync. Off by default. Optional.

"analyze_after_copy"
Boolean indicating whether or not to analyze the table after every
sync. Off by default. Optional.

"vacuum_after_copy"
Boolean indicating whether or not to vacuum the table after every
sync. Off by default. Optional.

"relgroup"
Adds the table to the named relgroup. If the relgroup does not
exist, it will be created. Optional.

"makedelta"
Turns makedelta magic on or off. Value is a list of databases which
need makedelta for this table. Value can also be "on" to enable
makedelta for all databases. Defaults to "off".

"strict_check"
Boolean indicating whether or not to be strict when comparing the
table between syncs. If the columns have different names or data
types, the validation will fail. But perhaps the columns are
allowed to have different names or data types. If so, disable
"strict_check" and column differences will result 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. Should be 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 not
exist, 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 configuration database 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
not provided, tables will be added from all known databases.

"schema"
"--schema"
"-n"
Limit to the tables in the specified comma-delimited list of
schemas. The options may be specified more than once.

"exclude-schema"
"--exclude-schema"
"-N"
Exclude tables in the specified comma-delimited list of schemas.
The options may 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 configuration database 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 not provided, sequences will be added from all known databases.

"schema"
"--schema"
"-n"
Limit to the sequences in the specified comma-delimited list of
schemas. The options may be specified more than once.

"exclude-schema"
"--exclude-schema"
"-N"
Exclude sequences in the specified comma-delimited list of schemas.
The options 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 tables
and/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
about what to replicate from where to where. The supported parameters
are:

"dbs"
The name of a dbgroup or comma-delimited list of databases. All of
the specified databases will be synchronized. Required.

"dbgroup"
The name of a dbgroup. All of the databases within this group will
be part of the sync. If the dbgroup does not exists and a separate
list of databases is given, the group will be created and
populated.

"relgroup"
The name of a relgroup to synchronize. All of the tables and/or
sequences in the relgroup will be 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 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 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 or not 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 indicating whether or not the sync processes (CTL) should
be persistent. Defaults to false.

"kidsalive"
Boolean indicating whether or not the sync child processes (KID)
should be persistent. Defaults to false.

"autokick"
Boolean indicating whether or not 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 indicating whether or not 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 has not 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 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 by default. Optional.

"strict_check"
Boolean indicating whether or not to be strict when comparing
tables in the sync. If the columns have different names or data
types, the validation will fail. But perhaps the columns are
allowed to have different names or data types. If so, disable
"strict_check" and column differences will result in warnings
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 in replication to have different names on different databases.
The "oldname" must contain the schema as well as the table name (if the
source database supports 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
the default "SELECT *" behavior, you can specify any columns you want,
including the use of function call return values and things not in the
source column list. The optional parameters limit it to one or more
databases, and/or to one or 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
certain points in the sync process. It might handle exceptions, handle
conflicts, or just run at certain times with no expectation of
functionality (e.g., before Bucardo drops triggers). Metadata about
that point will be 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 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"
"getdbh"
Boolean indicating whether or not Perl DBI database handles should
be provided to the custom code subroutine. If true, database
handles will be provided 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 with which to associate the custom code.

"relation"
Name of the table or sequence with which to associate the custom
code.

"status"
The current status of this customcode. Anything other than "active"
means the code is not run.

"priority"
Number indicating the priority in which order to execute custom
codes. Lower numbers are higher priority. Useful for subroutines
that set "lastcode" in order to cancel 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 single hash 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
custom code executed by the controller.

"rellist"
An array reference of hash references, each representing a relation
in the sync. Provided only 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. 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 of all 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, and the values are hash references with the names of the
databases containing the conflicting rows and true values. Provided
only 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 to send execution to the next custom code of the same type.
Mainly useful to exception custom codes, and supported only by
custom codes executed by the controller.

"lastcode"
Set to true to have any subsequent custom codes of the same type to
be skipped.

"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 parameters for 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
be provided to the custom code subroutine. If true, database
handles will be provided 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.

"status"
The current status of this customcode. Anything other than "active"
means the code is not run.

"whenrun"
A string indicating when the custom code should be run. Supported
values include:

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 to Bucardo. This may vary from the actual database name, as
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:

o "postgres"

o "drizzle"

o "mongo"

o "mysql"

o "maria"

o "oracle"

o "redis"

o "sqlite"

"username"
"dbuser"
"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 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 which to add the database.
The database will be removed from any other dbgroups of which it
was previously a member.

update sync

bucardo update sync syncname relgroup=xxx dbs=xxx

Updates a sync, which is a named replication event containing
information about what 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 or deactivate 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_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.

"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 a single 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
be persistent.

"kidsalive"
Boolean indicating whether or not the sync child processes (KID)
should be persistent.

"autokick"
Boolean indicating whether or not 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 indicating whether or not to analyze tables after every
sync. Off by default.

"track_rates"
Boolean indicating whether or not to track synchronization rates.

"rebuild_index"
Boolean indicating whether or not to rebuild indexes after every
sync.

update table

bucardo update table [schema].table db=actual_db_name

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

"db"
The name of the database from which to read the table information.
Should be a name 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 kick messages when it's modified. Overrides the "autokick"
parameter of any syncs of 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.

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
than once. 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;

o "db" or "database"

Use the "--force" option to clear out related tables and groups
instead of erroring out.

o "dbgroup"

o "relgroup"

o "sync"

o "table"

o "sequence"

o "customcols"

o "customname"

o "customcode"

Aliases:

"delete"
"del"

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 that the sync fire: it may 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 is treated as a timeout. If this number
is zero, the bucardo command will not return until 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 will cause 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 to multiple targets, the time that each
target takes from the start of the kick is also 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 by using the backspace character. This may
not be wanted if running a kick, for example, via a cronjob, so
turning --notimer on will simply 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. This only applies to active syncs and only takes effect
if Bucardo is currently running. The keyword '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
Bucardo configuration. This configuration is a series of key/value
pairs that configure 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
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 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.3.1.

"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.3.1.

"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 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.

"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|<setting> [<setting>...]

Shows the current Bucardo settings. Use the keyword "all" to see all
the settings, 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.

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:

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 show the 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 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 that 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.

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
It is usually easier to set most of these options at the top of the
script, or make an alias for them, as they will not change very often
if at all.

"-d"
"--db-name"
bucardo --db-name widgets
bucardo -d bricolage

Name of the Bucardo database to which to connect.

"-U"
"--db-user"
bucardo --db-user postgres
bucardo -U Mom

User name to use when connecting to the Bucardo database.

"-P"
"--db-pass"
bucardo --db-pass s3cr1t
bucardo -P lolz

Password to use when connecting to the Bucardo database.

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

Host name to use when connecting to the Bucardo database.

"-p"
"--db-port"
bucardo --db-port 7654

Port number to connect to when connecting to the Bucardo database.

"--bucardorc"
bucardo --bucardorc myrcfile

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

"--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 <http://bucardo.org>, file GitHub Issues
<http://github.com/bucardo/bucardo/issues>, or post to our email list
<https://mail.endcrypt.com/mailman/listinfo/bucardo-general>.

DragonFly On-Line Manual Pages

NAME

VERSION

USAGE

DESCRIPTION

COMMANDS

OPTIONS

COMMAND DETAILS

OPTIONS DETAILS

FILES

ENVIRONMENT VARIABLES

BUGS

SEE ALSO

COPYRIGHT