README

==== 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 committed 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 up to 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.