database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-27 12:41:57 +03:00
Code Activity

What I've done:

Browse Source 
1. Rewritten libpq to allow asynchronous clients.

2. Implemented client side of cancel protocol in library,
   and patched psql.c to send a cancel request upon SIGINT.  The
   backend doesn't notice it yet :-(

3. Implemented 'Z' protocol message addition and renaming of
   copy in/out start messages.  These are implemented conditionally,
   ie, the client protocol version is checked; so the code should
   still work with 1.0 clients.

4. Revised protocol and libpq sgml documents (don't have an SGML
   compiler, though, so there may be some markup glitches here).


What remains to be done:

1. Implement addition of atttypmod field to RowDescriptor messages.
   The client-side code is there but ifdef'd out.  I have no idea
   what to change on the backend side.  The field should be sent
   only if protocol >= 2.0, of course.

2. Implement backend response to cancel requests received as OOB
   messages.  (This prolly need not be conditional on protocol
   version; just do it if you get SIGURG.)

3. Update libpq.3.  (I'm hoping this can be generated mechanically
   from libpq.sgml... if not, will do it by hand.)  Is there any
   other doco to fix?

4. Update non-libpq interfaces as necessary.  I patched libpgtcl
   so that it would compile, but haven't tested it.  Dunno what
   needs to be done with the other interfaces.

Have at it!

Tom Lane
This commit is contained in:
Bruce Momjian
1998-05-06 23:51:16 +00:00
parent 2e12331d42
commit edbd51395c
15 changed files with 2664 additions and 2146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

389
doc/src/sgml/libpq.sgml
View File

@ -128,7 +128,7 @@ PGconn *PQsetdb(char *pghost,
<ListItem>
<Para>
<Function>PQconndefaults</Function>
Returns the database name of the connection.
Returns the default connection options.
<ProgramListing>
PQconninfoOption *PQconndefaults(void)
@ -244,7 +244,7 @@ void PQfinish(PGconn *conn)
Reset the communication port with the backend.
This function will close the IPC socket connection
to the backend and attempt to reestablish a new
connection to the same backend.
connection to the same postmaster.
<ProgramListing>
void PQreset(PGconn *conn)
</ProgramListing>
@ -287,11 +287,12 @@ void PQuntrace(PGconn *conn);
<Para>
<Function>PQexec</Function>
Submit a query to <ProductName>Postgres</ProductName>. Returns a PGresult
pointer if the query was successful or a NULL otherwise. If a NULL is returned, PQerrorMessage can
be used to get more information about the error.
pointer or possibly a NULL pointer. If a NULL is returned, it
should be treated like a PGRES_FATAL_ERROR result: use
PQerrorMessage to get more information about the error.
<ProgramListing>
PGresult *PQexec(PGconn *conn,
char *query);
const char *query);
</ProgramListing>
The <Function>PGresult</Function> structure encapsulates the query
result returned by the backend. <Function>libpq</Function> programmers
@ -310,7 +311,7 @@ PGresult *PQexec(PGconn *conn,
Returns the result status of the query. PQresultStatus can return one of the following values:
<ProgramListing>
PGRES_EMPTY_QUERY,
PGRES_COMMAND_OK, /* the query was a command */
PGRES_COMMAND_OK, /* the query was a command returning no data */
PGRES_TUPLES_OK, /* the query successfully returned tuples */
PGRES_COPY_OUT,
PGRES_COPY_IN,
@ -391,7 +392,20 @@ Oid PQftype(PGresult *res,
returned is -1, the field is a variable length
field. Field indices start at 0.
<ProgramListing>
int2 PQfsize(PGresult *res,
short PQfsize(PGresult *res,
int field_index);
</ProgramListing>
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQfmod</Function>
Returns the type-specific modification data of the field
associated with the given field index.
Field indices start at 0.
<ProgramListing>
short PQfmod(PGresult *res,
int field_index);
</ProgramListing>
</Para>
@ -521,7 +535,6 @@ struct _PQprintOpt
<Function>PQprintTuples</Function>
Prints out all the tuples and, optionally, the
attribute names to the specified output stream.
The programs psql and monitor both use PQprintTuples for output.
<ProgramListing>
void PQprintTuples(PGresult* res,
FILE* fout, /* output stream */
@ -566,6 +579,207 @@ void PQclear(PQresult *res);
</Para>
</Sect1>
<Sect1>
<Title>Asynchronous Query Processing</Title>
<Para>
The PQexec function is adequate for submitting queries in simple synchronous
applications. It has a couple of major deficiencies however:
<Para>
<ItemizedList>
<ListItem>
<Para>
PQexec waits for the query to be completed. The application may have other
work to do (such as maintaining a user interface), in which case it won't
want to block waiting for the response.
</Para>
</ListItem>
<ListItem>
<Para>
Since control is buried inside PQexec, there is no way for the frontend
to decide it would like to try to cancel the ongoing query.
</Para>
</ListItem>
<ListItem>
<Para>
PQexec can return only one PGresult structure. If the submitted query
string contains multiple SQL commands, all but the last PGresult are
discarded by PQexec.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
Applications that do not like these limitations can instead use the
underlying functions that PQexec is built from: PQsendQuery and
PQgetResult.
<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQsendQuery</Function>
Submit a query to <ProductName>Postgres</ProductName> without
waiting for the result(s). TRUE is returned if the query was
successfully dispatched, FALSE if not (in which case, use
PQerrorMessage to get more information about the failure).
<ProgramListing>
int PQsendQuery(PGconn *conn,
const char *query);
</ProgramListing>
After successfully calling PQsendQuery, call PQgetResult one or more
times to obtain the query results. PQsendQuery may not be called
again (on the same connection) until PQgetResult has returned NULL,
indicating that the query is done.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQgetResult</Function>
Wait for the next result from a prior PQsendQuery,
and return it. NULL is returned when the query is complete
and there will be no more results.
<ProgramListing>
PGresult *PQgetResult(PGconn *conn);
</ProgramListing>
PQgetResult must be called repeatedly until it returns NULL,
indicating that the query is done. (If called when no query is
active, PQgetResult will just return NULL at once.)
Each non-null result from PQgetResult should be processed using
the same PGresult accessor functions previously described.
Don't forget to free each result object with PQclear when done with it.
Note that PQgetResult will block only if a query is active and the
necessary response data has not yet been read by PQconsumeInput.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
Using PQsendQuery and PQgetResult solves one of PQexec's problems:
if a query string contains multiple SQL commands, the results of those
commands can be obtained individually. (This allows a simple form of
overlapped processing, by the way: the frontend can be handling the
results of one query while the backend is still working on later
queries in the same query string.) However, calling PQgetResult will
still cause the frontend to block until the backend completes the
next SQL command. This can be avoided by proper use of three more
functions:
<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQconsumeInput</Function>
If input is available from the backend, consume it.
<ProgramListing>
void PQconsumeInput(PGconn *conn);
</ProgramListing>
No direct return value is available from PQconsumeInput, but
after calling it, the application may check PQisBusy and/or
PQnotifies to see if their state has changed.
PQconsumeInput may be called even if the application is not
prepared to deal with a result or notification just yet.
It will read available data and save it in a buffer, thereby
causing a select(2) read-ready indication to go away. The
application can thus use PQconsumeInput to clear the select
condition immediately, and then examine the results at leisure.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQisBusy</Function>
Returns TRUE if a query is busy, that is, PQgetResult would block
waiting for input. A FALSE return indicates that PQgetResult can
be called with assurance of not blocking.
<ProgramListing>
int PQisBusy(PGconn *conn);
</ProgramListing>
PQisBusy will not itself attempt to read data from the backend;
therefore PQconsumeInput must be invoked first, or the busy
state will never end.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQsocket</Function>
Obtain the file descriptor number for the backend connection socket.
A valid descriptor will be >= 0; a result of -1 indicates that
no backend connection is currently open.
<ProgramListing>
int PQsocket(PGconn *conn);
</ProgramListing>
PQsocket should be used to obtain the backend socket descriptor
in preparation for executing select(2). This allows an application
to wait for either backend responses or other conditions.
If the result of select(2) indicates that data can be read from
the backend socket, then PQconsumeInput should be called to read the
data; after which, PQisBusy, PQgetResult, and/or PQnotifies can be
used to process the response.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
A typical frontend using these functions will have a main loop that uses
select(2) to wait for all the conditions that it must respond to. One of
the conditions will be input available from the backend, which in select's
terms is readable data on the file descriptor identified by PQsocket.
When the main loop detects input ready, it should call PQconsumeInput
to read the input. It can then call PQisBusy, followed by PQgetResult
if PQisBusy returns FALSE. It can also call PQnotifies to detect NOTIFY
messages (see "Asynchronous Notification", below). An example is given
in the sample programs section.
<Para>
A frontend that uses PQsendQuery/PQgetResult can also attempt to cancel
a query that is still being processed by the backend.
<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQrequestCancel</Function>
Request that <ProductName>Postgres</ProductName> abandon
processing of the current query.
<ProgramListing>
int PQrequestCancel(PGconn *conn);
</ProgramListing>
The return value is TRUE if the cancel request was successfully
dispatched, FALSE if not. (If not, PQerrorMessage tells why not.)
Successful dispatch is no guarantee that the request will have any
effect, however. Regardless of the return value of PQrequestCancel,
the application must continue with the normal result-reading
sequence using PQgetResult. If the cancellation
is effective, the current query will terminate early and return
an error result. If the cancellation fails (say because the
backend was already done processing the query), then there will
be no visible result at all.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
Note that if the current query is part of a transaction, cancellation
will abort the whole transaction.
<Para>
The current implementation of cancel requests uses "out of band" messages.
This feature is supported only on TCP/IP connections. If the backend
communication is being done through a Unix socket, PQrequestCancel will
always fail.
</Sect1>
<Sect1>
<Title>Fast Path</Title>
@ -617,48 +831,60 @@ typedef struct {
<Title>Asynchronous Notification</Title>
<Para>
<ProductName>Postgres</ProductName> supports asynchronous notification via the
LISTEN and NOTIFY commands. A backend registers its
interest in a particular relation with the LISTEN command. All backends listening on a particular relation
will be notified asynchronously when a NOTIFY of that
relation name is executed by another backend. No
additional information is passed from the notifier to
the listener. Thus, typically, any actual data that
needs to be communicated is transferred through the
relation.
<FileName>libpq</FileName> applications are notified whenever a connected
backend has received an asynchronous notification.
However, the communication from the backend to the
frontend is not asynchronous. Notification comes
piggy-backed on other query results. Thus, an application must submit queries, even empty ones, in order to
receive notice of backend notification. In effect, the
<FileName>libpq</FileName> application must poll the backend to see if there
is any pending notification information. After the
execution of a query, a frontend may call PQNotifies to
see if any notification data is available from the
backend.
</Para>
<ProductName>Postgres</ProductName> supports asynchronous notification via the
LISTEN and NOTIFY commands. A backend registers its interest in a particular
notification condition with the LISTEN command. All backends listening on a
particular condition will be notified asynchronously when a NOTIFY of that
condition name is executed by any backend. No additional information is
passed from the notifier to the listener. Thus, typically, any actual data
that needs to be communicated is transferred through a database relation.
Commonly the condition name is the same as the associated relation, but it is
not necessary for there to be any associated relation.
<Para>
<FileName>libpq</FileName> applications submit LISTEN commands as ordinary
SQL queries. Subsequently, arrival of NOTIFY messages can be detected by
calling PQnotifies().
<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQNotifies</Function>
returns the notification from a list of unhandled
notifications from the backend. Returns NULL if
there are no pending notifications from the backend. PQNotifies behaves like the popping of a
stack. Once a notification is returned from PQnotifies, it is considered handled and will be
removed from the list of notifications.
<Function>PQnotifies</Function>
Returns the next notification from a list of unhandled
notification messages received from the backend. Returns NULL if
there are no pending notifications. PQnotifies behaves like the
popping of a stack. Once a notification is returned from
PQnotifies, it is considered handled and will be removed from the
list of notifications.
<ProgramListing>
PGnotify* PQNotifies(PGconn *conn);
PGnotify* PQnotifies(PGconn *conn);
</ProgramListing>
The second sample program gives an example of the use
of asynchronous notification.
After processing a PGnotify object returned by PQnotifies,
be sure to free it with free() to avoid a memory leak.
The second sample program gives an example of the use
of asynchronous notification.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
PQnotifies() does not actually read backend data; it just returns messages
previously absorbed by another <FileName>libpq</FileName> function. In prior
releases of <FileName>libpq</FileName>, the only way to ensure timely receipt
of NOTIFY messages was to constantly submit queries, even empty ones, and then
check PQnotifies() after each PQexec(). While this still works, it is
deprecated as a waste of processing power. A better way to check for NOTIFY
messages when you have no useful queries to make is to call PQconsumeInput(),
then check PQnotifies(). You can use select(2) to wait for backend data to
arrive, thereby using no CPU power unless there is something to do. Note that
this will work OK whether you use PQsendQuery/PQgetResult or plain old PQexec
for queries. You should, however, remember to check PQnotifies() after each
PQgetResult or PQexec to see if any notifications came in during the
processing of the query.
</Para>
</Sect1>
<Sect1>
@ -671,6 +897,11 @@ PGnotify* PQNotifies(PGconn *conn);
advantage of this capability.
</Para>
<Para>
These functions should be executed only after obtaining a PGRES_COPY_OUT
or PGRES_COPY_IN result object from PQexec or PQgetResult.
</Para>
<Para>
<ItemizedList>
<ListItem>
@ -685,7 +916,7 @@ PGnotify* PQNotifies(PGconn *conn);
has been read, and 1 if the buffer is full but the
terminating newline has not yet been read.
Notice that the application must check to see if a
new line consists of the single character ".",
new line consists of the two characters "\.",
which indicates that the backend server has finished sending the results of the copy command.
Therefore, if the application ever expects to
receive lines that are more than length-1 characters long, the application must be sure to check
@ -708,8 +939,8 @@ int PQgetline(PGconn *conn,
<Function>PQputline</Function>
Sends a null-terminated string to the backend
server.
The application must explicitly send the single
character "." to indicate to the backend that it
The application must explicitly send the two
characters "\." on a final line to indicate to the backend that it
has finished sending its data.
<ProgramListing>
void PQputline(PGconn *conn,
@ -736,18 +967,35 @@ void PQputline(PGconn *conn,
int PQendcopy(PGconn *conn);
</ProgramListing>
<ProgramListing>
PQexec(conn, "create table foo (a int4, b text, d float8)");
PQexec(conn, "create table foo (a int4, b char16, d float8)");
PQexec(conn, "copy foo from stdin");
PQputline(conn, "3&lt;TAB&gt;hello world&lt;TAB&gt;4.5\n");
PQputline(conn,"4&lt;TAB&gt;goodbye world&lt;TAB&gt;7.11\n");
...
PQputline(conn,".\n");
PQputline(conn,"\\.\n");
PQendcopy(conn);
</ProgramListing>
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
When using PQgetResult, the application should respond to
a PGRES_COPY_OUT result by executing PQgetline repeatedly,
followed by PQendcopy after the terminator line is seen.
It should then return to the PQgetResult loop until PQgetResult
returns NULL. Similarly a PGRES_COPY_IN result is processed
by a series of PQputline calls followed by PQendcopy, then
return to the PQgetResult loop. This arrangement will ensure that
a copy in or copy out command embedded in a series of SQL commands
will be executed correctly.
Older applications are likely to submit a copy in or copy out
via PQexec and assume that the transaction is done after PQendcopy.
This will work correctly only if the copy in/out is the only
SQL command in the query string.
</Para>
</Sect1>
<Sect1>
@ -833,7 +1081,7 @@ void fe_setauthsvc(char *name,
<Para>
The query buffer is 8192 bytes long, and queries over
that length will be silently truncated.
that length will be rejected.
</Para>
</Sect1>
@ -888,7 +1136,7 @@ void fe_setauthsvc(char *name,
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '&percnt;s' failed.0, dbName);
fprintf(stderr,"Connection to database '&percnt;s' failed.\n", dbName);
fprintf(stderr,"&percnt;s",PQerrorMessage(conn));
exit_nicely(conn);
}
@ -900,7 +1148,7 @@ void fe_setauthsvc(char *name,
res = PQexec(conn,"BEGIN");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"BEGIN command failed0);
fprintf(stderr,"BEGIN command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -911,7 +1159,7 @@ void fe_setauthsvc(char *name,
/* fetch instances from the pg_database, the system catalog of databases*/
res = PQexec(conn,"DECLARE myportal CURSOR FOR select * from pg_database");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"DECLARE CURSOR command failed0);
fprintf(stderr,"DECLARE CURSOR command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -919,7 +1167,7 @@ void fe_setauthsvc(char *name,
res = PQexec(conn,"FETCH ALL in myportal");
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
fprintf(stderr,"FETCH ALL command didn't return tuples properly0);
fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
PQclear(res);
exit_nicely(conn);
}
@ -929,14 +1177,14 @@ void fe_setauthsvc(char *name,
for (i=0; i &lt; nFields; i++) {
printf("&percnt;-15s",PQfname(res,i));
}
printf("0);
printf("\n");
/* next, print out the instances */
for (i=0; i &lt; PQntuples(res); i++) {
for (j=0 ; j &lt; nFields; j++) {
printf("&percnt;-15s", PQgetvalue(res,i,j));
}
printf("0);
printf("\n");
}
PQclear(res);
@ -1018,14 +1266,14 @@ void fe_setauthsvc(char *name,
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '&percnt;s' failed.0, dbName);
fprintf(stderr,"Connection to database '&percnt;s' failed.\n", dbName);
fprintf(stderr,"&percnt;s",PQerrorMessage(conn));
exit_nicely(conn);
}
res = PQexec(conn, "LISTEN TBL2");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"LISTEN command failed0);
fprintf(stderr,"LISTEN command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -1034,20 +1282,19 @@ void fe_setauthsvc(char *name,
PQclear(res);
while (1) {
/* async notification only come back as a result of a query*/
/* we can send empty queries */
res = PQexec(conn, " ");
/* printf("res-&gt;status = &percnt;s0, pgresStatus[PQresultStatus(res)]); */
/* check for asynchronous returns */
notify = PQnotifies(conn);
if (notify) {
/* wait a little bit between checks;
* waiting with select() would be more efficient.
*/
sleep(1);
/* collect any asynchronous backend messages */
PQconsumeInput(conn);
/* check for asynchronous notify messages */
while ((notify = PQnotifies(conn)) != NULL) {
fprintf(stderr,
"ASYNC NOTIFY of '&percnt;s' from backend pid '&percnt;d' received0,
"ASYNC NOTIFY of '&percnt;s' from backend pid '&percnt;d' received\n",
notify-&gt;relname, notify-&gt;be_pid);
free(notify);
break;
}
PQclear(res);
}
/* close the connection to the database and cleanup */
@ -1128,7 +1375,7 @@ void fe_setauthsvc(char *name,
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '&percnt;s' failed.0, dbName);
fprintf(stderr,"Connection to database '&percnt;s' failed.\n", dbName);
fprintf(stderr,"&percnt;s",PQerrorMessage(conn));
exit_nicely(conn);
}
@ -1136,7 +1383,7 @@ void fe_setauthsvc(char *name,
/* start a transaction block */
res = PQexec(conn,"BEGIN");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"BEGIN command failed0);
fprintf(stderr,"BEGIN command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -1147,7 +1394,7 @@ void fe_setauthsvc(char *name,
/* fetch instances from the pg_database, the system catalog of databases*/
res = PQexec(conn,"DECLARE mycursor BINARY CURSOR FOR select * from test1");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"DECLARE CURSOR command failed0);
fprintf(stderr,"DECLARE CURSOR command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -1155,7 +1402,7 @@ void fe_setauthsvc(char *name,
res = PQexec(conn,"FETCH ALL in mycursor");
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
fprintf(stderr,"FETCH ALL command didn't return tuples properly0);
fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
PQclear(res);
exit_nicely(conn);
}
@ -1165,7 +1412,7 @@ void fe_setauthsvc(char *name,
p_fnum = PQfnumber(res,"p");
for (i=0;i&lt;3;i++) {
printf("type[&percnt;d] = &percnt;d, size[&percnt;d] = &percnt;d0,
printf("type[&percnt;d] = &percnt;d, size[&percnt;d] = &percnt;d\n",
i, PQftype(res,i),
i, PQfsize(res,i));
}
@ -1183,12 +1430,12 @@ void fe_setauthsvc(char *name,
pval = (POLYGON*) malloc(plen + VARHDRSZ);
pval-&gt;size = plen;
memmove((char*)&amp;pval-&gt;npts, PQgetvalue(res,i,p_fnum), plen);
printf("tuple &percnt;d: got0, i);
printf(" i = (&percnt;d bytes) &percnt;d,0,
printf("tuple &percnt;d: got\n", i);
printf(" i = (&percnt;d bytes) &percnt;d,\n",
PQgetlength(res,i,i_fnum), *ival);
printf(" d = (&percnt;d bytes) &percnt;f,0,
printf(" d = (&percnt;d bytes) &percnt;f,\n",
PQgetlength(res,i,d_fnum), *dval);
printf(" p = (&percnt;d bytes) &percnt;d points boundbox = (hi=&percnt;f/&percnt;f, lo = &percnt;f,&percnt;f)0,
printf(" p = (&percnt;d bytes) &percnt;d points boundbox = (hi=&percnt;f/&percnt;f, lo = &percnt;f,&percnt;f)\n",
PQgetlength(res,i,d_fnum),
pval-&gt;npts,
pval-&gt;boundbox.xh,

281
doc/src/sgml/protocol.sgml
View File

@ -4,14 +4,15 @@
<FirstName>Phil</FirstName>
<Surname>Thompson</Surname>
</Author>
<Date>1998-02-02</Date>
<Date>1998-05-04</Date>
</DocInfo>
<Title>Frontend/Backend Protocol</Title>
<Para>
<Note>
<Para>
Written by <ULink url="mailto:phil@river-bank.demon.co.uk">Phil Thompson</ULink>
Written by <ULink url="mailto:phil@river-bank.demon.co.uk">Phil Thompson</ULink>.
Updates for protocol 2.0 by <ULink url="mailto:tgl@sss.pgh.pa.us">Tom Lane</ULink>.
</Para>
</Note>
@ -24,7 +25,7 @@ a way as to still allow connections from earlier versions of frontends, but
this document does not cover the protocol used by those earlier versions.
<Para>
This document describes the initial version-numbered protocol, designated v1.0.
This document describes version 2.0 of the protocol.
Higher level features built on this protocol (for example, how <FileName>libpq</FileName> passes
certain environment variables after the connection is established)
are covered elsewhere.
@ -47,7 +48,9 @@ and responds to the frontend accordingly.
<Para>
The frontend then sends any required authentication information. Once the
postmaster validates this it responds to the frontend that it is authenticated
and hands over to a backend.
and hands over the connection to a backend. The backend then sends a message
indicating successful startup (normal case) or failure (for example, an
invalid database name).
<Para>
Subsequent communications are query and result packets exchanged between the
@ -60,7 +63,7 @@ closes the connection without waiting for a response for the backend.
<Para>
Packets are sent as a data stream. The first byte determines what should be
expected in the rest of the packet. The exception is packets send from a
expected in the rest of the packet. The exception is packets sent from a
frontend to the postmaster, which comprise a packet length then the packet
itself. The difference is historical.
@ -70,15 +73,22 @@ itself. The difference is historical.
<Para>
This section describes the message flow. There are four different types of
flows depending on the state of the connection:
authentication, query, function call, and termination.
startup, query, function call, and termination.
There are also special provisions for notification responses and command
cancellation, which can occur at any time after the startup phase.
<Sect2>
<Title>Authentication</Title>
<Title>Startup</Title>
<Para>
The frontend sends a StartupPacket. The postmaster uses this and the contents
of the pg_hba.conf(5) file to determine what authentication method the frontend
must use. The postmaster then responds with one of the following messages:
Startup is divided into an authentication phase and a backend startup phase.
<Para>
Initially, the frontend sends a StartupPacket. The postmaster uses this info
and the contents of the pg_hba.conf(5) file to determine what authentication
method the frontend must use. The postmaster then responds with one of the
following messages:
<Para>
<VariableList>
@ -162,13 +172,65 @@ must use. The postmaster then responds with one of the following messages:
If the frontend does not support the authentication method requested by the
postmaster, then it should immediately close the connection.
<Para>
After sending AuthenticationOk, the postmaster attempts to launch a backend
process. Since this might fail, or the backend might encounter a failure
during startup, the frontend must wait for the backend to acknowledge
successful startup. The frontend should send no messages at this point.
The possible messages from the backend during this phase are:
<Para>
<VariableList>
<VarListEntry>
<Term>
ReadyForQuery
</Term>
<ListItem>
<Para>
Backend startup is successful. The frontend may now issue
query or function call messages.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
ErrorResponse
</Term>
<ListItem>
<Para>
Backend startup failed. The connection is closed after
sending this message.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
NoticeResponse
</Term>
<ListItem>
<Para>
A warning message has been issued. The frontend should
display the message but continue listening for ReadyForQuery
or ErrorResponse.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
<Sect2>
<Title>Query</Title>
<Para>
The frontend sends a Query message to the backend. The response sent by the
backend depends on the contents of the query. The possible responses are as
follows.
A Query cycle is initiated by the frontend sending a Query message to the
backend. The backend then sends one or more response messages depending
on the contents of the query command string, and finally a ReadyForQuery
response message. ReadyForQuery informs the frontend that it may safely
send a new query or function call.
<Para>
The possible response messages from the backend are:
<Para>
<VariableList>
@ -178,7 +240,7 @@ follows.
</Term>
<ListItem>
<Para>
The query completed normally.
An SQL command completed normally.
</Para>
</ListItem>
</VarListEntry>
@ -240,7 +302,7 @@ follows.
<Para>
For a fetch(l) or select(l) command, the backend sends a
RowDescription message. This is then followed by an AsciiRow
or BinaryRow message (depending on if a binary cursor was
or BinaryRow message (depending on whether a binary cursor was
specified) for each row being returned to the frontend.
Finally, the backend sends a CompletedResponse message with a
tag of "SELECT".
@ -253,7 +315,8 @@ follows.
</Term>
<ListItem>
<Para>
The query was empty.
An empty query string was recognized. (The need to specially
distinguish this case is historical.)
</Para>
</ListItem>
</VarListEntry>
@ -268,6 +331,21 @@ follows.
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
ReadyForQuery
</Term>
<ListItem>
<Para>
Processing of the query string is complete. A separate
message is sent to indicate this because the query string
may contain multiple SQL commands. (CompletedResponse marks
the end of processing one SQL command, not the whole string.)
ReadyForQuery will always be sent, whether processing
terminates successfully or with an error.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
NoticeResponse
</Term>
@ -275,20 +353,7 @@ follows.
<Para>
A warning message has been issued in relation to the query.
Notices are in addition to other responses, ie. the backend
will send another response message immediately afterwards.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
NotificationResponse
</Term>
<ListItem>
<Para>
A notify(l) command has been executed for a relation for
which a previous listen(l) command was executed. Notifications
are in addition to other responses, ie. the backend will send
another response message immediately afterwards.
will continue processing the command.
</Para>
</ListItem>
</VarListEntry>
@ -297,15 +362,23 @@ follows.
<Para>
A frontend must be prepared to accept ErrorResponse and NoticeResponse
messages whenever it is expecting any other type of message.
messages whenever it is expecting any other type of message. Also,
if it issues any listen(l) commands then it must be prepared to accept
NotificationResponse messages at any time; see below.
<Sect2>
<Title>Function Call</Title>
<Para>
The frontend sends a FunctionCall message to the backend. The response sent by
the backend depends on the result of the function call. The possible responses
are as follows.
A Function Call cycle is initiated by the frontend sending a FunctionCall
message to the backend. The backend then sends one or more response messages
depending on the results of the function call, and finally a ReadyForQuery
response message. ReadyForQuery informs the frontend that it may safely send
a new query or function call.
<Para>
The possible response messages from the backend are:
<Para>
<VariableList>
@ -340,15 +413,27 @@ are as follows.
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
ReadyForQuery
</Term>
<ListItem>
<Para>
Processing of the function call is complete.
ReadyForQuery will always be sent, whether processing
terminates successfully or with an error.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
NoticeResponse
</Term>
<ListItem>
<Para>
A warning message has been issued in relation to the function
call. Notices are in addition to other responses, ie. the
backend will send another response message immediately
afterwards.
call.
Notices are in addition to other responses, ie. the backend
will continue processing the command.
</Para>
</ListItem>
</VarListEntry>
@ -357,7 +442,58 @@ are as follows.
<Para>
A frontend must be prepared to accept ErrorResponse and NoticeResponse
messages whenever it is expecting any other type of message.
messages whenever it is expecting any other type of message. Also,
if it issues any listen(l) commands then it must be prepared to accept
NotificationResponse messages at any time; see below.
<Sect2>
<Title>Notification Responses</Title>
<Para>
If a frontend issues a listen(l) command, then the backend will send a
NotificationResponse message (not to be confused with NoticeResponse!)
whenever a notify(l) command is executed for the same relation name.
<Para>
Notification responses are permitted at any point in the protocol (after
startup), except within another backend message. Thus, the frontend
must be prepared to recognize a NotificationResponse message whenever it is
expecting any message. Indeed, it should be able to handle
NotificationResponse messages even when it is not engaged in a query.
<Para>
<VariableList>
<VarListEntry>
<Term>
NotificationResponse
</Term>
<ListItem>
<Para>
A notify(l) command has been executed for a relation for
which a previous listen(l) command was executed. Notifications
may be sent at any time.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
<Sect2>
<Title>Cancelling Requests in Progress</Title>
<Para>
During the processing of a query, the frontend may request cancellation of the
query by sending a single byte of OOB (out-of-band) data. The contents of the
data byte should be zero (although the backend does not currently check this).
If the cancellation is effective, it results in the current command being
terminated with an error message. Note that the backend makes no specific
reply to the cancel request itself. If the cancel request is ineffective
(say, because it arrived after processing was complete) then it will have
no visible effect at all. Thus, the frontend must continue with its normal
processing of query cycle responses after issuing a cancel request.
<Sect2>
<Title>Termination</Title>
@ -409,7 +545,7 @@ This section describes the base data types used in messages.
<Para>
A conventional C '\0' terminated string with no length
limitation. A frontend should always read the full string
even though it may have to discard characters if it's buffers
even though it may have to discard characters if its buffers
aren't big enough.
<Note>
<Para>
@ -458,8 +594,9 @@ AsciiRow (B)
</Term>
<ListItem>
<Para>
Identifies the message, in the context in which it is sent (see
CopyInResponse), as an <Acronym>ASCII</Acronym> row.
Identifies the message as an <Acronym>ASCII</Acronym> data row.
(A prior RowDescription message defines the number of
fields in the row and their data types.)
</Para>
</ListItem>
</VarListEntry>
@ -704,8 +841,9 @@ BinaryRow (B)
</Term>
<ListItem>
<Para>
Identifies the message, in the context in which it is sent (see
CopyOutResponse), as a binary row.
Identifies the message as a binary data row.
(A prior RowDescription message defines the number of
fields in the row and their data types.)
</Para>
</ListItem>
</VarListEntry>
@ -814,12 +952,12 @@ CopyInResponse (B)
<VariableList>
<VarListEntry>
<Term>
Byte1('D')
Byte1('G')
</Term>
<ListItem>
<Para>
Identifies the message, in the context in which it is sent (see
AsciiRow), as a copy in started response.
Identifies the message as a Start Copy In response.
The frontend must now send a CopyDataRows message.
</Para>
</ListItem>
</VarListEntry>
@ -839,12 +977,12 @@ CopyOutResponse (B)
<VariableList>
<VarListEntry>
<Term>
Byte1('B')
Byte1('H')
</Term>
<ListItem>
<Para>
Identifies the message, in the context in which it is sent (see
BinaryRow), as a copy out started response.
Identifies the message as a Start Copy Out response.
This message will be followed by a CopyDataRows message.
</Para>
</ListItem>
</VarListEntry>
@ -903,7 +1041,7 @@ EmptyQueryResponse (B)
</Term>
<ListItem>
<Para>
Identifies the message as an empty query response.
Identifies the message as a response to an empty query string.
</Para>
</ListItem>
</VarListEntry>
@ -954,6 +1092,31 @@ EncryptedPasswordPacket (F)
</VariableList>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
ReadyForQuery (B)
</Term>
<ListItem>
<Para>
<VariableList>
<VarListEntry>
<Term>
Byte1('Z')
</Term>
<ListItem>
<Para>
Identifies the message type. ReadyForQuery is sent
whenever the backend is ready for a new query cycle.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</ListItem>
</VarListEntry>
@ -1099,7 +1262,7 @@ FunctionResultResponse (B)
</Term>
<ListItem>
<Para>
Specifies that an actual result was returned.
Specifies that a nonempty result was returned.
</Para>
</ListItem>
</VarListEntry>
@ -1167,7 +1330,7 @@ FunctionVoidResponse (B)
</Term>
<ListItem>
<Para>
Specifies that no actual result was returned.
Specifies that an empty result was returned.
</Para>
</ListItem>
</VarListEntry>
@ -1269,7 +1432,7 @@ Query (F)
</Term>
<ListItem>
<Para>
Identifies the message as query.
Identifies the message as a query.
</Para>
</ListItem>
</VarListEntry>
@ -1279,7 +1442,7 @@ Query (F)
</Term>
<ListItem>
<Para>
The query itself.
The query string itself.
</Para>
</ListItem>
</VarListEntry>
@ -1348,6 +1511,16 @@ RowDescription (B)
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
Int16
</Term>
<ListItem>
<Para>
Specifies the type modifier.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>