mirror of
https://github.com/php/php-src.git
synced 2024-11-25 19:05:31 +08:00
236 lines
8.4 KiB
Plaintext
236 lines
8.4 KiB
Plaintext
==== 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.
|
|
|