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