Particularly during the application development phase, you’ll want to output various status messages and errors for convenience. Additionally, during the lifetime of the application, you’ll want to log, and perhaps even be immediately notified via e-mail of, any errors that arise.
Several functions are at your disposal for these purposes, introduced in this section.
pg_connection_status()
int pg_connection_status(resource connection)
The pg_connection_status() function returns one of two possible values regarding the data- base connection specified by connection: PGSQL_CONNECTION_OK or PGSQL_CONNECTION_BAD.
An example follows:
$pg = pg_connect("host=localhost user=jason password=secret dbname=corporate");
if (pg_connection_status($pg) == "PG_CONNECTION_BAD") { die("There was a problem connecting to the database.");
}
674 C H A P T E R 3 0 ■ P H P ’ S P O S T G R E S Q L F U N C T I O N A L I T Y
Of course, because pg_connect() will return FALSE on failure, you can also determine connection success like so:
$pg = pg_connect("host=localhost user=jason password=secret dbname=corporate");
if (!$pg) {
die("There was a problem connecting to the database.");
}
Note that if PHP’s error-reporting mechanism is enabled and the information is being output to the screen (see the PHP directives error_reporting and display_errors), other infor- mation will also be output to the screen.
pg_last_notice()
string pg_last_notice(resource connection)
The pg_last_notice() function returns the most recently occurring notice emanating from the connection specified by the connection parameter.
pg_result_status()
pg_result_status(resource result [, int type])
The pg_result_status() function returns information regarding the status of result. The type of information returned depends upon which type value is assigned, of which two are supported:
• PGSQL_STATUS_LONG: Causes pg_result_status() to return the numerical status of the result. This is the default.
• PGSQL_STATUS_STRING: Returns the type of query executed. For instance, if the query was a standard SELECT statement, then the word SELECT is returned.
If PGSQL_STATUS_LONG is assigned to type, one of eight possible values will be returned. Note that a numerical representation of these values is returned, so you need to devise a means for converting the numerical value to the corresponding status response:
• PGSQL_BAD_RESPONSE: The server’s response isn’t understood. The numerical value is 5.
• PGSQL_COMMAND_OK: A query not involving the return of data has executed correctly. The numerical value is 1.
• PGSQL_COPY_IN: The copy of data to the server has commenced. The numerical value is 4.
• PGSQL_COPY_OUT: The copy of data from the server has commenced. The numerical value is 3.
• PGSQL_EMPTY_QUERY: The query sent to the server contains no data. The numerical value is 0.
• PGSQL_FATAL_ERROR: A fatal error has occurred, such as the inability to successfully connect to the database server. The numerical value is 7.
• PGSQL_NONFATAL_ERROR: A nonfatal error (specifically a notice or warning) has occurred, such as an attempt to drop a table that doesn’t exist. The numerical value is 6.
• PGSQL_TUPLES_OK: A query involving the retrieval of data has executed correctly. The numerical value is 2.
For example, the following code determines what type of query is being executed and returns information regarding the response status:
$query = "SELECT productid, name, price FROM product ORDER BY name";
$result = pg_query($query);
echo "Query Type: ".pg_result_status($result, PGSQL_STATUS_STRING)."<br />";
echo "Query Status: ".pg_result_status($result, PGSQL_STATUS_LONG)."<br />";
This returns the following:
Query Type: SELECT Query Status: 2
pg_last_error()
string pg_last_error([resource connection])
The pg_last_error() function returns the most recently occurring error message emanating from the connection specified by the optional connection parameter. If connection isn’t provided, the most recently initiated connection will be used. For instance, an attempt to drop a nonexistent table will produce an error, which is demonstrated below:
$res = pg_query("DROP TABLE nonexistenttable");
echo pg_last_error();
Executing this example produces:
ERROR: table "nonexistenttable" does not exist
pg_result_error()
string pg_result_error(resource result)
The pg_result_error() function returns the error most recently attributed to the resource specified by result. For example:
$query = "SELECT * FROM productt ORDER BY name";
$done = pg_send_query($pg, $query);
$result = pg_get_result($pg);
echo pg_result_error($result);
676 C H A P T E R 3 0 ■ P H P ’ S P O S T G R E S Q L F U N C T I O N A L I T Y
Because the product table has been misspelled in the query, the following error will occur:
ERROR: relation "productt" does not exist
Note that this function differs from the previously introduced pg_last_error() function in that pg_result_error() is specific to the last error attributed to a specific resource, whereas pg_last_error() is specific to the last error occurring during the script’s execution, regardless of resource. Because of this, the pg_send_query() and pg_get_result() functions must be used to retrieve the failed query result. Note that using pg_query() in conjunction with pg_result_error() will produce no information, regardless of whether the query fails!
While pg_result_error() is useful, the pg_result_error_field() function offers a much more detailed summary of the problem. This function is introduced next.
pg_result_error_field()
string pg_result_error_field(resource result, int fieldcode)
Only available when used in conjunction with PostgreSQL 7.4 and later, the
pg_result_error_field() function returns error information pertinent to the resource speci- fied by result. The returned error information is specific to the value defined by fieldcode.
Twelve fieldcode values are supported, including:
• PGSQL_DIAG_CONTEXT: Contains a trace of internally generated information pertinent to the error.
• PGSQL_DIAG_INTERNAL_POSITION: Available as of PostgreSQL version 8.0, contains the cursor position of a failed command that was generated by PostgreSQL rather than by the client.
• PGSQL_DIAG_INTERNAL_QUERY: Available as of PostgreSQL version 8.0, specifies the text of a failed command that was generated by PostgreSQL rather than by the client.
• PGSQL_DIAG_MESSAGE_DETAIL: Occasionally offers additional information regarding why the error occurred, building upon what is stored in PGSQL_DIAG_MESSAGE_PRIMARY.
• PGSQL_DIAG_MESSAGE_HINT: Occasionally offers some explanation of how the user can go about resolving the error.
• PGSQL_DIAG_MESSAGE_PRIMARY: Offers a user-friendly, yet terse, description of the error.
• PGSQL_DIAG_SEVERITY: Specifies the error’s severity, which could be one of the following values: DEBUG, ERROR, FATAL, INFO, LOG, NOTICE, PANIC, or WARNING.
• PGSQL_DIAG_SOURCE_FILE: Specifies the name of the file in which the error occurred.
• PGSQL_DIAG_SOURCE_FUNCTION: Specifies the name of the PostgreSQL function that produced the error.
• PGSQL_DIAG_SOURCE_LINE: Specifies the line number of the file in which the error occurred.
• PGSQL_DIAG_SQLSTATE: Contains the SQLSTATE string. Available as of PostgreSQL version 7.4, SQLSTATE messages consist of five-character strings that represent various database server warnings and errors. See the online PostgreSQL documentation for a complete list of the codes and their corresponding meanings.
• PGSQL_DIAG_STATEMENT_POSITION: Contains the cursor position of the place in which the error occurred within the query statement.
Building on the previous example, it’s possible to report just the name of the file, the error message, and the line in which the error occurred, like so:
<?php
$pg = pg_connect("host=localhost user=webuser password=secret dbname=corporate");
$query = "SELECT * FROM productt ORDER BY name";
pg_send_query($pg, $query);
$result = pg_get_result($pg);
echo "PostgreSQL has returned an error: <br />";
echo "File: ".pg_result_error_field($result, PGSQL_DIAG_SOURCE_FILE)."<br />";
echo "Line: ".pg_result_error_field($result, PGSQL_DIAG_SOURCE_LINE)."<br />";
echo "Message: ".pg_result_error_field($result,
PGSQL_DIAG_MESSAGE_PRIMARY)."<br />";
?>
This returns the following output:
PostgreSQL has returned an error:
File: namespace.c Line: 200
Message: relation "productt" does not exist
pg_set_error_verbosity()
int pg_set_error_verbosity([resource connection,] int verbosity)
Available as of PostgreSQL 7.4, the pg_set_error_verbosity() function determines the amount of information returned by the pg_last_error() and pg_result_error() functions. Three verbosity settings are supported:
678 C H A P T E R 3 0 ■ P H P ’ S P O S T G R E S Q L F U N C T I O N A L I T Y
• PGSQL_ERRORS_DEFAULT: Returns error information including the position, primary text, severity, additional details, context fields, and a hint
• PGSQL_ERRORS_TERSE: Returns error information including the position, primary text, and severity
• PGSQL_ERRORS_VERBOSE: Returns all available error information