embedaddon/php/ext/pgsql/README - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / ext / pgsql / README
Revision 1.1: download - view: text, annotated - select for diffs - revision graph
Tue Feb 21 23:47:59 2012 UTC (12 years, 10 months ago) by misho
CVS tags: MAIN, HEAD

Initial revision

==== 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 ==== I've tested upto 7.2.2. ==== TODO List === Make pg_convert() smater. - Better regex - User defiend type support Support async connection. ==== 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. NOTE: These functions are added in PHP 4.2.0 unless they are mentioned. ------------------------------------------------------------------- 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_cancel_query(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_connection_busy(resource connection) Returns connections is executing query or not. -------------------------------------------------------------------- int pg_connection_status(resource connection) Gets connection status. It returns PGSQL_CONNECTION_OK or PGSQL_CONNECTION_BAD. -------------------------------------------------------------------- bool pg_connection_reset(resource connection) Resets communication port to Postgresql server using the same connection parameter. It's useful for error recovery. -------------------------------------------------------------------- string pg_result_error(resource result) Get error message associated with result -------------------------------------------------------------------- int pg_result_status(resource result) Get status of query result -------------------------------------------------------------------- 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 message function -------------------------------------------------------------------- string pg_last_notice(resource connection) Returns the last notice set by the backend This function is fully implemed in only in current CVS version. PHP 4.3.0 supposed to included fully implemented version. NOTE: Added in PHP 4.0.6, but there is bug in notice message handling in PHP 4.0.6. Do no use 4.0.6 with pgsql module!! -------------------------------------------------------------------- Utility functions (for PHP 4.3.0) -------------------------------------------------------------------- array pg_metadata(resource db, string table) Get metadata -------------------------------------------------------------------- array pg_convert(resource db, string table, array values) Check and convert values for PostgreSQL SQL statement -------------------------------------------------------------------- bool pg_insert(resource db, string table, array values[, bool convert[, bool async]]) Insert values (filed=>value) to table -------------------------------------------------------------------- bool pg_update(resource db, string table, array fields, array ids[, bool convert[, bool async]]) Update table using values (field=>value) and ids (id=>value) -------------------------------------------------------------------- bool pg_delete(resource db, string table, array ids[, bool convert[, bool async]]) Delete records has ids (id=>value) -------------------------------------------------------------------- array pg_select(resource db, string table, array ids[, bool convert]) Select records that has ids (id=>value) -------------------------------------------------------------------- array pg_get_notify([resource db[, notify]]) Get notify message on the connection -------------------------------------------------------------------- string pg_unescape_bytea(string bytea_data) Unescape bytea field data -------------------------------------------------------------------- bool pg_ping(resource db) ping database connection and try to reset connection if it's broken ------------------------------------------------------------------- Again, experimental functions are subject to be changed without notice.