1BUCARDO(1) User Contributed Perl Documentation BUCARDO(1)
2
6 bucardo - utility script for controlling the Bucardo program
7
9 This document describes version 5.4.1 of bucardo
10
12 bucardo [<options>] <command> [<action>] [<command-options>] [<command-params>]
13
15 The bucardo script is the main interaction to a running Bucardo
16 instance. It can be used to start and stop Bucardo, add new items, kick
17 syncs, and even install and upgrade Bucardo itself. For more complete
18 documentation, please view the wiki <http://bucardo.org/>.
19
21 Run "bucardo help <command>" for additional details
22 "install"
24 Installs the Bucardo configuration database.
25 "upgrade"
27 Upgrades the Bucardo configuration database to the latest schema.
28 "start [<start options>] [<reason>]"
30 Starts Bucardo.
31 "stop [<reason>]"
33 Stops Bucardo.
34 "restart [<start options>] [<reason>]"
36 Stops and starts Bucardo.
37 "list <type> [<regex>]"
39 Lists objects managed by Bucardo.
40 "add <type> <name> <parameters>"
42 Adds a new object.
43 "update <type> <name> <parameters>"
45 Updates an object.
46 "remove <type> <name> [<name>...]"
48 Removes one or more objects.
49 "kick <syncname> [<sync options>] [<syncname>...] [<timeout>]"
51 Kicks off one or more syncs.
52 "reload config"
54 Sends a message to all CTL and KID processes asking them to reload
55 the Bucardo configuration.
56 "reopen"
58 Sends a message to all Bucardo processes asking them to reopen any
59 log files they may have open. Call this after you have rotated the
60 log file(s).
61 "show all|<setting> [<setting>...]"
63 Shows the current Bucardo settings.
64 "<set <setting=value" [<setting=value>...] >>
66 Sets one or more configuration setting..
67 "ping [<timeout>]"
69 Sends a ping notice to the MCP process to see if it will respond.
70 "status [<status options>] <syncname> [<syncname>...]"
72 Shows the brief status of syncs in a tabular format.
73 "activate <syncname> [<syncname>...] [<timeout>]"
75 Activates one or more named syncs.
76 "deactivate <syncname> [<syncname>...] [<timeout>]"
78 Deactivates one or more named syncs.
79 "message <body>"
81 Sends a message to the running Bucardo logs.
82 "reload [<syncname> [<syncname>...]]"
84 Sends a message to one or more sync processes, instructing them to
85 reload.
86 "inspect <type> <name> [<name>...]"
88 Inspects one or more objects of a particular type.
89 "validate all|<syncname> [<syncname>...]"
91 Validates one or more syncs.
92 "purge all|<table> [<table>...]"
94 Purges the delta and track tables for one or more tables, for one
95 or more databases.
96 "delta [<database(s)>]"
98 Show the delta counts for each source target.
99 "help [<command> [<action>]]"
101 Shows help.
102
104 -d --db-name NAME Database name.
105 -U --db-user USER Database user name.
106 -P --db-pass PASS Database password.
107 -h --db-host HOST Database server host name.
108 -p --db-port PORT Database server port number.
109 --bucardorc FILE Use specified .bucardorc file.
110 --no-bucardorc Do not use .bucardorc file.
111 --quiet Incremental quiet.
112 --verbose Incremental verbose mode.
113 -? --help Output basic help and exit.
114 --version Print the version number and exit.
115 --dryrun Do not perform any actual actions.
116 --confirm Require direct confirmation before changes.
117
119 Most of the commands take parameters. These may be passed after the
120 command name and, where appropriate, an object name. Parameters take
121 the form of key/value pairs separated by an equal sign ("="). For
122 example:
123 bucardo add db sea_widgets dbname=widgets host=db.example.com
125 Here "dbname" and <host> are parameters.
127 Many of the commands also use command-line options, which are specified
129 in the normal way. For example, the "bucardo add db" command could also
130 be written as:
131 bucardo add db sea_widgets --dbname widgets --dbhost db.example.com
133 However, parameters and options are not directly interchangeable in all
135 cases. See the documentation for individual commands for their
136 supported options.
137 install
139 bucardo install
140 Installs the Bucardo schema from the file bucardo.schema into an
142 existing Postgres cluster. The user "bucardo" and database "bucardo"
143 will be created first as needed. This is an interactive installer, but
144 you can supply the following values from the command line:
145 "--dbuser"
147 defaults to postgres
148 "--dbname"
150 defaults to postgres
151 "--dbport"
153 defaults to 5432
154 "--pid-dir"
156 defaults to /var/run/bucardo/
157 upgrade
159 bucardo upgrade
160 Upgrades an existing Bucardo installation to the current version of the
162 bucardo database script. Requires that bucardo and the bucardo.schema
163 file be the same version. All changes should be backwards compatible,
164 but you may need to re-validate existing scripts to make sure changes
165 get propagated to all databases.
166 start
168 bucardo start "Reason"
169 Starts Bucardo. Fails if the MCP process is running (determined if its
171 PID file is present). Otherwise, starts cleanly by first issuing the
172 equivalent of a stop to ask any existing Bucardo processes to exit, and
173 then starting a new Bucardo MCP process. A short reason and name should
174 be provided - these are written to the "reason_file" file
175 (./bucardo.restart.reason.txt by default) and sent in the email sent
176 when Bucardo has been started up. It is also appended to the reason
177 log, which has the same name as the the "reason_file" but ends in .log.
178 The options for the "start" command are:
180 "--sendmail"
182 Tells Bucardo whether or not to send mail on interesting events:
183 startup, shutdown, and errors. Default is on.
184 "--extra-name string"
186 A short string that will be appended to the version string as
187 output by the Bucardo process names. Mostly useful for debugging.
188 "--log-destination destination"
190 Determines the destination for logging output. The supported values
191 are:
192 "stderr"
194 "stdout"
195 "syslog"
196 "none"
197 A file system directory.
198 May be specified more than once, which is useful for, e.g., logging
200 both to a directory and to syslog. If "--log-destination" is not
201 specified at all, the default is to log to files in
202 /var/log/bucardo.
203 "--log-separate"
205 Forces creation of separate log files for each Bucardo process of
206 the form "log.bucardo.X.Y", where X is the type of process (MCP,
207 CTL, or KID), and Y is the process ID.
208 "--log-extension string"
210 Appends the given string to the end of the default log file name,
211 log.bucardo. A dot is added before the name as well, so a log
212 extension of "rootdb" would produce a log file named
213 log.bucardo.rootdb.
214 "--log-clean"
216 Forces removal of all old log files before running.
217 "--debug"
219 "--no-debug"
220 Enable or disable debugging output. Disabled by default.
221 "--exit-on-nosync"
223 "--no-exit-on-nosync"
224 On startup, if Bucardo finds no active syncs, it normally will
225 continue to run, requiring a restart once syncs are added. This is
226 useful for startup scripts and whatnot.
227 If, however, you want it to exit when there are no active syncs,
229 pass the "--exit-on-nosync" option. You can also be explicit that
230 it should not exit when there are no syncs by passing
231 "--no-exit-on-nosync". This is the default value.
232 stop
234 bucardo stop "Reason"
235 Forces Bucardo to quit by creating a stop file which all MCP, CTL, and
237 KID processes should detect and cause them to exit. Note that active
238 syncs will not exit right away, as they will not look for the stop file
239 until they have finished their current run. Typically, you should scan
240 the list of processes after running this program to make sure that all
241 Bucardo processes have stopped. One should also provide a reason for
242 issuing the stop - usually this is a short explanation and your name.
243 This is written to the "reason_file" file (./bucardo.restart.reason.txt
244 by default) and is also used by Bucardo when it exits and sends out
245 mail about its death. It is also appended to the reason log, which has
246 the same name as the the "reason_file" but ends in .log.
247 restart
249 bucardo restart "Reason"
250 Stops bucardo, waits for the stop to complete, and then starts it
252 again. Supports the same options as <"start"/start>. Useful for start
253 scripts. For getting just CTL and KID processes to recognize newly
254 added, updated, or removed objects, use the "reload" command, instead.
255 list
257 bucardo list <type> <regex>
258 Lists summary information about Bucardo objects. The supported types
260 are:
261 · "database"
263 · "dbgroup"
265 · "relgroup"
267 · "sync"
269 · "table"
271 · "sequence"
273 · "customcode"
275 · "customname"
277 · "customcols"
279 · "all"
281 The "all" option will list information about all object types.
283 The optional "regex" option can be used to filter the list to only
285 those matching a regular expression.
286 add
288 bucardo add <type> <name> <parameters>
289 Adds a new object to Bucardo. The "type" specifies the type of object
291 to add, while the "name" should be the name of the object. The
292 supported types include:
293 "db"
295 "dbgroup"
296 "table"
297 "sequence"
298 "all tables"
299 "all sequences"
300 "relgroup"
301 "sync"
302 "customname"
303 "customcols"
304 add db
306 bucardo add db <name> dbname=actual_name port=xxx host=xxx user=xxx
308 Adds one or more new databases. The "name" is the name by which the
310 database will be known to Bucardo, and must be unique. This may vary
311 from the actual database name, as multiple hosts might have databases
312 with the same name. Multiple databases can be added by separating the
313 names with commas. Options that differ between the databases should be
314 separated by a matching commas. Example:
315 bucardo add db alpha,beta dbname=sales host=aa,bb user=bucardo
317 This command will attempt an immediate test connection to the added
319 database(s). The supported named parameters are:
320 "dbname"
322 The actual name of the database. Required unless using a service
323 file.
324 "type"
326 The type of the database. Defaults to "postgres". Currently
327 supported values are:
328 · "postgres"
330 · "drizzle"
332 · "mongo"
334 · "mysql"
336 · "maria"
338 · "oracle"
340 · "redis"
342 · "sqlite"
344 "user"
346 The username Bucardo should use when connecting to this database.
347 "pass"
349 The password Bucardo should use when connecting to this database.
350 It is recommended that you use a .pgpass file rather than entering
351 the password here.
352 "host"
354 The host Bucardo should use when connecting to this database.
355 Defaults to the value of the $PGHOSTADDR or $PGHOST environment
356 variables, if present.
357 "port"
359 The port Bucardo should use when connecting to this database.
360 Defaults to the value of the $PGPORT environment variable, if
361 present.
362 "conn"
364 Additional connection parameters, e.g. "sslmode=require".
365 "service"
367 The service name Bucardo should use when connecting to this
368 database.
369 "status"
371 Initial status of this database. Defaults to "active" but can be
372 set to "inactive".
373 "dbgroup"
375 Name of the database group this database should belong to.
376 "addalltables"
378 Automatically add all tables from this database.
379 "addallsequences"
381 Automatically add all sequences from this database.
382 "server_side_prepares"
384 "ssp"
385 Set to 1 or 0 to enable or disable server-side prepares. Defaults
386 to 1.
387 "makedelta"
389 Set to 1 or 0 to enable or disable makedelta. Defaults to 0.
390 Additional parameters:
392 "--force"
394 Forces the database to be added without running a connection test.
395 Note: As a convenience, if the "dbuser" value is its default value,
397 "bucardo", in the event that Bucardo cannot connect to the database, it
398 will try connecting as "postgres" and create a superuser named
399 "bucardo". This is to make things easier for folks getting started with
400 Bucardo, but will not work if it cannot connect as "postgres", or if it
401 the connection failed due to an authentication failure.
402 add dbgroup
404 bucardo add dbgroup name db1:source db2:source db3:target ...
406 Adds one or more databases to the named dbgroup. If the dbgroup doesn't
408 exist, it will be created. The database parameters should specify their
409 roles, either "source" or "target".
410 add table
412 bucardo add table [schema].table db=actual_db_name
414 Adds a table object. The table information will be read from the
416 specified database. Supported parameters:
417 "db"
419 The name of the database from which to read the table information.
420 Should be a name known to Bucardo, thanks to a previous call to
421 "add database". Required.
422 "autokick"
424 Boolean indicating whether or not the table should automatically
425 send kick messages when it's modified. Overrides the "autokick"
426 parameter of any syncs of which the table is a part.
427 "rebuild_index"
429 Boolean indicating whether or not to rebuild indexes after every
430 sync. Off by default. Optional.
431 "analyze_after_copy"
433 Boolean indicating whether or not to analyze the table after every
434 sync. Off by default. Optional.
435 "vacuum_after_copy"
437 Boolean indicating whether or not to vacuum the table after every
438 sync. Off by default. Optional.
439 "relgroup"
441 Adds the table to the named relgroup. If the relgroup does not
442 exist, it will be created. Optional.
443 "makedelta"
445 Turns makedelta magic on or off. Value is a list of databases which
446 need makedelta for this table. Value can also be "on" to enable
447 makedelta for all databases. Defaults to "off".
448 "strict_check"
450 Boolean indicating whether or not to be strict when comparing the
451 table between syncs. If the columns have different names or data
452 types, the validation will fail. But perhaps the columns are
453 allowed to have different names or data types. If so, disable
454 "strict_check" and column differences will result in warnings
455 rather than failing the validation. Defaults to true.
456 add sequence
458 bucardo add sequence [schema].sequence relgroup=xxx
460 "db"
462 The name of the database from which to read the sequence
463 information. Should be a name known to Bucardo, thanks to a
464 previous call to "add database". Required.
465 "relgroup"
467 Adds the sequence to the named relgroup. If the relgroup does not
468 exist, it will be created. Optional.
469 add all tables
471 bucardo add all tables [relgroup=xxx] [pkonly]
473 Adds all the tables in all known databases or in a specified database.
475 Excludes tables in the "pg_catalog", "information_schema", and
476 "bucardo" schemas. (Yes, this means that you cannot replicate the
477 Bucardo configuration database using Bucardo. Sorry about that.)
478 Supported options and parameters:
479 "db"
481 "--db"
482 Name of the database from which to find all the tables to add. If
483 not provided, tables will be added from all known databases.
484 "schema"
486 "--schema"
487 "-n"
488 Limit to the tables in the specified comma-delimited list of
489 schemas. The options may be specified more than once.
490 "exclude-schema"
492 "--exclude-schema"
493 "-N"
494 Exclude tables in the specified comma-delimited list of schemas.
495 The options may be specified more than once.
496 "table"
498 "--table"
499 "-t"
500 Limit to the specified tables. The options may be specified more
501 than once.
502 "exclude-table"
504 "--exclude-table"
505 "-T"
506 Exclude the specified tables. The options may be specified more
507 than once.
508 "relgroup"
510 "--relgroup"
511 Name of the relgroup to which to add new tables.
512 "pkonly"
514 Exclude tables without primary keys.
515 add all sequences
517 bucardo add all sequences relgroup=xxx
519 Adds all the sequences in all known databases or in a specified
521 database. Excludes sequences in the "pg_catalog",
522 "information_schema", and "bucardo" schemas. (Yes, this means that you
523 cannot replicate the Bucardo configuration database using Bucardo.
524 Sorry about that.) Supported options and parameters:
525 "db"
527 "--db"
528 Name of the database from which to find all the sequences to add.
529 If not provided, sequences will be added from all known databases.
530 "schema"
532 "--schema"
533 "-n"
534 Limit to the sequences in the specified comma-delimited list of
535 schemas. The options may be specified more than once.
536 "exclude-schema"
538 "--exclude-schema"
539 "-N"
540 Exclude sequences in the specified comma-delimited list of schemas.
541 The options may be specified more than once.
542 "relgroup"
544 "--relgroup"
545 Name of the relgroup to which to add new tables or sequences.
546 add relgroup
548 bucardo add relgroup name
550 bucardo add relgroup name table, sequence, ...
551 Adds a relgroup. After the name, pass in an optional list of tables
553 and/or sequences and they will be added to the group.
554 add sync
556 bucardo add sync name relgroup=xxx dbs=xxx
558 Adds a sync, which is a named replication event containing information
560 about what to replicate from where to where. The supported parameters
561 are:
562 "dbs"
564 The name of a dbgroup or comma-delimited list of databases. All of
565 the specified databases will be synchronized. Required.
566 "dbgroup"
568 The name of a dbgroup. All of the databases within this group will
569 be part of the sync. If the dbgroup does not exists and a separate
570 list of databases is given, the group will be created and
571 populated.
572 "relgroup"
574 The name of a relgroup to synchronize. All of the tables and/or
575 sequences in the relgroup will be synchronized. Required unless
576 "tables" is specified.
577 "tables"
579 List of tables to add to the sync. This implicitly creates a
580 relgroup with the same name as the sync. Required unless "relgroup"
581 is specified.
582 "status"
584 Indicates whether or not the sync is active. Must be either
585 "active" or "inactive". Defaults to "active".
586 "rebuild_index"
588 Boolean indicating whether or not to rebuild indexes after every
589 sync. Defaults to off.
590 "lifetime"
592 Number of seconds a KID can live before being reaped. No limit by
593 default.
594 "maxkicks"
596 Number of times a KID may be kicked before being reaped. No limit
597 by default.
598 "conflict_strategy"
600 The conflict resolution strategy to use in the sync. Supported
601 values:
602 "bucardo_source"
604 The rows on the "source" database always "win". In other words,
605 in a conflict, Bucardo copies rows from source to target.
606 "bucardo_target"
608 The rows on the "target" database always win.
609 "bucardo_skip"
611 Any conflicting rows are simply not replicated. Not recommended
612 for most cases.
613 "bucardo_random"
615 Each database has an equal chance of winning each time. This is
616 the default.
617 "bucardo_latest"
619 The row that was most recently changed wins.
620 "bucardo_abort"
622 The sync is aborted on a conflict.
623 "onetimecopy"
625 Determines whether or not a sync should switch to a full copy mode
626 for a single run. Supported values are:
627 0: off
629 1: always full copy
630 2: only copy tables that are empty on the target
631 "stayalive"
632 Boolean indicating whether or not the sync processes (CTL) should
633 be persistent. Defaults to false.
634 "kidsalive"
636 Boolean indicating whether or not the sync child processes (KID)
637 should be persistent. Defaults to false.
638 "autokick"
640 Boolean indicating whether or not tables in the sync should
641 automatically send kick messages when they're modified. May be
642 overridden by the "autokick" parameter of individual tables.
643 "checktime"
645 An interval specifying the maximum time a sync should go before
646 being kicked. Useful for busy systems where you don't want the
647 overhead of notify triggers.
648 "priority"
650 An integer indicating the priority of the sync. Lower numbers are
651 higher priority. Currently used only for display purposes.
652 "analyze_after_copy"
654 Boolean indicating whether or not to analyze tables after every
655 sync. Off by default. Optional.
656 "overdue"
658 An interval specifying the amount of time after which the sync has
659 not run that it should be considered overdue. "check_bucardo_sync"
660 issues a warning when a sync has not been run in this amount of
661 time.
662 "expired"
664 An interval specifying the amount of time after which the sync has
665 not run that it should be considered expired. "check_bucardo_sync"
666 issues a critical message when a sync has not been run in this
667 amount of time.
668 "track_rates"
670 Boolean indicating whether or not to track synchronization rates.
671 "rebuild_index"
673 Boolean indicating whether or not to rebuild indexes after every
674 sync. Off by default. Optional.
675 "strict_check"
677 Boolean indicating whether or not to be strict when comparing
678 tables in the sync. If the columns have different names or data
679 types, the validation will fail. But perhaps the columns are
680 allowed to have different names or data types. If so, disable
681 "strict_check" and column differences will result in warnings
682 rather than failing the validation. Defaults to true.
683 add customname
685 bucardo add customname oldname newname [db=name] [sync=name]
687 Creates a new Bucardo custom name mapping. This allows the tables
689 involved in replication to have different names on different databases.
690 The "oldname" must contain the schema as well as the table name (if the
691 source database supports schemas). The optional parameters limit it to
692 one or more databases, and/or to one or more syncs. Supported
693 parameters:
694 "sync"
696 A sync to which to add the customname. May be specified multiple
697 times.
698 "database"
700 "db"
701 A database for which to add the customname. May be specified
702 multiple times.
703 add customcols
705 bucardo add customcols tablename select_clause [sync=x db=x]
707 Specify the list of columns to select from when syncing. Rather than
709 the default "SELECT *" behavior, you can specify any columns you want,
710 including the use of function call return values and things not in the
711 source column list. The optional parameters limit it to one or more
712 databases, and/or to one or more syncs. Some examples:
713 bucardo add customcols public.foobar "select a, b, c"
715 bucardo add customcols public.foobar "select a, upper(b) AS b, c" db=foo
716 bucardo add customcols public.foobar "select a, b, c" db=foo sync=abc
717 Supported parameters:
719 "sync"
721 A sync to which to add the customcols. May be specified multiple
722 times.
723 "database"
725 "db"
726 A database for which to add the customcols. May be specified
727 multiple times.
728 add customcode
730 bucardo add customcode <name> <whenrun=value> <src_code=filename> [optional information]
732 Adds a customcode, which is a Perl subroutine that can be run at
734 certain points in the sync process. It might handle exceptions, handle
735 conflicts, or just run at certain times with no expectation of
736 functionality (e.g., before Bucardo drops triggers). Metadata about
737 that point will be passed to the subroutine as a hash reference.
738 Supported parameters:
740 "name"
742 The name of the custom code object.
743 "about"
745 A short description of the custom code.
746 "whenrun"
748 "when_run"
749 A string indicating when the custom code should be run. Supported
750 values include:
751 "before_txn"
753 "before_check_rows"
754 "before_trigger_drop"
755 "after_trigger_drop"
756 "after_table_sync"
757 "exception"
758 "conflict"
759 "before_trigger_enable"
760 "after_trigger_enable"
761 "after_txn"
762 "before_sync"
763 "after_sync"
764 "getdbh"
765 Boolean indicating whether or not Perl DBI database handles should
766 be provided to the custom code subroutine. If true, database
767 handles will be provided under the "dbh" key of the hash reference
768 passed to the subroutine. The value under this key will be a hash
769 reference mapping database names to their respective handles.
770 "sync"
772 Name of the sync with which to associate the custom code.
773 "relation"
775 Name of the table or sequence with which to associate the custom
776 code.
777 "status"
779 The current status of this customcode. Anything other than "active"
780 means the code is not run.
781 "priority"
783 Number indicating the priority in which order to execute custom
784 codes. Lower numbers are higher priority. Useful for subroutines
785 that set "lastcode" in order to cancel the execution of subsequent
786 custom codes for the same "when_run".
787 "src_code"
789 File from which to read the custom code Perl source.
790 The body of the Perl subroutine should be implemented in the "src_code"
792 file, and not inside a "sub" declaration. When called, it will be
793 passed a single hash reference with the following keys:
794 "syncname"
796 The name of the currently-executing sync.
797 "version"
799 The version of Bucardo executing the sync.
800 "sourcename"
802 The name of the source database.
803 "targetname"
805 The name of the target database.
806 "sendmail"
808 A code reference that can be used to send email messages.
809 "sourcedbh"
811 A DBI database handle to the sync source database. Provided only to
812 custom code executed by the controller.
813 "rellist"
815 An array reference of hash references, each representing a relation
816 in the sync. Provided only to custom code executed by the
817 controller. The keys in the hash are the same as the parameters
818 supported by "add table" and "add sequence", as appropriate.
819 "schemaname"
821 The schema for the table that triggered the exception. Provided
822 only to "exception" custom codes.
823 "tablename"
825 The name of the table that triggered the exception. Provided only
826 to "exception" custom codes.
827 "error_string"
829 The string containing the actual error message. Provided only to
830 "exception" custom codes.
831 "deltabin"
833 A hash reference with the name of each source database as a key and
834 a list of all primary keys joined together with "\0". Provided only
835 to "exception" custom codes.
836 "attempts"
838 The number of times the sync has been attempted. Provided only to
839 "exception" custom codes.
840 "conflicts"
842 A hash reference of conflicting rows. The keys are the primary key
843 values, and the values are hash references with the names of the
844 databases containing the conflicting rows and true values. Provided
845 only to "conflict" custom codes.
846 The custom code subroutine may set any of these keys in the hash
848 reference to change the behavior of the sync:
849 "message"
851 Message to send to the logs.
852 "warning"
854 A warning to emit after the subroutine has returned.
855 "error"
857 An error to be thrown after the subroutine has returned.
858 "nextcode"
860 Set to send execution to the next custom code of the same type.
861 Mainly useful to exception custom codes, and supported only by
862 custom codes executed by the controller.
863 "lastcode"
865 Set to true to have any subsequent custom codes of the same type to
866 be skipped.
867 "endsync"
869 Cancels the sync altogether.
870 An example:
872 use strict;
874 use warnings;
875 use Data::Dumper;
876 my $info = shift;
878 # Let's open a file.
880 my $file = '/tmp/bucardo_dump.txt';
881 open my $fh, '>:encoding(UTF-8)', $file or do {
882 $info->{warning} = "Cannot open $file: $!\n";
883 return;
884 };
885 # Inspect $info for fun.
887 print $fh Dumper $info;
888 close $fh or $info->{warning} = "Error closing $file: $!\n";
889 # Log a message and return.
891 $info->{message} = 'IN UR DATABASEZ NORMALIZIN UR RELAYSHUNS';
892 return;
893 update
895 bucardo update <type> <name> <parameters>
896 Updates a Bucardo object. The "type" specifies the type of object to
898 update, while the "name" should be the name of the object. The
899 supported parameters for each type are the same as those for "add". The
900 supported types are:
901 "customcode"
903 "db"
904 "sync"
905 "table"
906 "sequence"
907 update customcode
909 bucardo update customcode <name> setting=value
911 Updates an existing customcode. Items that can be changed are:
913 "about"
915 A short description of the custom code.
916 "getdbh"
918 Boolean indicating whether or not Perl DBI database handles should
919 be provided to the custom code subroutine. If true, database
920 handles will be provided under the "dbh" key of the hash reference
921 passed to the subroutine. The value under this key will be a hash
922 reference mapping database names to their respective handles.
923 "name"
925 The name of the custom code object.
926 "priority"
928 Number indicating the priority in which order to execute custom
929 codes. Lower numbers are higher priority. Useful for subroutines
930 that set "lastcode" in order to cancel the execution of subsequent
931 custom codes for the same "when_run".
932 "status"
934 The current status of this customcode. Anything other than "active"
935 means the code is not run.
936 "whenrun"
938 A string indicating when the custom code should be run. Supported
939 values include:
940 "before_txn"
942 "before_check_rows"
943 "before_trigger_drop"
944 "after_trigger_drop"
945 "after_table_sync"
946 "exception"
947 "conflict"
948 "before_trigger_enable"
949 "after_trigger_enable"
950 "after_txn"
951 "before_sync"
952 "after_sync"
953 update db
955 bucardo udpate db <name> port=xxx host=xxx user=xxx pass=xxx
957 Updates a database. The "name" is the name by which the database is
959 known to Bucardo. This may vary from the actual database name, as
960 multiple hosts might have databases with the same name.
961 The supported named parameters are:
963 "dbname"
965 "db"
966 The actual name of the database.
967 "type"
969 "dbtype"
970 The type of the database. Currently supported values are:
971 · "postgres"
973 · "drizzle"
975 · "mongo"
977 · "mysql"
979 · "maria"
981 · "oracle"
983 · "redis"
985 · "sqlite"
987 "username"
989 "dbuser"
990 "user"
991 The username Bucardo should use to connect to the database.
992 "password"
994 "dbpass"
995 "pass"
996 The password Bucardo should use when connecting to the database.
997 "dbhost"
999 "pghost"
1000 "host"
1001 The host name to which to connect.
1002 "dbport"
1004 "pgport"
1005 "port"
1006 The port to which to connect.
1007 "dbconn"
1009 "pgconn"
1010 "conn"
1011 Additional connection parameters, e.g., "sslmode=require".
1012 Optional.
1013 "status"
1015 Status of the database in Bucardo. Must be either "active" or
1016 "inactive".
1017 "dbgroup"
1019 "server_side_prepares"
1020 "ssp"
1021 Enable or disable server-side prepares. Pass 1 to enable them or 0
1022 to disable them.
1023 "makedelta"
1025 Enable or disable makedelta for this database.
1026 "dbservice"
1028 "service"
1029 The service name to use for a Postgres database.
1030 "dbgroup"
1032 A comma-separated list of dbgroups to which to add the database.
1033 The database will be removed from any other dbgroups of which it
1034 was previously a member.
1035 update sync
1037 bucardo update sync syncname relgroup=xxx dbs=xxx
1039 Updates a sync, which is a named replication event containing
1041 information about what to replicate from where to where. The supported
1042 parameters are:
1043 "name"
1045 The name of the sync. Required.
1046 "dbs"
1048 The name of a dbgroup or comma-delimited list of databases.
1049 "relgroup"
1051 The name of a relgroup to synchronize.
1052 "status"
1054 Indicates whether or not the sync is active. Must be either
1055 "active" or "inactive". Note that this will not change the current
1056 run status of the sync, just mark whether it should be active or
1057 inactive on the next reload. Use the "activate sync" and
1058 <deactivate sync> commands to actually activate or deactivate a
1059 sync.
1060 "rebuild_index"
1062 Boolean indicating whether or not to rebuild indexes after every
1063 sync.
1064 "lifetime"
1066 Number of seconds a KID can live before being reaped.
1067 "maxkicks"
1069 Number of times a KID may be kicked before being reaped.
1070 "isolation_level"
1072 The transaction isolation level this sync should use. Only choices
1073 are "serializable" and "repeatable read"
1074 "conflict_strategy"
1076 The conflict resolution strategy to use in the sync. Supported
1077 values:
1078 "bucardo_source"
1080 The rows on the "source" database always "win". In other words,
1081 in a conflict, Bucardo copies rows from source to target.
1082 "bucardo_target"
1084 The rows on the "target" database always win.
1085 "bucardo_skip"
1087 Any conflicting rows are simply not replicated. Not recommended
1088 for most cases.
1089 "bucardo_random"
1091 Each database has an equal chance of winning each time.
1092 "bucardo_latest"
1094 The row that was most recently changed wins.
1095 "bucardo_abort"
1097 The sync is aborted on a conflict.
1098 "onetimecopy"
1100 Determines whether or not a sync should switch to a full copy mode
1101 for a single run. Supported values are:
1102 0: off
1104 1: always full copy
1105 2: only copy tables that are empty on the target
1106 "stayalive"
1107 Boolean indicating whether or not the sync processes (CTL) should
1108 be persistent.
1109 "kidsalive"
1111 Boolean indicating whether or not the sync child processes (KID)
1112 should be persistent.
1113 "autokick"
1115 Boolean indicating whether or not tables in the sync should
1116 automatically send kick messages when they're modified. May be
1117 overridden by the "autokick" parameter of individual tables.
1118 "checktime"
1120 An interval specifying the maximum time a sync should go before
1121 being kicked. Useful for busy systems where you don't want the
1122 overhead of notify triggers.
1123 "priority"
1125 An integer indicating the priority of the sync. Lower numbers are
1126 higher priority. Currently used only for display purposes.
1127 "analyze_after_copy"
1129 Boolean indicating whether or not to analyze tables after every
1130 sync. Off by default.
1131 "overdue"
1133 An interval specifying the amount of time after which the sync has
1134 not run that it should be considered overdue. "check_bucardo_sync"
1135 issues a warning when a sync has not been run in this amount of
1136 time.
1137 "expired"
1139 An interval specifying the amount of time after which the sync has
1140 not run that it should be considered expired. "check_bucardo_sync"
1141 issues a critical message when a sync has not been run in this
1142 amount of time.
1143 "track_rates"
1145 Boolean indicating whether or not to track synchronization rates.
1146 "rebuild_index"
1148 Boolean indicating whether or not to rebuild indexes after every
1149 sync.
1150 "strict_check"
1152 Boolean indicating whether or not to be strict when comparing
1153 tables in the sync. If the columns have different names or data
1154 types, the validation will fail. But perhaps the columns are
1155 allowed to have different names or data types. If so, disable
1156 "strict_check" and column differences will result in warnings
1157 rather than failing the validation. Defaults to true.
1158 update table
1160 bucardo update table [schema].table db=actual_db_name
1162 Updates a table object. The table information will be read from the
1164 specified database. Supported parameters:
1165 "db"
1167 The name of the database from which to read the table information.
1168 Should be a name known to Bucardo.
1169 "schemaname"
1171 The name of the schema in which the table is found.
1172 "tablename"
1174 The actual name of the table.
1175 "autokick"
1177 Boolean indicating whether or not the table should automatically
1178 send kick messages when it's modified. Overrides the "autokick"
1179 parameter of any syncs of which the table is a part.
1180 "rebuild_index"
1182 Boolean indicating whether or not to rebuild indexes after every
1183 sync.
1184 "analyze_after_copy"
1186 Boolean indicating whether or not to analyze the table after every
1187 sync.
1188 "vacuum_after_copy"
1190 Boolean indicating whether or not to vacuum the table after every
1191 sync.
1192 "relgroup"
1194 Adds the table to the named relgroup. May be specified more than
1195 once. The table will be removed from any other relgroups.
1196 "makedelta"
1198 Specifies which databases need makedelta enabled for this table.
1199 "strict_check"
1201 Boolean indicating whether or not to be strict when comparing the
1202 table between syncs. If the columns have different names or data
1203 types, the validation will fail. But perhaps the columns are
1204 allowed to have different names or data types. If so, disable
1205 "strict_check" and column differences will result in warnings
1206 rather than failing the validation. Defaults to true.
1207 update sequence
1209 bucardo update sequence [schema].sequence relgroup=xxx
1211 "db"
1213 The name of the database where the sequence lives.
1214 "schemaname"
1216 The name of the schema in which the sequence is found.
1217 "relgroup"
1219 Adds the sequence to the named relgroup. May be speci<fied more
1220 than once. The sequence will be removed from any other relgroups.
1221 remove
1223 bucardo remove <item_type> <item_name>
1224 Removes one or more objects from Bucardo. Valid item types are;
1226 · "db" or "database"
1228 Use the "--force" option to clear out related tables and groups
1230 instead of erroring out.
1231 · "dbgroup"
1233 · "relgroup"
1235 · "sync"
1237 · "table"
1239 · "sequence"
1241 · "customcols"
1243 · "customname"
1245 · "customcode"
1247 kick
1249 bucardo kick <syncname(s)> [timeout]
1250 Tells one or more named syncs to fire as soon as possible. Note that
1252 this simply sends a request that the sync fire: it may not start right
1253 away if the same sync is already running, or if the source or target
1254 database has exceeded the number of allowed Bucardo connections. If the
1255 final argument is a number, it is treated as a timeout. If this number
1256 is zero, the bucardo command will not return until the sync has
1257 finished. For any other number, the sync will wait at most that number
1258 of seconds. If any sync has not finished before the timeout, an exit
1259 value of 1 will be returned. Errors will cause exit values of 2 or 3.
1260 In all other cases, an exit value of 0 will be returned.
1261 If a timeout is given, the total completion time in seconds is also
1263 displayed. If the sync is going to multiple targets, the time that each
1264 target takes from the start of the kick is also shown as each target
1265 finishes. Options:
1266 "--retry"
1268 The number of times to retry a sync if it fails. Defaults to 0.
1269 "--retry-sleep"
1271 How long to sleep, in seconds, between each retry attempt.
1272 "--notimer"
1274 By default, kicks with a timeout argument give a running real-time
1275 summary of time elapsed by using the backspace character. This may
1276 not be wanted if running a kick, for example, via a cronjob, so
1277 turning --notimer on will simply print the entire message without
1278 backspaces.
1279 pause
1281 bucardo pause <syncname(s)>
1282 bucardo pause all
1283 bucardo resume <syncname(s)>
1284 bucardo resume all
1285 Tells one or more named syncs to temporarily pause, or to resume from a
1287 previous pause. This only applies to active syncs and only takes effect
1288 if Bucardo is currently running. The keyword 'all' can be used as well
1289 to pause or resume all known active syncs.
1290 reload config
1292 bucardo reload config
1293 bucardo reload config 30
1294 Sends a message to all CTL and KID processes asking them to reload the
1296 Bucardo configuration. This configuration is a series of key/value
1297 pairs that configure Bucardo's behavior, and not any of the objects
1298 managed by the "add", "remove", or "update" commands.
1299 By default, Bucardo will send the message and then exit. Pass an
1301 optional number and Bucardo will instead wait up to that length of time
1302 for all child processes to report completion.
1303 set
1305 bucardo set setting1=value [setting2=value]
1306 Sets one or more configuration setting table. Setting names are case-
1308 insensitive. The available settings are:
1309 "autosync_ddl"
1311 Which DDL changing conditions do we try to remedy automatically?
1312 Default: "newcol".
1313 "bucardo_version"
1315 Current version of Bucardo. Default: 5.4.1.
1316 "bucardo_vac"
1318 Do we want the automatic VAC daemon to run? Default: 1.
1319 "bucardo_initial_version"
1321 Bucardo version this schema was created with. Default: 5.4.1.
1322 "ctl_checkonkids_time"
1324 How often does the controller check on the kids health? Default:
1325 10.
1326 "ctl_createkid_time"
1328 How long do we sleep to allow kids-on-demand to get on their feet?
1329 Default: 0.5.
1330 "ctl_sleep"
1332 How long does the controller loop sleep? Default: 0.2.
1333 "default_conflict_strategy"
1335 Default conflict strategy for all syncs. Default: "bucardo_latest".
1336 "default_email_from"
1338 Who the alert emails are sent as. Default: "nobody@example.com".
1339 "default_email_host"
1341 Which host to send email through. Default: "localhost".
1342 "default_email_to"
1344 Who to send alert emails to. Default: "nobody@example.com".
1345 "email_debug_file"
1347 File to save a copy of all outgoing emails to. Default: None.
1348 "endsync_sleep"
1350 How long do we sleep when custom code requests an endsync? Default:
1351 1.0.
1352 "flatfile_dir"
1354 Directory to store the flatfile output inside of. Default: ".".
1355 "host_safety_check"
1357 Regex to make sure we don't accidentally run where we should not.
1358 Default: None.
1359 "isolation_level"
1361 The transaction isolation level all sync should use. Defaults to
1362 'serializable'. The only other valid option is 'repeatable read'
1363 "kid_deadlock_sleep"
1365 How long to sleep in seconds if we hit a deadlock error. Default:
1366 0.5. Set to -1 to prevent the kid from retrying.
1367 "kid_nodeltarows_sleep"
1369 How long do kids sleep if no delta rows are found? Default: 0.5.
1370 "kid_pingtime"
1372 How often do we ping check the KID? Default: 60.
1373 "kid_restart_sleep"
1375 How long to sleep in seconds when restarting a kid? Default: 1.
1376 "kid_serial_sleep"
1378 How long to sleep in seconds if we hit a serialization error.
1379 Default: 0.5. Set to -1 to prevent the kid from retrying.
1380 "kid_sleep"
1382 How long does a kid loop sleep? Default: 0.5.
1383 "log_conflict_file"
1385 Name of the conflict detail log file. Default:
1386 "bucardo_conflict.log".
1387 "log_level"
1389 How verbose to make the logging. Higher is more verbose. Default:
1390 "normal".
1391 "log_microsecond"
1393 Show microsecond output in the timestamps? Default: 0.
1394 "log_showlevel"
1396 Show log level in the log output? Default: 0.
1397 "log_showline"
1399 Show line number in the log output? Default: 0.
1400 "log_showpid"
1402 Show PID in the log output? Default: 1.
1403 "log_showtime"
1405 Show timestamp in the log output? 0=off 1=seconds since epoch
1406 2=scalar gmtime 3=scalar localtime. Default: 3.
1407 "mcp_dbproblem_sleep"
1409 How many seconds to sleep before trying to respawn. Default: 15.
1410 "mcp_loop_sleep"
1412 How long does the main MCP daemon sleep between loops? Default:
1413 0.2.
1414 "mcp_pingtime"
1416 How often do we ping check the MCP? Default: 60.
1417 "mcp_vactime"
1419 How often in seconds do we check that a VAC is still running?
1420 Default: 60.
1421 "piddir"
1423 Directory holding Bucardo PID files. Default: "/var/run/bucardo".
1424 "reason_file"
1426 File to hold reasons for stopping and starting. Default:
1427 "bucardo.restart.reason.txt".
1428 "reload_config_timeout"
1430 Number of seconds the "reload_config" command should wait for the
1431 reload to complete. Default: 30.
1432 "semaphore_table"
1434 Table to let apps know a sync is ongoing. Default:
1435 "bucardo_status".
1436 "statement_chunk_size"
1438 How many primary keys to shove into a single statement. Default:
1439 10000.
1440 "stats_script_url"
1442 Location of the stats script. Default: "http://www.bucardo.org/".
1443 "stopfile"
1445 Name of the semaphore file used to stop Bucardo processes. Default:
1446 "fullstopbucardo".
1447 "syslog_facility"
1449 Which syslog facility level to use. Default: "log_local1".
1450 "tcp_keepalives_count"
1452 How many probes to send. 0 indicates sticking with system defaults.
1453 Default: 0.
1454 "tcp_keepalives_idle"
1456 How long to wait between each keepalive probe. Default: 0.
1457 "tcp_keepalives_interval"
1459 How long to wait for a response to a keepalive probe. Default: 0.
1460 "vac_run"
1462 How often does the VAC process run? Default: 30.
1463 "vac_sleep"
1465 How long does VAC process sleep between runs? Default: 120.
1466 "warning_file"
1468 File containing all log lines starting with "Warning". Default:
1469 "bucardo.warning.log".
1470 show
1472 bucardo show all|<setting> [<setting>...]
1473 Shows the current Bucardo settings. Use the keyword "all" to see all
1475 the settings, or specify one or more search terms. See "set" for
1476 complete details on the configuration settings.
1477 config
1479 bucardo config show all|<setting> [<setting>...]
1480 bucardo config set <setting=value> [<setting=value>...]
1481 Deprecated interface for showing and setting configuration settings.
1483 Use the "show" and "set" commands, instead.
1484 ping
1486 bucardo ping
1487 bucardo ping 60
1488 bucardo ping 0
1489 Sends a ping notice to the MCP process to see if it will respond. By
1491 default, it will wait 15 seconds. A numeric argument will change this
1492 timeout. Using a 0 as the timeout indicates waiting forever. If a
1493 response was returned, the program will exit with a value of 0. If it
1494 times out, the value will be 1. Returns a Nagios like message starting
1495 with "OK" or "CRITICAL" for success or failure.
1496 status
1498 bucardo status [syncname(s)] [--sort=#] [--show-days] [--compress]
1499 Shows the brief status of all known syncs in a tabular format. If given
1501 one or more sync names, shows detailed information for each one. To see
1502 detailed information for all syncs, simply use "status all"
1503 When showing brief information, the columns are:
1505 1. Name
1507 The name of the sync
1508 2. State
1510 The state of the sync. Can be 'Good', 'Bad', 'Empty', 'No records
1511 found', 'Unknown', or the run state for a currently-running sync.
1512 3. Last good
1514 When the sync last successfully ran.
1515 4. Time
1517 How long it has been since the last sync success
1518 5. Last I/U
1520 The number of insert and deletes performed by the last successful
1521 sync. May also show the number of rows truncated (T) or conflicted
1522 (C), if applicable.
1523 6. Last bad
1525 When the sync last failed.
1526 7. Time
1528 How long it has been since the last sync failure
1529 The options for "status" are:
1531 "--show-days"
1533 Specifies whether or not do list the time interval with days, or
1534 simply show the hours. For example, "3d 12h 6m 3s" vs. "48h 6m 3s"
1535 "--compress"
1537 Specifies whether or not to compress the time interval by removing
1538 spaces. Mostly used to limit the width of the 'status' display.
1539 "--sort=#"
1541 Requests sorting of the 'status' output by one of the nine columns.
1542 Use a negative number to reverse the sort order.
1543 activate
1545 bucardo activate syncname [syncname2 syncname3 ...] [timeout]
1546 Activates one or more named syncs. If given a timeout argument, it will
1548 wait until it has received confirmation from Bucardo that each sync has
1549 been successfully activated.
1550 deactivate
1552 bucardo deactivate syncname [syncname2 syncname3 ...] [timeout]
1553 Deactivates one or more named syncs. If given a timeout argument, it
1555 will wait until it has received confirmation from Bucardo that the sync
1556 has been successfully deactivated.
1557 message
1559 bucardo message 'I WAS HERE'
1560 Sends a message to the running Bucardo logs. This message will appear
1562 prefixed with "MESSAGE: ". If Bucardo is not running, the message will
1563 go to the logs the next time Bucardo runs and someone adds another
1564 message.
1565 reload
1567 bucardo reload [syncname2 syncname3 ...]
1568 Sends a message to one or more sync processes, instructing them to
1570 reload. Waits for each to reload before going on to the next.
1571 Reloading consists of deactivating a sync, reloading its information
1572 from the database, and activating it again.
1573 inspect
1575 bucardo inspect <type> <name> [<name2>...]
1576 Inspects one or more objects of a particular type. The results are sent
1578 to "STDOUT". The supported types include:
1579 "table"
1581 "sync"
1582 "relgroup"
1583 validate
1585 bucardo validate all|<sync> [<sync>...]
1586 Validates one or more syncs. Use the keyword "all" to validate all
1588 syncs, or specify one or more syncs to validate.
1589 Note that this command executes a subset of all the validation done
1591 when a sync is started or activated.
1592 purge
1594 bucardo purge all|<table> [<table>...]
1595 Purges the delta and track tables for one or more tables, for one or
1597 more databases. Use the keyword "all" to validate all tables, or
1598 specify one or more tables to validate.
1599 delta
1601 bucardo delta [total] [<database>...]
1602 Show the current delta count for each source target. Provide a list of
1604 databases to limit it to just the given ones. Wildcards are allowed.
1605 Use the special name "totals" to show only the grand total.
1606 help
1608 bucardo help
1609 bucardo help <command>
1610 bucardo help <command> <action>
1611 Get help. General help can be returned, as well as help for a single
1613 command or a command and its action. Some examples:
1614 bucard help list
1616 bucard help add table
1617
1619 It is usually easier to set most of these options at the top of the
1620 script, or make an alias for them, as they will not change very often
1621 if at all.
1622 "-d"
1624 "--db-name"
1625 bucardo --db-name widgets
1626 bucardo -d bricolage
1627 Name of the Bucardo database to which to connect.
1629 "-U"
1631 "--db-user"
1632 bucardo --db-user postgres
1633 bucardo -U Mom
1634 User name to use when connecting to the Bucardo database.
1636 "-P"
1638 "--db-pass"
1639 bucardo --db-pass s3cr1t
1640 bucardo -P lolz
1641 Password to use when connecting to the Bucardo database.
1643 "-h"
1645 "--db-host"
1646 bucardo --db-host db.example.com
1647 bucardo -h db2.example.net
1648 Host name to use when connecting to the Bucardo database.
1650 "-p"
1652 "--db-port"
1653 bucardo --db-port 7654
1654 Port number to connect to when connecting to the Bucardo database.
1656 "--bucardorc"
1658 bucardo --bucardorc myrcfile
1659 Use the specified file for configuration instead of the default
1661 ./.bucardorc.
1662 "--no-bucardorc"
1664 Do not use the ./.bucardorc configuration file.
1665 "--verbose"
1667 Makes bucardo run verbosely. Default is off.
1668 "--quiet"
1670 Tells bucardo to be as quiet as possible. Default is off.
1671 "--help"
1673 Shows a brief summary of usage for bucardo.
1674
1676 In addition to command-line configurations, you can put any options
1677 inside of a file. The file .bucardorc in the current directory will be
1678 used if found. If not found, then the file ~/.bucardorc will be used.
1679 Finally, the file /etc/bucardorc will be used if available. The format
1680 of the file is option = value, one per line. Any line starting with a
1681 '#' will be skipped. Any values loaded from a bucardorc file will be
1682 overwritten by command-line options. All bucardorc files can be ignored
1683 by supplying a "--no-bucardorc" argument. A specific file can be forced
1684 with the "--bucardorc=file" option; if this option is set, bucardo will
1685 refuse to run unless that file can be read.
1686
1688 The bucardo script uses $ENV{HOME} to look for a .bucardorc file.
1689
1691 Bug reports and feature requests are always welcome, please visit
1692 bucardo.org <http://bucardo.org>, file GitHub Issues
1693 <http://github.com/bucardo/bucardo/issues>, or post to our email list
1694 <https://mail.endcrypt.com/mailman/listinfo/bucardo-general>.
1695
1697 Bucardo
1698
1700 Copyright 2006-2015 Greg Sabino Mullane <greg@endpoint.com>
1701 This program is free to use, subject to the limitations in the LICENSE
1703 file.
1704perl v5.30.0 2019-07-24 BUCARDO(1)