Updated on 2025-03-13 GMT+08:00

PQresultStatus

Description

Returns the result status of a command.

Prototype

ExecStatusType PQresultStatus(const PGresult* res);

Parameter

Table 1 PQresultStatus parameter

Keyword

Description

res

Object pointer that contains the query result.

Return Values

PQresultStatus indicates the command execution status. The enumerated values are as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
PQresultStatus can return one of the following values:
PGRES_EMPTY_QUERY
The string sent to the server was empty.

PGRES_COMMAND_OK
A command that does not return data was successfully executed.

PGRES_TUPLES_OK
A query (such as SELECT or SHOW) that returns data was successfully executed.

PGRES_COPY_OUT
The data copied from the server begins to transmit.

PGRES_COPY_IN
The data copied to the server begins to transmit.

PGRES_BAD_RESPONSE
The response from the server cannot be understood.

PGRES_NONFATAL_ERROR
A non-fatal error (notification or warning) occurred.

PGRES_FATAL_ERROR
A fatal error occurred.

PGRES_COPY_BOTH
The data copied to and from the server begins to transmit. This state occurs only in streaming replication.

PGRES_SINGLE_TUPLE
PGresult contains a result tuple from the current command. This state occurs in a single-row query.

Precautions

  • Note that the SELECT command that happens to retrieve zero rows still returns PGRES_TUPLES_OK. PGRES_COMMAND_OK is used for commands that can never return rows (such as INSERT or UPDATE, without return clauses). The result status PGRES_EMPTY_QUERY might indicate a bug in the client software.
  • The result status PGRES_NONFATAL_ERROR will never be returned directly by PQexec or other query execution functions. Instead, such results will be passed to the notice processor.

Examples

For details, see Typical Application Development Examples.