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

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.

diff --git a/contrib/test_decoding/expected/binary.out b/contrib/test_decoding/expected/binary.out
index 4164784ab34e6d929212ef4ed2cd64986ef46a2e..6d307491f06df7714ab5f7d6e788c4edae732dfd 100644 (file)
--- a/contrib/test_decoding/expected/binary.out
+++ b/contrib/test_decoding/expected/binary.out
@@ -14,7 +14,7 @@ SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'for
 
 -- fails, binary plugin, textual consumer
 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
 SELECT data FROM pg_logical_slot_get_binary_changes('regression_slot', NULL, NULL, 'force-binary', '0');
  data 

diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index e6880d0ac58a096d16cfe11e08bd4e0c01b302b2..1f56b39df94e601ee0fe2a34afaa915b5b1f5957 100644 (file)
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -355,6 +355,24 @@ CREATE TABLE another_catalog_table(data text) WITH (user_catalog_table = true);
     
    
 
+   
+    Output Modes
+    
+     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 OutputPluginOptions.output_mode
+     to OUTPUT_PLUGIN_TEXTUAL_OUTPUT instead
+     of OUTPUT_PLUGIN_BINARY_OUTPUT in
+     the startup
+     callback. In that case all the data has to be in the server's encoding
+     so a text can contain it. This is checked in assertion enabled
+     builds.
+    
+   
+
    
     Output Plugin Callbacks
     
@@ -405,7 +423,8 @@ typedef struct OutputPluginOptions
 
       output_type has to either be set to
       OUTPUT_PLUGIN_TEXTUAL_OUTPUT
-      or OUTPUT_PLUGIN_BINARY_OUTPUT.
+      or OUTPUT_PLUGIN_BINARY_OUTPUT. See also
+      .
      
      
       The startup callback should validate the options present in

diff --git a/src/backend/replication/logical/logicalfuncs.c b/src/backend/replication/logical/logicalfuncs.c
index 9692f98b55ef5a39be82bd7f6fdf727673346c7c..3a5ec2f61d931ed1c78cc4f3b7e207867aac01e4 100644 (file)
--- a/src/backend/replication/logical/logicalfuncs.c
+++ b/src/backend/replication/logical/logicalfuncs.c
@@ -401,7 +401,9 @@ pg_logical_slot_get_changes_guts(FunctionCallInfo fcinfo, bool confirm, bool bin
            ctx->options.output_type != OUTPUT_PLUGIN_TEXTUAL_OUTPUT)
            ereport(ERROR,
                    (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;