Home Explore Blog CI



postgresql

19th chunk of `doc/src/sgml/protocol.sgml`
8d74bfbbc23fb7a6a6b16a0b709b7bfbbdc60db9b73e50d70000000100000fa5
 backend executes a <command>COPY TO STDOUT</command> SQL statement.  The backend
    sends a CopyOutResponse message to the frontend, followed by
    zero or more CopyData messages (always one per row), followed by CopyDone.
    The backend then reverts to the command-processing mode it was
    in before the <command>COPY</command> started, and sends CommandComplete.
    The frontend cannot abort the transfer (except by closing the connection
    or issuing a Cancel request),
    but it can discard unwanted CopyData and CopyDone messages.
   </para>

   <para>
    In the event of a backend-detected error during copy-out mode,
    the backend will issue an ErrorResponse message and revert to normal
    processing.  The frontend should treat receipt of ErrorResponse as
    terminating the copy-out mode.
   </para>

   <para>
    It is possible for NoticeResponse and ParameterStatus messages to be
    interspersed between CopyData messages; frontends must handle these cases,
    and should be prepared for other asynchronous message types as well (see
    <xref linkend="protocol-async"/>).  Otherwise, any message type other than
    CopyData or CopyDone may be treated as terminating copy-out mode.
   </para>

   <para>
    There is another Copy-related mode called copy-both, which allows
    high-speed bulk data transfer to <emphasis>and</emphasis> from the server.
    Copy-both mode is initiated when a backend in walsender mode
    executes a <command>START_REPLICATION</command> statement.  The
    backend sends a CopyBothResponse message to the frontend.  Both
    the backend and the frontend may then send CopyData messages
    until either end sends a CopyDone message. After the client
    sends a CopyDone message, the connection goes from copy-both mode to
    copy-out mode, and the client may not send any more CopyData messages.
    Similarly, when the server sends a CopyDone message, the connection
    goes into copy-in mode, and the server may not send any more CopyData
    messages. After both sides have sent a CopyDone message, the copy mode
    is terminated, and the backend reverts to the command-processing mode.
    In the event of a backend-detected error during copy-both mode,
    the backend will issue an ErrorResponse message, discard frontend messages
    until a Sync message is received, and then issue ReadyForQuery and return
    to normal processing.  The frontend should treat receipt of ErrorResponse
    as terminating the copy in both directions; no CopyDone should be sent
    in this case.  See <xref linkend="protocol-replication"/> for more
    information on the subprotocol transmitted over copy-both mode.
   </para>

   <para>
    The CopyInResponse, CopyOutResponse and CopyBothResponse messages
    include fields that inform the frontend of the number of columns
    per row and the format codes being used for each column.  (As of
    the present implementation, all columns in a given <command>COPY</command>
    operation will use the same format, but the message design does not
    assume this.)
   </para>

  </sect2>

  <sect2 id="protocol-async">
   <title>Asynchronous Operations</title>

   <para>
    There are several cases in which the backend will send messages that
    are not specifically prompted by the frontend's command stream.
    Frontends must be prepared to deal with these messages at any time,
    even when not engaged in a query.
    At minimum, one should check for these cases before beginning to
    read a query response.
   </para>

   <para>
    It is possible for NoticeResponse messages to be generated due to
    outside activity; for example, if the database administrator commands
    a <quote>fast</quote> database shutdown, the backend will send a NoticeResponse
    indicating this fact before closing the connection.  Accordingly,
    frontends should always be prepared to accept and display NoticeResponse
    messages, even when the connection is nominally idle.
   </para>

   <para>

Title: Advanced COPY Operations and Asynchronous Messages
Summary
The COPY protocol supports copy-out, copy-in, and copy-both modes for bulk data transfer, with specific message sequences and error handling rules. Additionally, asynchronous messages such as NoticeResponse and ParameterStatus can be interspersed with CopyData messages, and frontends must be prepared to handle these cases and other asynchronous operations at any time, even when not engaged in a query.