mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2025-02-23 19:39:53 +08:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation about binary/textual output mode for output plugins.

Browse Source 
Also improve related error message as it contributed to the confusion.

Discussion: CAB7nPqQrqFzjqCjxu4GZzTrD9kpj6HMn9G5aOOMwt1WZ8NfqeA@mail.gmail.com,
    CAB7nPqQXc_+g95zWnqaa=mVQ4d3BVRs6T41frcEYi2ocUrR3+A@mail.gmail.com

Per discussion between Michael Paquier, Robert Haas and Andres Freund

Backpatch to 9.4 where logical decoding was introduced.
This commit is contained in:
Andres Freund 2014-10-01 13:13:59 +02:00
parent ef8863844b
commit 0ef3c29a4b
3 changed files with 24 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
contrib/test_decoding/expected/binary.out
View File

@ -14,7 +14,7 @@ SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'for
-- fails, binary plugin, textual consumer -- fails, binary plugin, textual consumer
SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'force-binary', '1'); SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'force-binary', '1');
ERROR: output plugin cannot produce binary output ERROR: logical decoding output plugin "test_decoding" produces binary output, but "pg_logical_slot_get_changes(name,pg_lsn,integer,text[])" expects textual data
-- succeeds, textual plugin, binary consumer -- succeeds, textual plugin, binary consumer
SELECT data FROM pg_logical_slot_get_binary_changes('regression_slot', NULL, NULL, 'force-binary', '0'); SELECT data FROM pg_logical_slot_get_binary_changes('regression_slot', NULL, NULL, 'force-binary', '0');
data data

21
doc/src/sgml/logicaldecoding.sgml
View File

@ -355,6 +355,24 @@ CREATE TABLE another_catalog_table(data text) WITH (user_catalog_table = true);
</para> </para>
</sect2> </sect2>
<sect2 id="logicaldecoding-output-mode">
<title>Output Modes</title>
<para>
Output plugin callbacks can pass data to the consumer in nearly arbitrary
formats. For some use cases, like viewing the changes via SQL, returning
data in a datatype that can contain arbitrary data (i.e. bytea) is
cumbersome. If the output plugin only outputs textual data in the
server's encoding it can declare that by
setting <literal>OutputPluginOptions.output_mode</>
to <literal>OUTPUT_PLUGIN_TEXTUAL_OUTPUT</> instead
of <literal>OUTPUT_PLUGIN_BINARY_OUTPUT</> in
the <link linkend="logicaldecoding-output-plugin-startup">startup
callback</>. In that case all the data has to be in the server's encoding
so a <type>text</> can contain it. This is checked in assertion enabled
builds.
</para>
</sect2>
<sect2 id="logicaldecoding-output-plugin-callbacks"> <sect2 id="logicaldecoding-output-plugin-callbacks">
<title>Output Plugin Callbacks</title> <title>Output Plugin Callbacks</title>
<para> <para>
@ -405,7 +423,8 @@ typedef struct OutputPluginOptions
</programlisting> </programlisting>
<literal>output_type</literal> has to either be set to <literal>output_type</literal> has to either be set to
<literal>OUTPUT_PLUGIN_TEXTUAL_OUTPUT</literal> <literal>OUTPUT_PLUGIN_TEXTUAL_OUTPUT</literal>
or <literal>OUTPUT_PLUGIN_BINARY_OUTPUT</literal>. or <literal>OUTPUT_PLUGIN_BINARY_OUTPUT</literal>. See also
<xref linkend="logicaldecoding-output-mode"/>.
</para> </para>
<para> <para>
The startup callback should validate the options present in The startup callback should validate the options present in

4
src/backend/replication/logical/logicalfuncs.c
View File

@ -401,7 +401,9 @@ pg_logical_slot_get_changes_guts(FunctionCallInfo fcinfo, bool confirm, bool bin
ctx->options.output_type != OUTPUT_PLUGIN_TEXTUAL_OUTPUT) ctx->options.output_type != OUTPUT_PLUGIN_TEXTUAL_OUTPUT)
ereport(ERROR, ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED), (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
errmsg("output plugin cannot produce binary output"))); errmsg("logical decoding output plugin \"%s\" produces binary output, but \"%s\" expects textual data",
NameStr(MyReplicationSlot->data.plugin),
format_procedure(fcinfo->flinfo->fn_oid))));
ctx->output_writer_private = p; ctx->output_writer_private = p;