xref: /PHP-7.2/ext/pgsql/README (revision 60a69dae) 
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