From be0339cc4c7d7cb3358bfa9e0042c19f59d842e7 Mon Sep 17 00:00:00 2001 From: =?utf8?q?C=C3=A9dric=20Villemain?= Date: Fri, 25 Nov 2011 14:45:08 +0100 Subject: [PATCH] doc/londiste3.txt: add londiste3 manpage Up to date with --help Londiste man page is mostly written, it lacks maybe a QUICK START. --- doc/londiste3.txt | 357 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 357 insertions(+) create mode 100644 doc/londiste3.txt diff --git a/doc/londiste3.txt b/doc/londiste3.txt new file mode 100644 index 00000000..16865920 --- /dev/null +++ b/doc/londiste3.txt @@ -0,0 +1,357 @@ + += londiste3(1) = + +== NAME == + +londiste3 - tool for managing trigger-based replication for PostgreSQL. + +== SYNOPSIS == + + londiste3 command [subcommand] [options] + +== DESCRIPTION == + +Londiste allows to setup and administer the replication, and is run as a +daemon to handle the replication itself. (Londiste is just a complex +PgQ Consumer). + +See <> below to start your first trigger-based +replication in few steps. + +The 'command' is one of Node, Replication, Information or Internal +commands listed below. + +Londiste introduces the notion of 'takeover', it is the action when a +local node takes over the work of another node. The other node can be a +root node or a branch node and it can be dead or alive when the action +is run. + +Londiste also allows, among many other features, cascading replication, +partial replication and custom handlers for replication. + +== GENERAL OPTIONS == + + -V, --version:: + Print version info and exit. + + -h, --help:: + Show this help message and exit. + + -q, --quiet:: + Log only errors and warnings. + + -v, --verbose:: + Log verbosely. + + -d, --daemon:: + Run in daemon mode (go background). + +== SPECIFIC OPTIONS == + + --ini:: + Display sample ini file. + + --set="'param=val[,param=value]'":: + Override config setting. + +== DAEMON OPTIONS == + + -r, --reload:: + Reload config (send SIGHUP). + + -s, --stop:: + Stop program safely (send SIGINT). + + -k, --kill:: + Kill program immediately (send SIGTERM). + +== REPLICATION EXTRA ARGUMENTS == + + --rewind:: + Change queue position according to destination. + + --reset:: + Reset queue position on destination side. + +== NODE INITIALIZATION COMMANDS == + +Initialization commands are the only ones that requires a connection +string argument. It is the connection string that Londiste3 will store, +other nodes will use it to connect to the current node. + +=== create-root === + +Initializes a Master node. + +The is the name of the node, it should be unique. +The argument is the connection string to the database on the +Master node. + +=== create-branch --provider= === + +Initializes a Slave node which can be used as a reference for other +nodes. + +The is the name of the node, it should be unique. +The argument is the connection string to the database on the +current node and is the connection string to the +provider database (it can be a root node or a branch node). + +=== create-leaf --provider= === + +Initializes a Slave node which can not be used as a reference for other +nodes. + +The is the name of the node, it should be unique. +The argument is the connection string to the database on the +current node and is the connection string to the +provider database (it can be a root node or a branch node). + + --merge='qname':: + combined queue name + +== NODE ADMINISTRATION COMMANDS == + +=== pause === + +Pause the consumer: the replication of the events is stopped and can be +resumed later. + +=== resume === + +When the consumer has been paused, let it replay again. + +=== change-provider === + +Make become the new provider for the current node. + +TODO: londiste.py need update (param change from --provider) + +=== takeover [--target=] [--all] [--dead] === + +This command allows to achieve failover and switchover for any of your +providers (root or branch nodes). + + --target='tonode':: + Target node of the takeover. + + --all:: + In addition to take over the work from the 'fromnode', make other + nodes change their provider to the current node. + + --dead:: + Don't wait to take the new role and flag the 'fromnode' as dead. + + --dead='deadnode':: + Assume node is dead. + TODO : why use this one ? + + --dead-root:: + Old node was root. + + --dead-branch:: + Old node was branch + +=== drop-node === + +Remove the node from the Londiste replication. + +Londiste triggers on the node are removed but Londiste or PgQ are not +removed. + +=== tag-dead === + +Tag the node as dead, the command can be run from any node in the +replication. + +=== tag-alive === + +Tag the node as alive, the command can be run from any node in the +replication. + +== INFORMATION COMMANDS == + +=== status === + +Show status of the replication viewed by the current node. + +The output is a tree of the members of the replication with their lags, +last tick, status and the number of tables in state: ok/half/ignored +(replicated, initial copy not finnished, table not replicated locally). + +=== members === + +Show members of the replication viewed by the current node. + +Output the nodes name, status and node location (connection string to +the node). + +=== show-consumers [--node] === + +TODO: command is not working + +== REPLICATION DAEMON COMMAND == + +=== worker === + +Replay events to subscriber: it is needed to make the replication active +as it will start to replay the events. + +== REPLICATION ADMINISTRATION COMMANDS == + +=== add-table [args] === + +Add the table to the replication. + +See <> below for the list of possible arguments. + +=== remove-table
=== + +Remove the table from the replication. + +=== add-seq [args] === + +Add the sequence to the replication. + +See <> below for the list of possible arguments. + +=== remove-seq === + +Remove the sequence from the replication. + +=== tables === + +Show all tables on provider. + +=== seqs === + +Show all sequences on provider. + +=== missing === + +List tables subscriber has not yet attached to. + +=== resync
=== + +Do full copy of the table, again. + +== ADD ARGUMENTS [[add_args]] == + + --all:: + Include all possible tables. + + --dest-table='table':: + Redirect changes to different table. + + --force:: + Ignore table differences. + + --expect-sync:: + No copy needed. + + --skip-truncate:: + Keep old data. + + --create:: + Create table/sequence if not exist, with minimal schema. + + --create-full:: + Create table/sequence if not exist, with full schema. + + --trigger-flags='trigger_flags':: + Trigger creation flags, see below for details. + + --trigger-arg='trigger_arg':: + Custom trigger arg (can be specified multiply times). + + --no-triggers:: + Dont put triggers on table (makes sense on leaf node). + + --handler='handler':: + Custom handler for table. + + --handler-arg='handler_arg':: + Argument to custom handler. + + --copy-condition='copy_condition':: + Set WHERE expression for copy. + + --merge-all:: + Merge tables from all source queues. + + --no-merge:: + Don't merge tables from source queues. + + --max-parallel-copy='max_parallel_copy':: + Max number of parallel copy processes. + +Trigger creation flags (default: AIUDL): + +- I - ON INSERT +- U - ON UPDATE +- D - ON DELETE +- Q - use pgq.sqltriga() as trigger function +- L - use pgq.logutriga() as trigger function +- B - BEFORE +- A - AFTER +- S - SKIP + +== REPLICATION EXTRA COMMANDS == + +=== check === + +Compare table structure on both sides. + +=== fkeys === + +Print out fkey drop/create commands. + +=== compare [
] === + +Compare table contents on both sides. + +=== repair [
] [--force] === + +Repair data on subscriber. + + --force:: + Ignore lag. + +=== execute [filepath] === + +Execute SQL files on each nodes of the set. + +=== show-handlers ['handler'] === + +Show info about all or a specific handler. + +== INTERNAL COMMAND == + +=== copy === + +Copy table logic. + +== EXIT STATUS == + + 0:: + Successful program execution. + +== ENVIRONMENT == + +PostgreSQL environment variables can be used. + +== EXAMPLES [[examples]] == + +Londiste is provided with HowTos to help you make your fisrt steps: + +- How to set up simple replication. +- How to set up cascaded replication. +- How to set up table partitioning (handlers). + + + + + + + + -- 2.39.5