1==== About This Module === 2PostgreSQL module provides access to PostgreSQL server from 3PHP script. This module uses PostgreSQL C client lib called libpq. 4It is important that you use libpq that is later than backend 5(PostgreSQL Server) version. Otherwise, you may experience 6strange problems. 7 8Please send e-mail to yohgaki@php.net if you have comments for 9pgsql module. I appreciate your feedback. 10 11==== API Change === 12Older PHP than 4.2.0, pg_loimport()/pg_loexport() connection 13parameter as last parameter, not like other functions. From 4.2.0, 14connection parameter became 1st parameter. Old syntax is preserved, 15but it will raise NOTICE error message. 16 17pg_connect()/pg_pconnect() has obsolete multi parameter syntax. 18This syntax will be deleted in 4.3.0 or later. 19 20Omitting connectin parameter is NOT recommended. Connection 21parameter may be required for future PHP version. Specify connection 22always if you don't want to rewrite code when it is changed. 23 24==== Function Name Change ==== 25Function names are going to be changed to confirm coding 26standard. MySQL module has been done this already. Function names will 27be changed as follows. 28 29pg_errormessage -> pg_error_message 30pg_cmdtuples -> pg_affected_rows 31pg_fieldnum -> pg_field_num 32and so on. Except pg_cmdtuples, under scores '_' will be added to 33names. 34 35Older names will become aliases of new functions for backward 36compatibility. 37 38Manual will be updated when this change is committed to CVS source. 39 40==== Configure Option Notes ==== 41You cannot specify PostgreSQL source directly to build PostgreSQL 42module with specific version. You need to install PostgreSQL 43somewhere in your system to build PHP with PostgreSQL support. 44 45==== Note For PostgreSQL 7.2 ==== 46I've tested up to 7.2.2. 47 48==== TODO List === 49Make pg_convert() smater. 50 - Better regex 51 - User defiend type support 52Support async connection. 53 54==== Experimental Functions ===== 55 56WARNING: API/behavior may be changed without notice. 57 58Async query can improve application performance 59*significantly*. Please test and report any failure to 60yohgaki@php.net 61 62There are some cases that async functions blocks process. Even if 63process was blocked, functions work as expected. (except it blocks 64process) These are cases that process is blocked. Refer to libpq 65manual for details. Followings are common cases that async functions 66are blocked. 67 68 - If libpq is compile with USE_SSL, some async functions are 69 blocked. 70 - If libpq under Win32 is *NOT* compiled with 71 WIN32_NON_BLOCKING_CONNECTIONS, non-blocking connection will block. 72 73Async function may also block if you have not retrive result and 74send or execute query. If there is result left on connection, 75pg_send_query() will block until last query is completed. 76 77Garbages are cleaned when resource is cleaned up. There is no need to 78clean up query result if it is not needed. 79 80Please refer to libpq manual or source for details. 81These functions are *NOT* supposed to be documented, yet. 82API may be changed. 83 84NOTE: These functions are added in PHP 4.2.0 unless they are mentioned. 85 86------------------------------------------------------------------- 87bool pg_send_query(resource connection, string query) 88 89Sends async query to backend. Result may be retrieved with 90pg_get_result(). It does not accept multiple query, but it accepts 91multiple queries at once. Each result may be retrieved separately by 92pg_get_result(). 93 94-------------------------------------------------------------------- 95bool pg_cancel_query(resource connection) 96 97Cancels currently executing async query already sent to PostgreSQL 98server. This function is useful when user request time consuming query 99to server. It cannot cancel query executed by pg_exec(), since 100pg_exec() is a blocking function. 101 102-------------------------------------------------------------------- 103resource pg_get_result(resource conn) 104 105Gets pgsql query result resource. Returned value can be fed to 106pg_result()/pg_fetch_*(). pg_get_result() may block if result is not 107ready to be retrived. Use pg_is_busy() to check result is ready to be 108retrieved or not. If multiple query is sent to backend, it may be 109retrieved one by one using pg_get_result(). If there is no result left 110in connection, it returns false. 111 112-------------------------------------------------------------------- 113bool pg_connection_busy(resource connection) 114 115Returns connections is executing query or not. 116 117-------------------------------------------------------------------- 118int pg_connection_status(resource connection) 119 120Gets connection status. It returns PGSQL_CONNECTION_OK or 121PGSQL_CONNECTION_BAD. 122 123-------------------------------------------------------------------- 124bool pg_connection_reset(resource connection) 125 126Resets communication port to Postgresql server using the same 127connection parameter. It's useful for error recovery. 128 129-------------------------------------------------------------------- 130string pg_result_error(resource result) 131 132Get error message associated with result 133 134-------------------------------------------------------------------- 135int pg_result_status(resource result) 136 137Get status of query result 138 139-------------------------------------------------------------------- 140 141 142Copy functions 143 144-------------------------------------------------------------------- 145mixed pg_copy_to(int connection_id, string table_name, 146 [, string delim [, string null_as]]) 147 148nt pg_copy_from(int connection_id, string table_name, array rows 149 [, string delim [, string null_as]]) 150 151-------------------------------------------------------------------- 152 153Utility functions 154 155-------------------------------------------------------------------- 156string pg_escape_string(string data) 157Escape string or binary for SQL statemen (7.2 or later) 158 159 160string pg_escape_bytea(string data) 161Escape string or binary for SQL statement (7.2 or later) 162 163-------------------------------------------------------------------- 164 165Large Object Functions 166 167-------------------------------------------------------------------- 168int pg_lo_tell(resource large_object) 169Returns current position of large object 170 171-------------------------------------------------------------------- 172bool pg_lo_lseek(resource large_object, int offset[, int whence]) 173Seeks position of large object 174 175-------------------------------------------------------------------- 176 177Notice message function 178 179-------------------------------------------------------------------- 180 181string pg_last_notice(resource connection) 182Returns the last notice set by the backend 183 184This function is fully implemed in only in current CVS version. 185PHP 4.3.0 supposed to included fully implemented version. 186 187NOTE: Added in PHP 4.0.6, but there is bug in notice message handling 188in PHP 4.0.6. Do no use 4.0.6 with pgsql module!! 189 190-------------------------------------------------------------------- 191 192Utility functions (for PHP 4.3.0) 193 194-------------------------------------------------------------------- 195array pg_metadata(resource db, string table) 196 Get metadata 197 198-------------------------------------------------------------------- 199array pg_convert(resource db, string table, array values) 200 Check and convert values for PostgreSQL SQL statement 201 202-------------------------------------------------------------------- 203bool pg_insert(resource db, string table, array values[, bool convert[, bool async]]) 204 Insert values (filed=>value) to table 205 206-------------------------------------------------------------------- 207bool pg_update(resource db, string table, array fields, array ids[, bool convert[, bool async]]) 208 Update table using values (field=>value) and ids (id=>value) 209 210-------------------------------------------------------------------- 211bool pg_delete(resource db, string table, array ids[, bool convert[, bool async]]) 212 Delete records has ids (id=>value) 213 214-------------------------------------------------------------------- 215array pg_select(resource db, string table, array ids[, bool convert]) 216 Select records that has ids (id=>value) 217 218-------------------------------------------------------------------- 219array pg_get_notify([resource db[, notify]]) 220 Get notify message on the connection 221 222-------------------------------------------------------------------- 223string pg_unescape_bytea(string bytea_data) 224 Unescape bytea field data 225 226-------------------------------------------------------------------- 227bool pg_ping(resource db) 228 ping database connection and try to reset connection if it's 229 broken 230 231------------------------------------------------------------------- 232 233Again, experimental functions are subject to be changed without 234notice. 235
