From 46e3496b4477cb133674ba8d0c349871f6127baa Mon Sep 17 00:00:00 2001 From: Andres Freund Date: Mon, 27 Jan 2014 17:13:49 +0100 Subject: [PATCH 4/5] wal_decoding: Documentation for replication slots and changeset extraction Andres, Craig --- doc/src/sgml/catalogs.sgml | 27 +- doc/src/sgml/changesetextraction.sgml | 527 ++++++++++++++++++++++++++++++++++ doc/src/sgml/filelist.sgml | 2 + doc/src/sgml/func.sgml | 94 +++++- doc/src/sgml/postgres.sgml | 1 + doc/src/sgml/protocol.sgml | 95 ++++-- doc/src/sgml/ref/allfiles.sgml | 1 + doc/src/sgml/ref/create_table.sgml | 4 +- doc/src/sgml/ref/pg_recvlogical.sgml | 295 +++++++++++++++++++ doc/src/sgml/reference.sgml | 1 + 10 files changed, 1026 insertions(+), 21 deletions(-) create mode 100644 doc/src/sgml/changesetextraction.sgml create mode 100644 doc/src/sgml/ref/pg_recvlogical.sgml diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index dca24fc..5e680cf 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -5177,7 +5177,7 @@ For more on replication slots, - see . + see and . @@ -5210,6 +5210,13 @@ + plugin + text + + The basename of the shared object containing the output plugin this logical slot is using, or null for physical slots. + + + datoid oid pg_database.oid @@ -5243,6 +5250,24 @@ + xmin + xid + + The oldest transaction that this slot needs the database to + retain. VACUUM cannot remove catalog tuples deleted + by any later transaction. + + + + + catalog_xmin + xid + + The xmin, or oldest transaction ID, that this + slot forces to be retained in the system catalogs. + + + restart_lsn text diff --git a/doc/src/sgml/changesetextraction.sgml b/doc/src/sgml/changesetextraction.sgml new file mode 100644 index 0000000..38ac4ea --- /dev/null +++ b/doc/src/sgml/changesetextraction.sgml @@ -0,0 +1,527 @@ + + + Changeset Extraction + + Changeset Extraction + + + PostgreSQL provides infrastructure to stream the modifications performed + via SQL to external consumers which can be used to implement replication + solutions, perform auditing and similar tasks. + + + + Changeset Extraction Slot + A changeset extraction slot ("logical replication slot") is a persistent + server-side record of the replay progress of a stream of changes. A stream of + changes is read from the slot to a receiving client program. + + + The format in which those changes are streamed is determined by the output + plugin used. While an example plugin is provided, additional plugins can be + written to extend the choice of available formats without modifying any + core code. + + + Changes can be consumed either using one streaming replication protocol + (see and + ), or by calling functions + via SQL (see ). It is also possible + to write additional methods of consuming the output of a replication slot + without modifying core code + (see ). + + + + Changeset Extraction Example + + The following example shows usage of the SQL interface. + + + Before you can use changeset extraction you must edit + postgresql.conf and ensure the following parameters are + set to at least: + +wal_level = logical +max_replication_slots = 1 + + and restart PostgreSQL. Then connect to the target database (in the example + below, postgres) as a superuser. + + +postgres=# -- max_replication_slots must be nonzero and wal_level must be logical +postgres=# SHOW max_replication_slots; + max_replication_slots +----------------------- + 1 +(1 row) + +postgres=# SHOW wal_level; + wal_level +----------- + logical +(1 row) + +postgres=# -- The decoding plugin you want must be installed. If no rows are returned, +postgres=# -- then cd contrib/test_decoding && make install then re-check. +postgres=# +postgres=# select * from pg_available_extensions WHERE name = 'test_decoding'; + name | default_version | installed_version | comment +---------------+-----------------+-------------------+------------------------------------------------------------------- + test_decoding | 1.0 | 1.0 | test output plugin for changeset extraction / logical replication +(1 row) + +postgres=# SELECT * FROM pg_replication_slots; + slot_name | plugin | slottype | datoid | database | active | catalog_xmin | data_xmin | restart_decoding_lsn +-----------+--------+----------+--------+----------+--------+--------------+-----------+---------------------- +(0 rows) + +postgres=# -- Create a slot named 'regression_slot' using the output plugin 'test_decoding' +postgres=# SELECT * FROM pg_create_decoding_replication_slot('regression_slot', 'test_decoding'); + slotname | xlog_position +-----------------+--------------- + regression_slot | 0/16B1970 + +postgres=# SELECT * FROM pg_replication_slots; + slot_name | plugin | slottype | datoid | database | active | catalog_xmin | data_xmin | restart_decoding_lsn +-----------------+---------------+----------+--------+----------+--------+--------------+-----------+---------------------- + regression_slot | test_decoding | logical | 12054 | postgres | f | 690 | 0 | 0/16B1938 +(1 row) + +postgres=# -- There are no changes to see yet +postgres=# SELECT * FROM pg_decoding_slot_get_changes('regression_slot', 'now', 'include-xids', '0'); + location | xid | data +----------+-----+------ +(0 rows) + +postgres=# CREATE TABLE data(id serial primary key, data text); +CREATE TABLE + +postgres=# -- DDL isn't replicated, so all you'll see is the transaction +postgres=# SELECT * FROM pg_decoding_slot_get_changes('regression_slot', 'now', 'include-xids', '0'); + location | xid | data +-----------+-----+-------- + 0/16E1558 | 716 | BEGIN + 0/16EBAC8 | 716 | COMMIT +(2 rows) + +postgres=# -- Once changes are read once, they're consumed and not emitted +postgres=# -- in a subsequent call: +postgres=# SELECT * FROM pg_decoding_slot_get_changes('regression_slot', 'now', 'include-xids', '0'); + location | xid | data +----------+-----+------ +(0 rows) + +postgres=# BEGIN; +postgres=# INSERT INTO data(data) VALUES('1'); +postgres=# INSERT INTO data(data) VALUES('1'); +postgres=# COMMIT; + +postgres=# SELECT * FROM pg_decoding_slot_get_changes('regression_slot', 'now', 'include-xids', '0'); + location | xid | data +-----------+-----+----------------------------------------------- + 0/16EBD10 | 718 | BEGIN + 0/16EBE60 | 718 | table "data": INSERT: id[int4]:2 data[text]:1 + 0/16EBE60 | 718 | table "data": INSERT: id[int4]:3 data[text]:1 + 0/16EBE60 | 718 | COMMIT +(4 rows) + +postgres=# INSERT INTO data(data) VALUES('1'); + +postgres=# -- You can also peek ahead in the change stream without consuming changes +postgres=# SELECT * FROM pg_decoding_slot_peek_changes('regression_slot', 'now', 'include-xids', '0'); + location | xid | data +-----------+-----+----------------------------------------------- + 0/16EBE98 | 719 | BEGIN + 0/16EBF58 | 719 | table "data": INSERT: id[int4]:4 data[text]:1 + 0/16EBF58 | 719 | COMMIT +(3 rows) + +postgres=# SELECT * FROM pg_decoding_slot_peek_changes('regression_slot', 'now', 'include-xids', '0'); + location | xid | data +-----------+-----+----------------------------------------------- + 0/16EBE98 | 719 | BEGIN + 0/16EBF58 | 719 | table "data": INSERT: id[int4]:4 data[text]:1 + 0/16EBF58 | 719 | COMMIT + +postgres=# -- Remember to destroy a slot you no longer need to stop it consuming +postgres=# -- server resources: +postgres=# SELECT pg_drop_replication_slot('regression_slot'); + pg_drop_replication_slot +----------------------- + +(1 row) + + + The following example shows usage of the walsender interface using + the pg_recvlogical + shell command. It requires the replication configurations to be allowed + (see ) + and max_wal_senders to be set sufficiently high for + another connection. + + +# pg_recvlogical --slot test --init -d testdb +# pg_recvlogical --slot test -f - --start -d testdb +CTRL-Z +# psql -c "INSERT INTO data(data) VALUES('1');" +# fg +BEGIN 721 +table "data": INSERT: id[int4]:5 data[text]:1 +COMMIT 721 + + + + Changeset Extraction Concepts + + + Changeset Extraction + + + Changeset Generation + + Changeset Extraction + + Changeset Extraction is the the process of extracting all persistent + changes to a database's tables into a coherent, easy to understand format + which is easy to interpret independent of the way the changes were made. + + + In PostgreSQL changeset extraction is + implemented by decoding the WAL's contents, + which describe changes on a storage level, into an easier to interpret + format. That process is called logical decoding. + + + + + Logical Replication Slot + + + Replication Slot + + Replication Slots + + In the context of changeset extraction a replication slot represents a + stream of changes which can be replayed to a client in the order they + were made on the origin server. Each slot streams a sequence of changes + from a single database, sending each change exactly once (unless peeking + forward in the stream). + + + PostgreSQL also has streaming replication slots + (see ), but they are used somewhat + differently there. + + + + Replication slots have an identifier which is unique across all databases + in a PostgreSQL cluster. Slots persist + independently of the connection using them and are crash-safe. They can + be allocated in primary servers and hot-standby servers (streaming + replicas or archive-replaying hot standbys), so it's possible to + replicate changes over physical replication then read a logical change + stream from a physical replica server. + + + Multiple independent slots may exist for a single database. Each slot has + its own state, allowing different consumers to receive changes from + different points in the database change stream. For most applications a + separate slot is required for each changeset consumer. + + + A changeset extraction slot knows nothing about the state of the + receiver(s). It's even possible to have multiple different receivers use + the same slot at different times; they'll just get the changes following + on from when the last receiver stopped consuming them. Only one receiver + may consume changes from a slot at any given time. + + + Unused/abandoned slots + + Changeset extraction slots persist across crashes and know nothing about + the state of their consumer(s). They will prevent removal of required + resources even when there is no connection using them. This consumes + storage because neither required WAL nor required rows from the system + catalogs can be removed by VACUUM as long as they are required by a + replication slot, so if a slot is no longer required it should be + dropped. + + + Slots may be created manually, or using a client like a replication + tool. Keep this in mind when you retire a client that uses a changeset + extraction slot, like a logical replica - you may need to give it a + specific command to remove its changeset extraction slot, or drop the + slot yourself, even if you did not initially create the slot by hand. + + + + + Exported Snapshots + + When a new replication slot is created over the walsender interface a + snapshot is exported + (see ) which will show + exactly the state of the database after which all changes will be + included in the changestream. This can be used to create a new replica by + using SET TRANSACTION + SNAPSHOT to read the state of the database at the moment + the slot was created. This transaction can then be used to dump the + database's state at that point in time which afterwards can be updated + using the slot's contents without loosing any changes. + + + + + Streaming Replication Protocol Interface + + The CREATE_REPLICATION_SLOT SLOT slotname LOGICAL + options, DROP_REPLICATION_SLOT SLOT slotname + and START_REPLICATION SLOT slotname LOGICAL options + commands can be used to create, drop and stream changes from a replication + slot respectively. These commands are only available over a replication + connection; the won't work from the SQL + level. See . + + + The pg_recvlogical command + (see ) can be used to control changeset + extraction over a walsender connection. + + + + Changeset Extraction <acronym>SQL</acronym> Interface + + See for detailed + documentation on the SQL-level API for interacting with changeset + extraction. + + + Only replications slots which are consumed over the walsender interface + support being used for synchronous replication + (see ). + + + + System catalogs related to changeset extraction + + The view and the + pg_stat_replication view + in provide information about + the current state of replication slots and walsender connections + respectively. These views apply to both physical and logical replication. + + + + Changeset Extraction Output Plugins + + An example output plugin can be found in the + + contrib/test_decoding + + subdirectory of the PostgreSQL source tree. + + + Initialization Function + + _PG_output_plugin_init + + + An output plugin is loaded by dynamically loading a shared library with + the output plugin's name as the library basename. To provide the required + output plugin callbacks and to indicate that the library is actually an + output plugin it needs to provide a function named + _PG_output_plugin_init. This function is passed a + struct that needs to be filled with the callback function pointers for + individual actions. + +typedef struct OutputPluginCallbacks +{ + LogicalDecodeStartupCB startup_cb; + LogicalDecodeBeginCB begin_cb; + LogicalDecodeChangeCB change_cb; + LogicalDecodeCommitCB commit_cb; + LogicalDecodeShutdownCB shutdown_cb; +} OutputPluginCallbacks; +typedef void (*LogicalOutputPluginInit)(struct OutputPluginCallbacks *cb); + + The begin_cb, change_cb + and commit_cb callbacks are required, + while startup_cb + and shutdown_cb are optional. + + + + Output Plugin Callbacks + + An output plugin gets notified about changes that are happening via + various callbacks it needs to provide. + + + Concurrent transactions are decoded in commit order and only changes + belonging to a specific transaction are decoded inbetween + the begin and commit + callbacks. Transaction that were rolled back explicitly or implicitly + will never be + decoded. Successfull SAVEPOINTs are + folded into the transaction containing them in the order they were + exectuded within that transaction. + + + Startup Callback + + The optional startup callback is called whenever an replication slot + is created or asked to stream changes, independent of the number of + changes that are ready to be output. + +typedef void (*LogicalDecodeStartupCB) ( + struct LogicalDecodingContext *ctx, + bool is_init +); + + The is_init paramter will be true when the replication slot is being + created and false otherwise. + + + The startup callback should validate the options present in + ctx->output_plugin_options. If the output plugin needs + to have state, it can use ctx->output_plugin_private to + store it. + + + + Shutdown Callback + + The optional shutdown callback is called whenever a formerly active + replication slot is not used anymore and can be used to deallocate + resources private to the output plugin. The slot isn't necessarily being + dropped, streaming is just being stopped. + +typedef void (*LogicalDecodeShutdownCB) ( + struct LogicalDecodingContext *ctx +); + + + + + Transaction Begin Callback + + The required begin_cb callback is called whenever a + transaction start has been decoded, but only if we know that the + transaction has committed. Aborted transactions and their contents are + never decoded. + +typedef void (*LogicalDecodeBeginCB) ( + struct LogicalDecodingContext *, + ReorderBufferTXN *txn +); + + The txn parameter contains meta information about the transaction, + like the timestamp at which it committed and its xid. + + + + Transaction End Callback + + The required commit_cb callback is called whenever + a transaction commit has been + decoded. The change_cb callbacks for all modified + rows will have been called before this, if there are have been any + modified rows. + +typedef void (*LogicalDecodeCommitCB) ( + struct LogicalDecodingContext *, + ReorderBufferTXN *txn +); + + + + + Callback called for each individual change in a + transaction + + The required change_cb callback is called for every + individual row modification inside a transaction, be it + an INSERT, UPDATE + or DELETE. Even if the original command modified + several rows at once, the callback will be called indvidually for each + row. + +typedef void (*LogicalDecodeChangeCB) ( + struct LogicalDecodingContext *ctx, + ReorderBufferTXN *txn, + Relation relation, + ReorderBufferChange *change +); + + The ctx and txn parameters + have the same contents as for the begin_cb + and commit_cb callbacks, but additionally the + relation descriptor relationfor the relation the + row belongs to and a struct change describing the + row modification are passed in. + + + + Only changes in user defined tables, that are not unlogged + (see ) or temporary + (see )can be extracted using + changeset extraction. + + + + + + Functions for producing output from an output plugin + + To actually produce output output plugins can write data to + the StringInfo output buffer + in ctx->out when inside + the begin_cb, commit_cb, change_cb + callbacks. Before writing to the output + buffer OutputPluginPrepareWrite(ctx, last_write) has + to be called, and after finishing writing to the + buffer OutputPluginWrite(ctx, last_write) has to be + called to perform the write. The last_write + indicates whether a particular write was the callback's last write. + + + The following example shows how to output data to the consumer of an + output plugin: + +OutputPluginPrepareWrite(ctx, true); +appendStringInfo(ctx->out, "BEGIN %u", txn->xid); +OutputPluginWrite(ctx, true); + + + + + + Changeset Extraction Output Writers + + It is possible to add additional output methods, in addition to the SQL + and replication protocol variants, of consuming changeset extraction + data. For details look at the implementation of the SQL interface + functions + in src/backend/replication/logical/logicalfuncs.c. + Essentially three functions need to be provided, one to read WAL, one to + prepare writing output and one to write the output + (see ). + + + + Synchronous replication support for Changeset Extraction + + The Changeset Extraction support in PostgreSQL + supports being used to to + build synchronous + replication solutions, with the same user interface as synchronous + replication for streaming + replication if the walsender interface + (see ) is used to stream out + data. Clients have to send Standby status update (F) + (see ), just like streaming + replication clients do. + + + diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 09de4bd..05bed2b 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -91,6 +91,7 @@ + @@ -145,6 +146,7 @@ + diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index be548d7..d4e84ad 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -16301,8 +16301,9 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); PostgreSQL exposes a number of functions for controlling and interacting - with replication features. See - and . + with replication features. See , + + and . @@ -16361,9 +16362,98 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); command DROP_REPLICATION_SLOT. + + + + + pg_create_decoding_replication_slot + + pg_create_decoding_replication_slot(slotname text, plugin text) + + + (slotname text, xlog_position text) + + + Creates a new logical (decoding) replication slot named + slotname using the output plugin + plugin. Output plugins are listed amongst the + extensions in pg_catalog.pg_available_extensions, + but there is no specific listing of only output plugins. Same as + walsender protocol command CREATE REPLICATION SLOT ... LOGICAL. + + + + + + + pg_decoding_slot_get_changes + + pg_decoding_slot_get_changes(slotname text) + + + (location text, xid xid, data text) + + + Returns all changes in the slot slotname since + changes have been consumed last, up until the changes visible at the + time this call starts. Changes will be consumed. + + + + + + + pg_decoding_slot_peek_changes + + pg_decoding_slot_peek_changes(slotname text) + + + (location text, xid xid, data text) + + + Returns all changes in the slot slotname since + changes have been consumed last, up to the changes visible at the start + of this call. Changes will not be consumed. + + + + + + + pg_decoding_slot_get_binary_changes + + pg_decoding_slot_get_binary_changes(slotname text) + + + (location text, xid xid, data bytea) + + + Returns all changes in the slot slotname since + changes have been consumed last in binary format. Changes will be + consumed. + + + + + + + pg_decoding_slot_peek_binary_changes + + pg_decoding_slot_peek_binary_changes(slotname text) + + + (location text, xid xid, data binary) + + + Returns all changes in the slot slotname since + changes have been consumed last in binary format. Changes will not + be consumed. + +
+ diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index b47bf52..dd1709f 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -219,6 +219,7 @@ &spi; &bgworker; + &changesetextraction; diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 8d890ba..e53cc38 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1301,24 +1301,48 @@ Streaming Replication Protocol -To initiate streaming replication, the frontend sends the -replication parameter in the startup message. A boolean value -of true tells the backend to go into walsender mode, wherein a -small set of replication commands can be issued instead of SQL statements. Only -the simple query protocol can be used in walsender mode. -Passing a database as the value instructs walsender to connect to -the database specified in the dbname paramter which will in future -allow some additional commands to the ones specified below to be run. + To initiate streaming replication, the frontend sends the + replication parameter in the startup message. This accepts the + values true, false (and their 1/0 + numeric equivalents) or in 9.4 and above, database. + + + Any valid non-false value tells the backend to go into walsender mode, wherein + the small set of replication commands documented below can be issued instead + of SQL statements. Only the simple query protocol can be used in walsender + mode. + + + If replication is true, no specific + database is connected to. In this mode only a subset of walsender subcommands + are available. To use database-specific walsender commands like the logical + replication commands, replication must be set to + database and the name of a database to connect to must be + specified in the database startup packet field. + + + For the purpose of testing replication commands, you can make a replication + connection via psql or any other libpq-using + tool with a connection string including the replication option, + e.g.: + + psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" + + However it is usually more useful to use + pg_receivexlog (for physical replication) or + pg_recvlogical (for logical replication). + + The commands accepted in walsender mode are: - IDENTIFY_SYSTEM - Requests the server to identify itself. Server replies with a result - set of a single row, containing four fields: + Requests the server to identify itself. Does not require a database name + to be specified for the connection. Server replies with a result set of a + single row, containing four fields: @@ -1381,7 +1405,8 @@ The commands accepted in walsender mode are: Requests the server to send over the timeline history file for timeline - tli. Server replies with a + tli. Does not require a database + name to be specified for the connection. Server replies with a result set of a single row, containing two fields: @@ -1764,17 +1789,55 @@ The commands accepted in walsender mode are: + + START_REPLICATION SLOT slotname LOGICAL XXX/XXX + + + Instructs server to start streaming WAL for logical replication, starting + at WAL position XXX/XXX. The server can + reply with an error, e.g. if the requested section of WAL has already + been recycled. On success, server responds with a CopyBothResponse + message, and then starts to stream WAL to the frontend. + + + The output plugin associated with the selected slot is used + to process the output for streaming. + + + + SLOT slotname + + + The name of the slot to stream changes from. This parameter is required, + and must correspond to an existing logical replication slot created + with CREATE_REPLICATION_SLOT in + LOGICAL mode. + + + + + XXX/XXX + + + The WAL position to begin streaming at. + + + + + + - DROP_REPLICATION_SLOT slotname + DROP_REPLICATION_SLOT SLOT slotname - Drops a replication slot, freeing any reserved server-side resources. If - the slot is currently in use by an active connection, this command fails. + Drops a physical or logical replication slot, freeing any reserved server-side + resources. If the slot is currently in use by an active connection this command + fails. - slotname + SLOT slotname The name of the slot to drop. diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index ce7a5e3..1b0962c 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -183,6 +183,7 @@ Complete list of usable sgml source files in this directory. + diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index e0b8a4e..04e8b92 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -137,7 +137,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI - + TEMPORARY or TEMP @@ -171,7 +171,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI - + UNLOGGED diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml new file mode 100644 index 0000000..8fbb698 --- /dev/null +++ b/doc/src/sgml/ref/pg_recvlogical.sgml @@ -0,0 +1,295 @@ + + + + + pg_recvlogical + 1 + Application + + + + pg_recvlogical + Control changeset extraction + (see ) replication streams over a + walsender connection. + + + + pg_recvlogical + + + + + pg_recvlogical + + + + + + Description + + pg_recvlogical controls changeset extraction replication + slots and streams data from such replication slots. + + + It makes a replication-mode connection, so it is subject to the same + constraints as pg_receivexlog, + plus those for logical replication (see ). + + + + + + Options + + + pg_recvlogical runs in one of three modes, which + control its primary action: + + + + + + + + Create a new logical replication slot with the name specified in + , using the output plugin + , then exit. The slot is created for the + database given in . + + + + + + + + + Begin streaming changes from the logical replication slot with the name + specified in , continuing until terminated with a + signal. If the server side change stream ends with a server + shutdown / disconnect, retry in a loop unless + is specified. The stream format is determined by the output plugin + specified when the slot was created. + + + You must connect to the same as the slot was + created with to stream changes from a logical replication slot. + + + + + + + + + Drop the replication slot with the name specified in , then exit. + + + + + + + + + pg_recvlogical supports all the usual + libpq-based options. These are explained in detail in the + documentation for psql and for libpq. + + + + + + + + + Username to connect as. Must have a suitable pg_hba.conf + entry allowing replication connections. Defaults to + current operating system user name. + + + + + + + + + + The database to connect to in replication mode; see + mode descriptions for details. May be a libpq connstring instead. Defaults + to user name. + + + + + + + + + + Host or socket to connect to. See psql and libpq documentation. + + + + + + + + + + Port number to connect to. See libpq for an explanation + of default port choices when this is not specified. + + + + + + + + + + Prevent prompting for a password. Will exit with an error code if a password is + required but not available. + + + + + + + + + + Provide a password for this connection. Please use the pgservice file + (see ) or an environment variable + instead of this option. + + + + + + + + + + The following command-line options control the location and format of the + output and other replication behaviour: + + + + + + + + + Receive decoded transaction data into this file. Use - for stdout. + + + + + + + + + + + When the connection to the server is lost, do not retry in a loop, just exit. + + + + + + + + + + When creating a slot, use the specified changeset decoding output + plugin. See . This option has no + effect if the slot already exists. + + + + + + + + + + This option has the same effect as the option of the same name in pg_receivexlog. + See the description there. + + + + + + + + + + In mode, use the existing logical replication slot named + slot_name. In mode, create the + slot with this name. In mode, delete the slot with this name. + + + + + + + + + + In mode, start replication from the given LSN. + For details on the effect of this, see the documentation in + and . Ignored in other modes. + + + + + + + + + + The following additional options are available: + + + + + + + + + Output verbose (detailed) error messages suitable for debugging and fault diagnosis. + + + + + + + + + + Print the pg_recvlogical version and exit. + + + + + + + + + + Show help about pg_recvlogical command line + arguments, and exit. + + + + + + + + diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 87e8e9e..a6575f5 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -231,6 +231,7 @@ &pgDumpall; &pgIsready; &pgReceivexlog; + &pgRecvlogical; &pgRestore; &psqlRef; &reindexdb; -- 1.8.5.rc2.dirty