From 5ed27e35f35f6c354b1a7120ec3a3ce57f93e73e Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 22 Apr 2003 00:08:07 +0000 Subject: Another round of protocol changes. Backend-to-frontend messages now all have length words. COPY OUT reimplemented per new protocol: it doesn't need \. anymore, thank goodness. COPY BINARY to/from frontend works, at least as far as the backend is concerned --- libpq's PQgetline API is not up to snuff, and will have to be replaced with something that is null-safe. libpq uses message length words for performance improvement (no cycles wasted rescanning long messages), but not yet for error recovery. --- doc/src/sgml/libpq.sgml | 83 ++++++++++++++++++++++++++++------------------ doc/src/sgml/protocol.sgml | 29 ++++++++++++++-- 2 files changed, 76 insertions(+), 36 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 7a7bb48ff39..5ba7e6468c3 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -175,7 +175,8 @@ PGconn *PQconnectdb(const char *conninfo); connect_timeout - Time space in seconds given to connection function. Zero or not set means infinite. + Maximum wait for connection, in seconds (write as a decimal integer + string). Zero or not specified means infinite. @@ -184,7 +185,7 @@ PGconn *PQconnectdb(const char *conninfo); options - Configuration options to be sent to the server. + Command-line options to be sent to the server. @@ -252,8 +253,9 @@ PGconn *PQsetdbLogin(const char *pghost, - This is the predecessor of PQconnectdb with a fixed number - of parameters but the same functionality. + This is the predecessor of PQconnectdb with a fixed + number of parameters. It has the same functionality except that the + missing parameters cannot be specified in the call. @@ -274,8 +276,8 @@ PGconn *PQsetdb(char *pghost, This is a macro that calls PQsetdbLogin with null pointers - for the login and pwd parameters. It is provided primarily - for backward compatibility with old programs. + for the login and pwd parameters. It is provided + for backward compatibility with very old programs. @@ -454,7 +456,7 @@ switch(PQstatus(conn)) - Finally, these functions leave the socket in a nonblocking state as if + Finally, these functions leave the connection in a nonblocking state as if PQsetnonblocking had been called. @@ -486,8 +488,6 @@ typedef struct - converts an escaped string representation of binary data into binary - data --- the reverse of PQescapeBytea. Returns a connection options array. This may be used to determine all possible PQconnectdb options and their current default values. The return value points to an array of @@ -683,7 +683,7 @@ char *PQtty(const PGconn *conn); PQoptions - Returns the configuration options passed in the connection request. + Returns the command-line options passed in the connection request. char *PQoptions(const PGconn *conn); @@ -2047,13 +2047,13 @@ contains example functions that correctly handle the COPY pro PQgetlineAsync - Reads a newline-terminated line of characters + Reads a row of COPY data (transmitted by the server) into a buffer without blocking. int PQgetlineAsync(PGconn *conn, char *buffer, - int length); + int bufsize); @@ -2070,24 +2070,27 @@ end-of-data signal is detected. Unlike PQgetline, this function takes responsibility for detecting end-of-data. -On each call, PQgetlineAsync will return data if a complete newline- -terminated data line is available in libpq's input buffer, or if the -incoming data line is too long to fit in the buffer offered by the caller. -Otherwise, no data is returned until the rest of the line arrives. + + +On each call, PQgetlineAsync will return data if a +complete data row is available in libpq's input buffer. +Otherwise, no data is returned until the rest of the row arrives. The function returns -1 if the end-of-copy-data marker has been recognized, or 0 if no data is available, or a positive number giving the number of bytes of data returned. If -1 is returned, the caller must next call PQendcopy, and then return to normal processing. -The data returned will not extend beyond a newline character. If possible -a whole line will be returned at one time. But if the buffer offered by -the caller is too small to hold a line sent by the server, then a partial -data line will be returned. This can be detected by testing whether the -last returned byte is \n or not. +The data returned will not extend beyond a data-row boundary. If possible +a whole row will be returned at one time. But if the buffer offered by +the caller is too small to hold a row sent by the server, then a partial +data row will be returned. With textual data this can be detected by testing +whether the last returned byte is \n or not. (In a binary +COPY, actual parsing of the COPY data format will be needed to make the +equivalent determination.) The returned string is not null-terminated. (If you want to add a -terminating null, be sure to pass a length one smaller than the room -actually available.) +terminating null, be sure to pass a bufsize one smaller +than the room actually available.) @@ -2105,10 +2108,24 @@ int PQputline(PGconn *conn, -Note the application must explicitly send the two -characters \. on a final line to indicate to -the server that it has finished sending its data. +The COPY datastream sent by a series of calls to +PQputline has the same format as that returned by +PQgetlineAsync, except that applications are not +obliged to send exactly one data row per PQputline +call; it is okay to send a partial line or multiple lines per call. + + + +Before PostgreSQL 7.4, it was necessary for the +application to explicitly send the two characters \. as a +final line to indicate to the server that it had finished sending COPY data. +While this still works, it is deprecated and the special meaning of +\. can be expected to be removed in a future release. +It is sufficient to call PQendcopy after having sent the +actual data. + + @@ -2126,9 +2143,9 @@ int PQputnbytes(PGconn *conn, -This is exactly like PQputline, except that the data buffer need -not be null-terminated since the number of bytes to send is -specified directly. +This is exactly like PQputline, except that the data +buffer need not be null-terminated since the number of bytes to send is +specified directly. Use this procedure when sending binary data. @@ -2147,11 +2164,12 @@ int PQendcopy(PGconn *conn); sent to the server using PQputline or when the last string has been received from the server using PGgetline. It must be issued or the server - may get out of sync with the client. Upon + will get out of sync with the client. Upon return from this function, the server is ready to receive the next SQL command. The return value is 0 on successful completion, - nonzero otherwise. + nonzero otherwise. (Use PQerrorMessage to retrieve + details if the return value is nonzero.) @@ -2187,7 +2205,6 @@ PQexec(conn, "COPY foo FROM STDIN;"); PQputline(conn, "3\thello world\t4.5\n"); PQputline(conn, "4\tgoodbye world\t7.11\n"); ... -PQputline(conn, "\\.\n"); PQendcopy(conn); diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 529baa1f31b..52d2a60c3b2 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1,4 +1,4 @@ - + Frontend/Backend Protocol @@ -3691,7 +3691,8 @@ Terminate (F) This section describes the fields that may appear in ErrorResponse and NoticeResponse messages. Each field type has a single-byte identification -token. +token. Note that any given field type should appear at most once per +message. @@ -3863,7 +3864,29 @@ PasswordMessage now has a type byte. COPY data is now encapsulated into CopyData and CopyDone messages. There -is a well-defined way to recover from errors during COPY. +is a well-defined way to recover from errors during COPY. The special +\. last line is not needed anymore, and is not sent +during COPY OUT. +(It is still recognized as a terminator during COPY IN, but its use is +deprecated and will eventually be removed.) Binary COPY is supported. +The CopyInResponse and CopyOutResponse messages carry a field indicating +whether the COPY operation is text or binary. + + + +The CursorResponse ('P') message is no longer generated by +the backend. + + + +The NotificationResponse ('A') message has an additional string +field, which is presently empty but may someday carry additional data passed +from the NOTIFY event sender. + + + +The EmptyQueryResponse ('I') message used to include an empty +string parameter; this has been removed. -- cgit v1.2.3