LXVII. PostgreSQL functions
Postgres, developed originally in the UC Berkeley Computer Science Department, pioneered many of the object-relational
concepts now becoming available in some commercial databases. It provides SQL92/SQL3 language support, transaction
integrity, and type extensibility. PostgreSQL is an open source descendant of this original Berkeley code.
PostgreSQL is available without cost. The current version is available at www.PostgreSQL.org
(http://www.postgresql.org/).
Since version 6.3 (03/02/1998) PostgreSQL uses unix domain sockets. A table is shown below describing these new
connection possibilities. This socket will be found in /tmp/.s.PGSQL.5432. This option can be enabled with the ’-i’ flag
to postmaster and it’s meaning is: "listen on TCP/IP sockets as well as Unix domain sockets".
Table 1. Postmaster and PHP
Postmaster
PHP
postmaster &
postmaster -i &
postmaster &
Status
pg_connect("dbname=MyDbName");
OK
pg_connect("dbname=MyDbName");
OK
pg_connect("host=localhost
dbname=MyDbName");
Unable to connect to PostgreSQL
server: connectDB() failed: Is the
postmaster running and accepting
TCP/IP (with -i) connection at
’localhost’ on port ’5432’? in
/path/to/file.php3 on line 20.
postmaster -i &
pg_connect("host=localhost
dbname=MyDbName");
OK
One can establish a connection with the following value pairs set in the command string: $conn =
pg_Connect("host=myHost port=myPort tty=myTTY options=myOptions dbname=myDB user=myUser
password=myPassword ");
The previous syntax of: $conn = pg_connect ("host", "port", "options", "tty", "dbname") has been deprecated.
To use the large object (lo) interface, it is necessary to enclose it within a transaction block. A transaction block starts with
a begin and if the transaction was valid ends with commit or end. If the transaction fails the transaction should be closed
with rollback or abort.
Example 1. Using Large Objects
<?php
$database = pg_Connect ("dbname=jacarta");
pg_exec ($database, "begin");
$oid = pg_locreate ($database);
echo ("$oid\n");
$handle = pg_loopen ($database, $oid, "w");
echo ("$handle\n");
pg_lowrite ($handle, "gaga");
pg_loclose ($handle);
pg_exec ($database, "commit");
?>
846
PostgreSQL
pg_close (PHP 3, PHP 4 >= 4.0b1)
Close a PostgreSQL connection
bool pg_close (int connection)
Returns FALSE if connection is not a valid connection index, TRUE otherwise. Closes down the connection to a
PostgreSQL database associated with the given connection index.
Note: This isn’t usually necessary, as non-persistent open links are automatically closed at the end of the script’s
execution.
pg_close() will not close persistent links generated by pg_pconnect().
pg_cmdtuples (PHP 3, PHP 4 >= 4.0b1)
Returns number of affected tuples
int pg_cmdtuples (int result_id)
pg_cmdtuples() returns the number of tuples (instances) affected by INSERT, UPDATE, and DELETE queries. If no tuple
is affected the function will return 0.
Example 1. pg_cmdtuples()
<?php
$result = pg_exec ($conn, "INSERT INTO publisher VALUES (’Author’)");
$cmdtuples = pg_cmdtuples ($result);
echo $cmdtuples . " <- cmdtuples affected.";
?>
See also pg_numfields() and pg_numrows().
pg_connect (PHP 3, PHP 4 >= 4.0b1)
Open a PostgreSQL connection
int
int
int
int
pg_connect
pg_connect
pg_connect
pg_connect
(string
(string
(string
(string
host, string port, string dbname)
host, string port, string options, string dbname)
host, string port, string options, string tty, string dbname)
conn_string)
Returns a connection index on success, or FALSE if the connection could not be made. Opens a connection to a
PostgreSQL database. The arguments should be within a quoted string.
Example 1. Using pg_connect arguments
<?php
$dbconn = pg_Connect ("dbname=mary");
//connect to a database named "mary"
$dbconn2 = pg_Connect ("host=localhost port=5432 dbname=mary");
//connect to a database named "mary" on "localhost" at port "5432"
$dbconn3 = pg_Connect ("host=sheep port=5432 dbname=mary user=lamb password=baaaa");
//connect to a database named "mary" on the host "sheep" with a username and password
?>
847
PostgreSQL
The arguments available include host, port, tty, options, dbname, user, and password .
If a second call is made to pg_connect() with the same arguments, no new connection will be established, but instead, the
connection index of the already opened connection will be returned.
!
This function returns a connection index that is needed by other PostgreSQL functions. You can have multiple connections
open at once.
"
The previous syntax of: $conn = pg_connect ("host", "port", "options", "tty", "dbname") has been deprecated.
See also pg_pconnect().
pg_dbname (PHP 3, PHP 4 >= 4.0b1)
Get the database name
#
string pg_dbname (int connection)
Returns the name of the database that the given PostgreSQL connection index is connected to, or FALSE if connection is
not a valid connection index.
$
pg_end_copy (PHP 4 >= 4.0.3)
Sync with PostgreSQL backend
bool pg_end_copy ([resource connection])
pg_end_copy() syncs PostgreSQL frontend with the backend after doing a copy operation. It must be issued or the
backend may get "out of sync" with the frontend. Returns TRUE if successfull, FALSE otherwise.
%
&
For further details and an example, see also pg_put_line().
pg_errormessage (PHP 3, PHP 4 >= 4.0b1)
Get the error message string
#
string pg_errormessage (int connection)
Returns a string containing the error message, FALSE on failure. Details about the error probably cannot be retrieved using
the pg_errormessage() function if an error occured on the last database action for which a valid connection exists, this
function will return a string containing the error message generated by the backend server.
'
'
pg_exec (PHP 3, PHP 4 >= 4.0b1)
Execute a query
(
int pg_exec (int connection, string query)
Returns a result index if query could be executed, FALSE on failure or if connection is not a valid connection index. Details
about the error can be retrieved using the pg_ErrorMessage() function if connection is valid. Sends an SQL statement to
the PostgreSQL database specified by the connection index. The connection must be a valid index that was returned by
pg_Connect(). The return value of this function is an index to be used to access the results from other PostgreSQL
functions.
848
PostgreSQL
)
Note: PHP/FI returned 1 if the query was not expected to return data (inserts or updates, for example) and greater
than 1 even on selects that did not return anything. No such assumption can be made in PHP.
pg_fetch_array (PHP 3>= 3.0.1, PHP 4 >= 4.0b1)
Fetch a row as an array
array pg_fetch_array (int result, int row [, int result_type])
&
Returns: An array that corresponds to the fetched row, or FALSE if there are no more rows.
pg_fetch_array() is an extended version of pg_fetch_row(). In addition to storing the data in the numeric indices of the
result array, it also stores the data in associative indices, using the field names as keys.
The third optional argument result_type in pg_fetch_array() is a constant and can take the following values:
PGSQL_ASSOC, PGSQL_NUM, and PGSQL_BOTH.
*
Note: Result_type was added in PHP 4.0.
An important thing to note is that using pg_fetch_array() is NOT significantly slower than using pg_fetch_row(), while it
provides a significant added value.
For further details, see also pg_fetch_row()
+
Example 1. PostgreSQL fetch array
<?php
$conn = pg_pconnect ("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
$result = pg_Exec ($conn, "SELECT * FROM authors");
if (!$result) {
echo "An error occured.\n";
exit;
}
$arr = pg_fetch_array ($result, 0);
echo $arr[0] . " <- array\n";
$arr = pg_fetch_array ($result, 1);
echo $arr["author"] . " <- array\n";
?>
pg_fetch_object (PHP 3>= 3.0.1, PHP 4 >= 4.0b1)
Fetch a row as an object
+
object pg_fetch_object (int result, int row [, int result_type])
&
Returns: An object with properties that correspond to the fetched row, or FALSE if there are no more rows.
849
PostgreSQL
pg_fetch_object() is similar to pg_fetch_array(), with one difference - an object is returned, instead of an array. Indirectly,
that means that you can only access the data by the field names, and not by their offsets (numbers are illegal property
names).
&
&
The third optional argument result_type in pg_fetch_object() is a constant and can take the following values:
PGSQL_ASSOC, PGSQL_NUM, and PGSQL_BOTH.
*
Note: Result_type was added in PHP 4.0.
Speed-wise, the function is identical to pg_fetch_array(), and almost as quick as pg_fetch_row() (the difference is
insignificant).
See also: pg_fetch_array() and pg_fetch_row().
,
Example 1. Postgres fetch object
<?php
$database = "verlag";
$db_conn = pg_connect ("host=localhost port=5432 dbname=$database");
if (!$db_conn): ?>
<H1>Failed connecting to postgres database <?php echo $database ?></H1> <?php
exit;
endif;
$qu = pg_exec ($db_conn, "SELECT * FROM verlag ORDER BY autor");
$row = 0; // postgres needs a row counter other dbs might not
while ($data = pg_fetch_object ($qu, $row)):
echo $data->autor." (";
echo $data->jahr ."): ";
echo $data->titel."<BR>";
$row++;
endwhile; ?>
<PRE><?php
$fields[] = Array ("autor", "Author");
$fields[] = Array ("jahr", " Year");
$fields[] = Array ("titel", " Title");
$row= 0; // postgres needs a row counter other dbs might not
while ($data = pg_fetch_object ($qu, $row)):
echo "--------\n";
reset ($fields);
while (list (,$item) = each ($fields)):
echo $item[1].": ".$data->$item[0]."\n";
endwhile;
$row++;
endwhile;
echo "--------\n"; ?>
</PRE> <?php
pg_freeResult ($qu);
pg_close ($db_conn);
?>
850
PostgreSQL
pg_fetch_row (PHP 3>= 3.0.1, PHP 4 >= 4.0b1)
#
Get a row as an enumerated array
array pg_fetch_row (int result, int row)
Returns: An array that corresponds to the fetched row, or FALSE if there are no more rows.
pg_fetch_row() fetches one row of data from the result associated with the specified result identifier. The row is returned
as an array. Each result column is stored in an array offset, starting at offset 0.
See also: pg_fetch_array(), pg_fetch_object(), pg_result().
Example 1. Postgres fetch row
<?php
$conn = pg_pconnect ("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
$result = pg_Exec ($conn, "SELECT * FROM authors");
if (!$result) {
echo "An error occured.\n";
exit;
}
$num = pg_numrows($result);
for ($i=0; $i<$num; $i++) {
$r = pg_fetch_row($result, $i);
for ($j=0; $j<count($r); $j++) {
echo "$r[$j]&nbsp;";
}
echo "<BR>";
}
?>
pg_fieldisnull (PHP 3, PHP 4 >= 4.0b1)
Test if a field is NULL
int pg_fieldisnull (int result_id, int row, mixed field)
Test if a field is NULL or not. Returns 0 if the field in the given row is not NULL. Returns 1 if the field in the given row is
NULL. Field can be specified as number or fieldname. Row numbering starts at 0.
851
PostgreSQL
pg_fieldname (PHP 3, PHP 4 >= 4.0b1)
Returns the name of a field
string pg_fieldname (int result_id, int field_number)
pg_fieldname() will return the name of the field occupying the given column number in the given PostgreSQL result
identifier. Field numbering starts from 0.
&
pg_fieldnum (PHP 3, PHP 4 >= 4.0b1)
Returns the field number of the named field
int pg_fieldnum (int result_id, string field_name)
pg_fieldnum() will return the number of the column slot that corresponds to the named field in the given PosgreSQL result
identifier. Field numbering starts at 0. This function will return -1 on error.
pg_fieldprtlen (PHP 3, PHP 4 >= 4.0b1)
Returns the printed length
int pg_fieldprtlen (int result_id, int row_number, string field_name)
pg_fieldprtlen() will return the actual printed length (number of characters) of a specific value in a PostgreSQL result.
Row numbering starts at 0. This function will return -1 on an error.
pg_fieldsize (PHP 3, PHP 4 >= 4.0b1)
Returns the internal storage size of the named field
int pg_fieldsize (int result_id, int field_number)
pg_fieldsize() will return the internal storage size (in bytes) of the field number in the given PostgreSQL result. Field
numbering starts at 0. A field size of -1 indicates a variable length field. This function will return FALSE on error.
pg_fieldtype (PHP 3, PHP 4 >= 4.0b1)
Returns the type name for the corresponding field number
string pg_fieldtype (int result_id, int field_number)
pg_fieldtype() will return a string containing the type name of the given field in the given PostgreSQL result identifier.
Field numbering starts at 0.
+
852
PostgreSQL
pg_freeresult (PHP 3, PHP 4 >= 4.0b1)
Free result memory
int pg_freeresult (int result_id)
pg_freeresult() only needs to be called if you are worried about using too much memory while your script is running. All
result memory will automatically be freed when the script is finished. But, if you are sure you are not going to need the
result data anymore in a script, you may call pg_freeresult() with the result identifier as an argument and the associated
result memory will be freed.
pg_getlastoid (PHP 3, PHP 4 >= 4.0b1)
Returns the last object identifier
int pg_getlastoid (int result_id)
pg_getlastoid() can be used to retrieve the oid assigned to an inserted tuple if the result identifier is used from the last
command sent via pg_exec() and was an SQL INSERT. This function will return a positive integer if there was a valid oid.
It will return -1 if an error occured or the last command sent via pg_exec() was not an INSERT.
pg_host (PHP 3, PHP 4 >= 4.0b1)
Returns the host name associated with the connection
string pg_host (int connection_id)
pg_host() will return the host name of the given PostgreSQL connection identifier is connected to.
pg_loclose (PHP 3, PHP 4 >= 4.0b1)
Close a large object
void pg_loclose (int fd)
&
pg_loclose() closes an Inversion Large Object. Fd is a file descriptor for the large object from pg_loopen().
pg_locreate (PHP 3, PHP 4 >= 4.0b1)
Create a large object
int pg_locreate (int conn)
pg_locreate() creates an Inversion Large Object and returns the oid of the large object. conn specifies a valid database
connection. PostgreSQL access modes INV_READ, INV_WRITE, and INV_ARCHIVE are not supported, the object is
created always with both read and write access. INV_ARCHIVE has been removed from PostgreSQL itself (version 6.3
and above).
853
PostgreSQL
pg_loexport (PHP 4 >= 4.0.1)
Export a large object to file
bool pg_loexport (int oid, int file [, int connection_id])
The oid argument specifies the object id of the large object to export and the filename argument specifies the pathname
of the file. Returns FALSE if an error occurred, TRUE otherwise. Remember that handling large objects in PostgreSQL must
happen inside a transaction.
&
pg_loimport (PHP 4 >= 4.0.1)
Import a large object from file
!
int pg_loimport (int file [, int connection_id])
&
The filename argument specifies the pathname of the file to be imported as a large object. Returns FALSE if an error
occurred, object id of the just created large object otherwise. Remember that handling large objects in PostgreSQL must
happen inside a transaction.
"
*
-
/
Note: When safe-mode is enabled, PHP checks whether the file(s)/directories you are about to operate on, have the
same UID as the script that is being executed.
.
.
pg_loopen (PHP 3, PHP 4 >= 4.0b1)
Open a large object
int pg_loopen (int conn, int objoid, string mode)
pg_loopen() open an Inversion Large Object and returns file descriptor of the large object. The file descriptor encapsulates
information about the connection. Do not close the connection before closing the large object file descriptor. objoid
specifies a valid large object oid and mode can be either "r", "w", or "rw".
&
pg_loread (PHP 3, PHP 4 >= 4.0b1)
Read a large object
string pg_loread (int fd, int len)
%
pg_loread() reads at most len bytes from a large object and returns it as a string. fd specifies a valid large object file
descriptor andlen specifies the maximum allowable size of the large object segment.
pg_loreadall (PHP 3, PHP 4 >= 4.0b1)
Read a entire large object and send straight to browser
void pg_loreadall (int fd)
854
PostgreSQL
pg_loreadall() reads a large object and passes it straight through to the browser after sending all pending headers. Mainly
intended for sending binary data like images or sound.
&
pg_lounlink (PHP 3, PHP 4 >= 4.0b1)
Delete a large object
void pg_lounlink (int conn, int lobjid)
pg_lounlink() deletes a large object with the lobjid identifier for that large object.
pg_lowrite (PHP 3, PHP 4 >= 4.0b1)
Write a large object
0
int pg_lowrite (int fd, string buf)
pg_lowrite() writes at most to a large object from a variable buf and returns the number of bytes actually written, or
FALSE in the case of an error. fd is a file descriptor for the large object from pg_loopen().
&
&
pg_numfields (PHP 3, PHP 4 >= 4.0b1)
Returns the number of fields
int pg_numfields (int result_id)
pg_numfields() will return the number of fields (columns) in a PostgreSQL result. The argument is a valid result identifier
returned by pg_exec(). This function will return -1 on error.
See also pg_numrows() and pg_cmdtuples().
pg_numrows (PHP 3, PHP 4 >= 4.0b1)
Returns the number of rows
int pg_numrows (int result_id)
pg_numrows() will return the number of rows in a PostgreSQL result. The argument is a valid result identifier returned by
pg_exec(). This function will return -1 on error.
See also pg_numfields() and pg_cmdtuples().
pg_options (PHP 3, PHP 4 >= 4.0b1)
Get the options associated with the connection
#
string pg_options (int connection_id)
pg_options() will return a string containing the options specified on the given PostgreSQL connection identifier.
855
PostgreSQL
pg_pconnect (PHP 3, PHP 4 >= 4.0b1)
Open a persistent PostgreSQL connection
int pg_pconnect (string conn_string)
Returns a connection index on success, or FALSE if the connection could not be made. Opens a connection to a
PostgreSQL database. The arguments should be within a quoted string. The arguments available include host, port,
tty, options, dbname, user, and password .
This function returns a connection index that is needed by other PostgreSQL functions. You can have multiple connections
open at once.
The previous syntax of: $conn = pg_pconnect ("host", "port", "options", "tty", "dbname") has been deprecated.
See also pg_connect().
pg_port (PHP 3, PHP 4 >= 4.0b1)
Return the port number associated with the connection
int pg_port (int connection_id)
pg_port() will return the port number that the given PostgreSQL connection identifier is connected to.
pg_put_line (PHP 4 >= 4.0.3)
Send a NULL-terminated string to PostgreSQL backend
bool pg_put_line ([resource connection_id, string data])
pg_put_line() sends a NULL-terminated string to the PostgreSQL backend server. This is useful for example for very
high-speed inserting of data into a table, initiated by starting a PostgreSQL copy-operation. That final NULL-character is
added automatically. Returns TRUE if successfull, FALSE otherwise.
"
*
1
Note: Note the application must explicitly send the two characters "\." on a final line to indicate to the backend that it
has finished sending its data.
See also pg_end_copy().
,
Example 1. High-speed insertion of data into a table
<?php
$conn = pg_pconnect ("dbname=foo");
pg_exec($conn, "create table bar (a int4, b char(16), d float8)");
pg_exec($conn, "copy bar from stdin");
pg_put_line($conn, "3\thello world\t4.5\n");
pg_put_line($conn, "4\tgoodbye world\t7.11\n");
pg_put_line($conn, "\\.\n");
pg_end_copy($conn);
?>
856
PostgreSQL
pg_result (PHP 3, PHP 4 >= 4.0b1)
Returns values from a result identifier
mixed pg_result (int result_id, int row_number, mixed fieldname)
pg_result() will return values from a result identifier produced by pg_Exec(). The row_number and fieldname
sepcify what cell in the table of results to return. Row numbering starts from 0. Instead of naming the field, you may use
the field index as an unquoted number. Field indices start from 0.
PostgreSQL has many built in types and only the basic ones are directly supported here. All forms of integer, boolean and
oid types are returned as integer values. All forms of float, and real types are returned as double values. All other types,
including arrays are returned as strings formatted in the same default PostgreSQL manner that you would see in the psql
program.
&
pg_set_client_encoding (PHP 3 CVS only, PHP 4 >= 4.0.3)
Set the client encoding
int pg_set_client_encoding ([int connection, string encoding])
The function set the client encoding and return 0 if success or -1 if error.
encoding is the client encoding and can be either : SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE,
MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5, WIN1250.
2
*
3
Note: This function requires PHP-4.0.2 or higher and PostgreSQL-7.0 or higher.
The function used to be called pg_setclientencoding().
4
See also pg_client_encoding().
pg_client_encoding (PHP 3 CVS only, PHP 4 >= 4.0.3)
#
Get the client encoding
string pg_client_encoding ([int connection])
The functions returns the client encoding as the string. The returned string should be either : SQL_ASCII, EUC_JP,
EUC_CN, EUC_KR, EUC_TW, UNICODE, MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5,
WIN1250.
(
0
*
3
Note: This function requires PHP-4.0.2 or higher and PostgreSQL-7.0 or higher.
3
The function used to be called pg_clientencoding().
4
See also pg_set_client_encoding().
pg_trace (PHP 4 >= 4.0.1)
Enable tracing a PostgreSQL connection
bool pg_trace (string filename [, string mode [, int connection]])
857
PostgreSQL
Enables tracing of the PostgreSQL frontend/backend communication to a debugging file. To fully understand the results
one needs to be familiar with the internals of PostgreSQL communication protocol. For those who are not, it can still be
useful for tracing errors in queries sent to the server, you could do for example grep ’^To backend’ trace.log and see what
query actually were sent to the PostgreSQL server.
(
6
5
7
'
Filename and mode are the same as in fopen() (mode defaults to ’w’), connection specifies the connection to trace
and defaults to the last one opened.
&
Returns TRUE if filename could be opened for logging, FALSE otherwise.
'
See also fopen() and pg_untrace().
pg_tty (PHP 3, PHP 4 >= 4.0b1)
Return the tty name associated with the connection
string pg_tty (int connection_id)
pg_tty() will return the tty name that server side debugging output is sent to on the given PostgreSQL connection identifier.
pg_untrace (PHP 4 >= 4.0.1)
Disable tracing of a PostgreSQL connection
8
bool pg_untrace ([int connection])
Stop tracing started by pg_trace(). connection specifies the connection that was traced and defaults to the last one
opened.
Returns always TRUE.
See also pg_trace().
858
Download PDF
Similar pages