==== About This Module === PostgreSQL module provides access to PostgreSQL server from PHP script. This module uses PostgreSQL C client lib called libpq. It is important that you use libpq that is later than backend (PostgreSQL Server) version. Otherwise, you may experience strange problems. Please send e-mail to yohgaki@php.net if you have comments for pgsql module. I appreciate your feedback. ==== API Change === Older PHP than 4.2.0, pg_loimport()/pg_loexport() connection parameter as last parameter, not like other functions. From 4.2.0, connection parameter became 1st parameter. Old syntax is preserved, but it will raise NOTICE error message. pg_connect()/pg_pconnect() has obsolete multi parameter syntax. This syntax will be deleted in 4.3.0 or later. Omitting connectin parameter is NOT recommended. Connection parameter may be required for future PHP version. Specify connection always if you don't want to rewrite code when it is changed. ==== Function Name Change ==== Function names are going to be changed to confirm coding standard. MySQL module has been done this already. Function names will be changed as follows. pg_errormessage -> pg_error_message pg_cmdtuples -> pg_affected_rows pg_fieldnum -> pg_field_num and so on. Except pg_cmdtuples, under scores '_' will be added to names. Older names will become aliases of new functions for backward compatibility. Manual will be updated when this change is commited to CVS source. ==== Configure Option Notes ==== You cannot specify PostgreSQL source directly to build PostgreSQL module with specific version. You need to install PostgreSQL somewhere in your system to build PHP with PostgreSQL support. ==== Note For PostgreSQL 7.2 beta ==== Current CVS version (probably 4.0.6 or later) compiles without modefication. ==== TODO List === pg_convert_array() - convert array elements for SQL statement. Support async connection create. ==== Experimental Functions ===== WARNING: API/behavior may be changed without notice. Async query can improve application performance *significantly*. Please test and report any failure to yohgaki@php.net There are some cases that async functions blocks process. Even if process was blocked, functions work as expected. (except it blocks process) These are cases that process is blocked. Refer to libpq manual for details. Followings are common cases that async functions are blocked. - If libpq is compile with USE_SSL, some async functions are blocked. - If libpq under Win32 is *NOT* compiled with WIN32_NON_BLOCKING_CONNECTIONS, non-blocking connection will block. Async function may also block if you have not retrive result and send or execute query. If there is result left on connection, pg_send_query() will block until last query is completed. Garbages are cleaned when resource is cleaned up. There is no need to clean up query result if it is not needed. Please refer to libpq manual or source for details. These functions are *NOT* supposed to be documented, yet. API may be changed. ------------------------------------------------------------------- bool pg_send_query(resource connection, string query) Sends async query to backend. Result may be retrieved with pg_get_result(). It does not accept multiple query, but it accepts multiple queries at once. Each result may be retrieved separately by pg_get_result(). -------------------------------------------------------------------- bool pg_request_cancel(resource connection) Cancels currently executing async query already sent to PostgreSQL server. This function is useful when user request time consuming query to server. It cannot cancel query executed by pg_exec(), since pg_exec() is a blocking function. -------------------------------------------------------------------- resource pg_get_result(resource conn) Gets pgsql query result resource. Returned value can be fed to pg_result()/pg_fetch_*(). pg_get_result() may block if result is not ready to be retrived. Use pg_is_busy() to check result is ready to be retrieved or not. If multiple query is sent to backend, it may be retrieved one by one using pg_get_result(). If there is no result left in connection, it returns false. -------------------------------------------------------------------- bool pg_is_busy(resource connection) Returns connections is executing query or not. -------------------------------------------------------------------- int pg_status(resource connection) Gets connection status. It returns PGSQL_CONNECTION_OK or PGSQL_CONNECTION_BAD. -------------------------------------------------------------------- bool pg_reset(resource connection) Resets communication port to Postgresql server using the same connection parameter. It's useful for error recovery. -------------------------------------------------------------------- Copy functions -------------------------------------------------------------------- mixed pg_copy_to(int connection_id, string table_name, [, string delim [, string null_as]]) nt pg_copy_from(int connection_id, string table_name, array rows [, string delim [, string null_as]]) -------------------------------------------------------------------- Utility functions -------------------------------------------------------------------- string pg_escape_string(string data) Escape string or binary for SQL statemen (7.2 or later) string pg_escape_bytea(string data) Escape string or binary for SQL statement (7.2 or later) -------------------------------------------------------------------- Large Object Functions -------------------------------------------------------------------- int pg_lo_tell(resource large_object) Returns current position of large object -------------------------------------------------------------------- bool pg_lo_lseek(resource large_object, int offset[, int whence]) Seeks position of large object -------------------------------------------------------------------- Notice messge function -------------------------------------------------------------------- string pg_last_notice(resource connection) Returns the last notice set by the backend Currently pg_last_notice() does not return notice message associated with the connection. -------------------------------------------------------------------- Again, experimental functions are subject to be changed without notice.