Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit5ed27e3

Browse files
committed
Another round of protocol changes. Backend-to-frontend messages now all
have length words. COPY OUT reimplemented per new protocol: it doesn'tneed \. anymore, thank goodness. COPY BINARY to/from frontend works,at least as far as the backend is concerned --- libpq's PQgetline APIis not up to snuff, and will have to be replaced with something that isnull-safe. libpq uses message length words for performance improvement(no cycles wasted rescanning long messages), but not yet for errorrecovery.
1 parentca944bd commit5ed27e3

File tree

22 files changed

+778
-353
lines changed

22 files changed

+778
-353
lines changed

‎doc/src/sgml/libpq.sgml

Lines changed: 50 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.119 2003/04/19 00:02:29 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.120 2003/04/22 00:08:06 tgl Exp $
33
-->
44

55
<chapter id="libpq">
@@ -175,7 +175,8 @@ PGconn *PQconnectdb(const char *conninfo);
175175
<term><literal>connect_timeout</literal></term>
176176
<listitem>
177177
<para>
178-
Time space in seconds given to connection function. Zero or not set means infinite.
178+
Maximum wait for connection, in seconds (write as a decimal integer
179+
string). Zero or not specified means infinite.
179180
</para>
180181
</listitem>
181182
</varlistentry>
@@ -184,7 +185,7 @@ PGconn *PQconnectdb(const char *conninfo);
184185
<term><literal>options</literal></term>
185186
<listitem>
186187
<para>
187-
Configuration options to be sent to the server.
188+
Command-line options to be sent to the server.
188189
</para>
189190
</listitem>
190191
</varlistentry>
@@ -252,8 +253,9 @@ PGconn *PQsetdbLogin(const char *pghost,
252253
</para>
253254

254255
<para>
255-
This is the predecessor of <function>PQconnectdb</function> with a fixed number
256-
of parameters but the same functionality.
256+
This is the predecessor of <function>PQconnectdb</function> with a fixed
257+
number of parameters. It has the same functionality except that the
258+
missing parameters cannot be specified in the call.
257259
</para>
258260
</listitem>
259261
</varlistentry>
@@ -274,8 +276,8 @@ PGconn *PQsetdb(char *pghost,
274276

275277
<para>
276278
This is a macro that calls <function>PQsetdbLogin</function> with null pointers
277-
for the <parameter>login</> and <parameter>pwd</> parameters. It is provided primarily
278-
for backward compatibility with old programs.
279+
for the <parameter>login</> and <parameter>pwd</> parameters. It is provided
280+
for backward compatibility withveryold programs.
279281
</para>
280282
</listitem>
281283
</varlistentry>
@@ -454,7 +456,7 @@ switch(PQstatus(conn))
454456
</para>
455457

456458
<para>
457-
Finally, these functions leave thesocket in a nonblocking state as if
459+
Finally, these functions leave theconnection in a nonblocking state as if
458460
<function>PQsetnonblocking</function> had been called.
459461
</para>
460462
</listitem>
@@ -486,8 +488,6 @@ typedef struct
486488
</para>
487489

488490
<para>
489-
converts an escaped string representation of binary data into binary
490-
data --- the reverse of <function>PQescapeBytea</function>.
491491
Returns a connection options array. This may
492492
be used to determine all possible <function>PQconnectdb</function> options and their
493493
current default values. The return value points to an array of
@@ -683,7 +683,7 @@ char *PQtty(const PGconn *conn);
683683
<term><function>PQoptions</function></term>
684684
<listitem>
685685
<para>
686-
Returns theconfiguration options passed in the connection request.
686+
Returns thecommand-line options passed in the connection request.
687687
<synopsis>
688688
char *PQoptions(const PGconn *conn);
689689
</synopsis>
@@ -2047,13 +2047,13 @@ contains example functions that correctly handle the <command>COPY</command> pro
20472047
<term><function>PQgetlineAsync</function></term>
20482048
<listitem>
20492049
<para>
2050-
Reads a newline-terminated lineof characters
2050+
Readsa rowofCOPY data
20512051
(transmitted by the server) into a buffer
20522052
without blocking.
20532053
<synopsis>
20542054
int PQgetlineAsync(PGconn *conn,
20552055
char *buffer,
2056-
intlength);
2056+
intbufsize);
20572057
</synopsis>
20582058
</para>
20592059

@@ -2070,24 +2070,27 @@ end-of-data signal is detected.
20702070
<para>
20712071
Unlike <function>PQgetline</function>, this function takes
20722072
responsibility for detecting end-of-data.
2073-
On each call, <function>PQgetlineAsync</function> will return data if a complete newline-
2074-
terminated data line is available in <application>libpq</>'s input buffer, or if the
2075-
incoming data line is too long to fit in the buffer offered by the caller.
2076-
Otherwise, no data is returned until the rest of the line arrives.
2073+
</para>
2074+
<para>
2075+
On each call, <function>PQgetlineAsync</function> will return data if a
2076+
complete data row is available in <application>libpq</>'s input buffer.
2077+
Otherwise, no data is returned until the rest of the row arrives.
20772078
The function returns -1 if the end-of-copy-data marker has been recognized,
20782079
or 0 if no data is available, or a positive number giving the number of
20792080
bytes of data returned. If -1 is returned, the caller must next call
20802081
<function>PQendcopy</function>, and then return to normal processing.
20812082
</para>
20822083
<para>
2083-
The data returned will not extend beyond a newline character. If possible
2084-
a whole line will be returned at one time. But if the buffer offered by
2085-
the caller is too small to hold a line sent by the server, then a partial
2086-
data line will be returned. This can be detected by testing whether the
2087-
last returned byte is <literal>\n</literal> or not.
2084+
The data returned will not extend beyond a data-row boundary. If possible
2085+
a whole row will be returned at one time. But if the buffer offered by
2086+
the caller is too small to hold a row sent by the server, then a partial
2087+
data row will be returned. With textual data this can be detected by testing
2088+
whether the last returned byte is <literal>\n</literal> or not. (In a binary
2089+
COPY, actual parsing of the COPY data format will be needed to make the
2090+
equivalent determination.)
20882091
The returned string is not null-terminated. (If you want to add a
2089-
terminating null, be sure to pass a <parameter>length</parameter> one smaller than the room
2090-
actually available.)
2092+
terminating null, be sure to pass a <parameter>bufsize</parameter> one smaller
2093+
than the roomactually available.)
20912094
</para>
20922095
</listitem>
20932096
</varlistentry>
@@ -2105,10 +2108,24 @@ int PQputline(PGconn *conn,
21052108
</para>
21062109

21072110
<para>
2108-
Note the application must explicitly send the two
2109-
characters <literal>\.</literal> on a final line to indicate to
2110-
the server that it has finished sending its data.
2111+
The COPY datastream sent by a series of calls to
2112+
<function>PQputline</function> has the same format as that returned by
2113+
<function>PQgetlineAsync</function>, except that applications are not
2114+
obliged to send exactly one data row per <function>PQputline</function>
2115+
call; it is okay to send a partial line or multiple lines per call.
21112116
</para>
2117+
2118+
<note>
2119+
<para>
2120+
Before <productname>PostgreSQL</productname> 7.4, it was necessary for the
2121+
application to explicitly send the two characters <literal>\.</literal> as a
2122+
final line to indicate to the server that it had finished sending COPY data.
2123+
While this still works, it is deprecated and the special meaning of
2124+
<literal>\.</literal> can be expected to be removed in a future release.
2125+
It is sufficient to call <function>PQendcopy</function> after having sent the
2126+
actual data.
2127+
</para>
2128+
</note>
21122129
</listitem>
21132130
</varlistentry>
21142131

@@ -2126,9 +2143,9 @@ int PQputnbytes(PGconn *conn,
21262143
</para>
21272144

21282145
<para>
2129-
This is exactly like <function>PQputline</function>, except that the data buffer need
2130-
not be null-terminated since the number of bytes to send is
2131-
specified directly.
2146+
This is exactly like <function>PQputline</function>, except that the data
2147+
buffer neednot be null-terminated since the number of bytes to send is
2148+
specified directly. Use this procedure when sending binary data.
21322149
</para>
21332150
</listitem>
21342151
</varlistentry>
@@ -2147,11 +2164,12 @@ int PQendcopy(PGconn *conn);
21472164
sent to the server using <function>PQputline</function> or when the
21482165
last string has been received from the server
21492166
using <function>PGgetline</function>. It must be issued or the server
2150-
may get <quote>out of sync</quote> with the client. Upon
2167+
will get <quote>out of sync</quote> with the client. Upon
21512168
return from this function, the server is ready to
21522169
receive the next SQL command.
21532170
The return value is 0 on successful completion,
2154-
nonzero otherwise.
2171+
nonzero otherwise. (Use <function>PQerrorMessage</function> to retrieve
2172+
details if the return value is nonzero.)
21552173
</para>
21562174

21572175
<para>
@@ -2187,7 +2205,6 @@ PQexec(conn, "COPY foo FROM STDIN;");
21872205
PQputline(conn, "3\thello world\t4.5\n");
21882206
PQputline(conn, "4\tgoodbye world\t7.11\n");
21892207
...
2190-
PQputline(conn, "\\.\n");
21912208
PQendcopy(conn);
21922209
</programlisting>
21932210
</para>

‎doc/src/sgml/protocol.sgml

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.28 2003/04/19 00:02:29 tgl Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.29 2003/04/22 00:08:06 tgl Exp $ -->
22

33
<chapter id="protocol">
44
<title>Frontend/Backend Protocol</title>
@@ -3691,7 +3691,8 @@ Terminate (F)
36913691
<para>
36923692
This section describes the fields that may appear in ErrorResponse and
36933693
NoticeResponse messages. Each field type has a single-byte identification
3694-
token.
3694+
token. Note that any given field type should appear at most once per
3695+
message.
36953696
</para>
36963697

36973698
<VariableList>
@@ -3863,7 +3864,29 @@ PasswordMessage now has a type byte.
38633864

38643865
<para>
38653866
COPY data is now encapsulated into CopyData and CopyDone messages. There
3866-
is a well-defined way to recover from errors during COPY.
3867+
is a well-defined way to recover from errors during COPY. The special
3868+
<quote><literal>\.</></quote> last line is not needed anymore, and is not sent
3869+
during COPY OUT.
3870+
(It is still recognized as a terminator during COPY IN, but its use is
3871+
deprecated and will eventually be removed.) Binary COPY is supported.
3872+
The CopyInResponse and CopyOutResponse messages carry a field indicating
3873+
whether the COPY operation is text or binary.
3874+
</para>
3875+
3876+
<para>
3877+
The CursorResponse ('<literal>P</>') message is no longer generated by
3878+
the backend.
3879+
</para>
3880+
3881+
<para>
3882+
The NotificationResponse ('<literal>A</>') message has an additional string
3883+
field, which is presently empty but may someday carry additional data passed
3884+
from the NOTIFY event sender.
3885+
</para>
3886+
3887+
<para>
3888+
The EmptyQueryResponse ('<literal>I</>') message used to include an empty
3889+
string parameter; this has been removed.
38673890
</para>
38683891

38693892
<note>

‎src/backend/access/common/printtup.c

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
* Portions Copyright (c) 1994, Regents of the University of California
1010
*
1111
* IDENTIFICATION
12-
* $Header: /cvsroot/pgsql/src/backend/access/common/printtup.c,v 1.65 2002/09/04 20:31:08 momjian Exp $
12+
* $Header: /cvsroot/pgsql/src/backend/access/common/printtup.c,v 1.66 2003/04/22 00:08:06 tgl Exp $
1313
*
1414
*-------------------------------------------------------------------------
1515
*/
@@ -77,15 +77,18 @@ static void
7777
printtup_setup(DestReceiver*self,intoperation,
7878
constchar*portalName,TupleDesctypeinfo)
7979
{
80-
/*
81-
* Send portal name to frontend.
82-
*
83-
* If portal name not specified, use "blank" portal.
84-
*/
85-
if (portalName==NULL)
86-
portalName="blank";
87-
88-
pq_puttextmessage('P',portalName);
80+
if (PG_PROTOCOL_MAJOR(FrontendProtocol)<3)
81+
{
82+
/*
83+
* Send portal name to frontend (obsolete cruft, gone in proto 3.0)
84+
*
85+
* If portal name not specified, use "blank" portal.
86+
*/
87+
if (portalName==NULL)
88+
portalName="blank";
89+
90+
pq_puttextmessage('P',portalName);
91+
}
8992

9093
/*
9194
* if this is a retrieve, then we send back the tuple descriptor of
@@ -98,8 +101,7 @@ printtup_setup(DestReceiver *self, int operation,
98101
inti;
99102
StringInfoDatabuf;
100103

101-
pq_beginmessage(&buf);
102-
pq_sendbyte(&buf,'T');/* tuple descriptor message type */
104+
pq_beginmessage(&buf,'T');/* tuple descriptor message type */
103105
pq_sendint(&buf,natts,2);/* # of attrs in tuples */
104106

105107
for (i=0;i<natts;++i)
@@ -174,8 +176,7 @@ printtup(HeapTuple tuple, TupleDesc typeinfo, DestReceiver *self)
174176
/*
175177
* tell the frontend to expect new tuple data (in ASCII style)
176178
*/
177-
pq_beginmessage(&buf);
178-
pq_sendbyte(&buf,'D');
179+
pq_beginmessage(&buf,'D');
179180

180181
/*
181182
* send a bitmap of which attributes are not null
@@ -388,8 +389,7 @@ printtup_internal(HeapTuple tuple, TupleDesc typeinfo, DestReceiver *self)
388389
/*
389390
* tell the frontend to expect new tuple data (in binary style)
390391
*/
391-
pq_beginmessage(&buf);
392-
pq_sendbyte(&buf,'B');
392+
pq_beginmessage(&buf,'B');
393393

394394
/*
395395
* send a bitmap of which attributes are not null

‎src/backend/commands/async.c

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
* Portions Copyright (c) 1994, Regents of the University of California
88
*
99
* IDENTIFICATION
10-
* $Header: /cvsroot/pgsql/src/backend/commands/async.c,v 1.92 2003/02/18 02:53:29 tgl Exp $
10+
* $Header: /cvsroot/pgsql/src/backend/commands/async.c,v 1.93 2003/04/22 00:08:06 tgl Exp $
1111
*
1212
*-------------------------------------------------------------------------
1313
*/
@@ -847,10 +847,14 @@ NotifyMyFrontEnd(char *relname, int32 listenerPID)
847847
{
848848
StringInfoDatabuf;
849849

850-
pq_beginmessage(&buf);
851-
pq_sendbyte(&buf,'A');
850+
pq_beginmessage(&buf,'A');
852851
pq_sendint(&buf,listenerPID,sizeof(int32));
853852
pq_sendstring(&buf,relname);
853+
if (PG_PROTOCOL_MAJOR(FrontendProtocol) >=3)
854+
{
855+
/* XXX Add parameter string here later */
856+
pq_sendstring(&buf,"");
857+
}
854858
pq_endmessage(&buf);
855859

856860
/*

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp