Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
BUCARDO(1)	      User Contributed Perl Documentation	    BUCARDO(1)

NAME
       bucardo - utility script	for controlling	the Bucardo program

VERSION
       This document describes version 5.6.0 of	bucardo

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

DESCRIPTION
       The bucardo script is the main interaction to a running Bucardo
       instance. 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 <https://bucardo.org/>.

COMMANDS
       Run "bucardo help <command>" for	additional details

       "install"
	   Installs the	Bucardo	configuration database.

       "upgrade"
	   Upgrades the	Bucardo	configuration database to the latest schema.

       "start [<start options>]	[<reason>]"
	   Starts Bucardo.

       "stop [<reason>]"
	   Stops Bucardo.

       "restart	[<start	options>] [<reason>]"
	   Stops and starts Bucardo.

       "list <type> [<regex>]"
	   Lists objects managed by Bucardo.

       "add <type> <name> <parameters>"
	   Adds	a new object.

       "update <type> <name> <parameters>"
	   Updates an object.

       "remove <type> <name> [<name>...]"
	   Removes one or more objects.

       "kick <syncname>	[<sync options>] [<syncname>...] [<timeout>]"
	   Kicks off one or more syncs.

       "reload config"
	   Sends a message to all CTL and KID processes	asking them to reload
	   the 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	or setting it via dbdsn.

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

       "dbdsn"
	   A direct DSN	to connect to a	database. Will override	all other
	   connection options if set.

       "user"
	   The username	Bucardo	should use when	connecting to this database.

       "pass"
	   The password	Bucardo	should use when	connecting to this database.
	   It is 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.

       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_checking"
	   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_checking" 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_checking"
	   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_checking" 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. Cannot be
	   used	in combination with "relation".

       "relation"
	   Name	of the table or	sequence with which to associate the custom
	   code. Cannot	be used	in combination with "sync".

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

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

       "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"
       "dbdsn"
	   A direct DSN	to connect to a	database. Will override	all other
	   connection options if set.

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

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

       "dbhost"
       "pghost"
       "host"
	   The host name to which to connect.

       "dbport"
       "pgport"
       "port"
	   The port to which to	connect.

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

       "status"
	   Status of the database in Bucardo. Must be either "active" or
	   "inactive".

       "dbgroup"
       "server_side_prepares"
       "ssp"
	   Enable or disable server-side prepares. Pass	1 to enable them or 0
	   to 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_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_checking"
	   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_checking" 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_checking"
	   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_checking" 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.6.0.

       "bucardo_vac"
	   Do we want the automatic VAC	daemon to run? Default:	1.

       "bucardo_initial_version"
	   Bucardo version this	schema was created with. Default: 5.6.0.

       "ctl_checkonkids_time"
	   How often does the controller check on the kids health? Default:
	   10.

       "ctl_createkid_time"
	   How long do we sleep	to allow kids-on-demand	to get on their	feet?
	   Default: 0.5.

       "ctl_sleep"
	   How long does the controller	loop sleep? Default: 0.2.

       "default_conflict_strategy"
	   Default conflict strategy for all syncs. Default: "bucardo_latest".

       "default_email_from"
	   Who the alert emails	are sent as. Default: "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.

       "log_timer_format"
	   The "strftime" format to use	to format the log timestamp when
	   "log_showtime" is set to 2 or 3.  Defaults to simply	the scalar
	   output of the time.

       "mcp_dbproblem_sleep"
	   How many seconds to sleep before trying to respawn. Default:	15.

       "mcp_loop_sleep"
	   How long does the main MCP daemon sleep between loops? Default:
	   0.2.

       "mcp_pingtime"
	   How often do	we ping	check the MCP? Default:	60.

       "mcp_vactime"
	   How often in	seconds	do we check that a VAC is still	running?
	   Default: 60.

       "piddir"
	   Directory holding Bucardo PID files.	Default: "/var/run/bucardo".

       "reason_file"
	   File	to hold	reasons	for stopping and starting. Default:
	   "bucardo.restart.reason.txt".

       "reload_config_timeout"
	   Number of seconds the "reload_config" command should	wait for the
	   reload to complete.	Default: 30.

       "semaphore_table"
	   Table to let	apps know a sync is ongoing. Default:
	   "bucardo_status".

       "statement_chunk_size"
	   How many primary keys to shove into a single	statement. Default:
	   10000.

       "stats_script_url"
	   Location of the stats script. Default: "http://www.bucardo.org/".

       "stopfile"
	   Name	of the semaphore file used to stop Bucardo processes. Default:
	   "fullstopbucardo".

       "syslog_facility"
	   Which syslog	facility level to use. Default:	"log_local1".

       "tcp_keepalives_count"
	   How many probes to send. 0 indicates	sticking with system defaults.
	   Default: 0.

       "tcp_keepalives_idle"
	   How long to wait between each keepalive probe. Default: 0.

       "tcp_keepalives_interval"
	   How long to wait for	a response to a	keepalive probe. Default: 0.

       "vac_run"
	   How often does the VAC process run? Default:	30.

       "vac_sleep"
	   How long does VAC process sleep between runs? Default: 120.

       "warning_file"
	   File	containing all log lines starting with "Warning". Default:
	   "bucardo.warning.log".

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

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

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

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

   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.

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

SEE ALSO
       Bucardo

COPYRIGHT
       Copyright 2006-2020 Greg	Sabino Mullane <greg@turnstep.com>

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

perl v5.32.1			  2021-03-01			    BUCARDO(1)

NAME | VERSION | USAGE | DESCRIPTION | COMMANDS | OPTIONS | COMMAND DETAILS | OPTIONS DETAILS | FILES | ENVIRONMENT VARIABLES | BUGS | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=bucardo&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help