/
README
235 lines (165 loc) · 8.41 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
==== 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 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.