GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  BUCARDO (1)

.ds Aq ’

NAME

bucardo - utility script for controlling the Bucardo program

CONTENTS

VERSION

This document describes version 5.4.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.
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 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.

    add



  bucardo add <type> <name> <parameters>



Adds a new object to Bucardo. The type specifies the type of object to add, while the name should be the name of the object. The supported types include:
db
dbgroup
table
sequence
all tables
all sequences
relgroup
sync
customname
customcols
add db


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



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


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



This command will attempt an immediate test connection to the added database(s). The supported named parameters are:
dbname The actual name of the database. Required unless using a service file.
type 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
user The username Bucardo should use when connecting to this database.
pass The password Bucardo should use when connecting to this database. It is recommended that 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 $PGHOSTADDR or $PGHOST environment variables, if present.
port The port Bucardo should use when connecting to this database. Defaults to the value of the $PGPORT environment 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.
<B>Note:B> 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;

  # Lets 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.
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.
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:
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 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.
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.
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.
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.
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.
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

    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.4.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.4.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. <B>NameB> The name of the sync
2. <B>StateB> The state of the sync. Can be ’Good’, ’Bad’, ’Empty’, ’No records found’, ’Unknown’, or the run state for a currently-running sync.
3. <B>Last goodB> When the sync last successfully ran.
4. <B>TimeB> How long it has been since the last sync success
5. <B>Last I/UB> 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. <B>Last badB> When the sync last failed.
7. <B>TimeB> 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.

    delta



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



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

    help



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



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



  bucard help list
  bucard help add table



OPTIONS DETAILS

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

SEE ALSO

Bucardo

COPYRIGHT

Copyright 2006-2015 Greg Sabino Mullane <greg@endpoint.com>

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

Search for    or go to Top of page |  Section 1 |  Main Index


perl v5.20.3 BUCARDO (1) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.