From b39321c1b93848d7b2835030d88fdc99e1d921b6 Mon Sep 17 00:00:00 2001 From: Jeroen van Wolffelaar Date: Fri, 3 Aug 2001 19:24:40 +0000 Subject: [PATCH] Resurrected pgsql, hopefully not reserved anymore git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@53183 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/pgsql.xml | 1458 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1458 insertions(+) create mode 100644 functions/pgsql.xml diff --git a/functions/pgsql.xml b/functions/pgsql.xml new file mode 100644 index 0000000000..6832252b20 --- /dev/null +++ b/functions/pgsql.xml @@ -0,0 +1,1458 @@ + + + PostgreSQL functions + PostgreSQL + + + + 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. + + + 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". + + Postmaster and PHP + + + + Postmaster + PHP + Status + + + + + postmaster & + pg_connect("dbname=MyDbName"); + OK + + + postmaster -i & + + pg_connect("dbname=MyDbName"); + OK + + + postmaster & + 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. + + 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"); +?> + + + + + + + + pg_close + Close a PostgreSQL connection + + + Description + + + 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. + + + 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 + Returns number of affected tuples + + + Description + + + 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. + + <function>pg_cmdtuples</function> + +<?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 + Open a PostgreSQL connection + + + Description + + + int pg_connect + string host + string port + string dbname + + + int pg_connect + string host + string port + string options + string dbname + + + int pg_connect + string host + string port + string options + string tty + string dbname + + + int pg_connect + 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. + + 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 +?> + + + 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 + Get the database name + + + Description + + + 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 + Sync with PostgreSQL backend + + + Description + + + 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 + Get the error message string + + + Description + + + 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 + Execute a query + + + Description + + + 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. + + + 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 + Fetch a row as an array + + + Description + + + 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. + + + 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 + + + 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 + Fetch a row as an object + + + Description + + + 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. + + + 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. + + + 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. + + 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); +?> + + + + + + + + + pg_fetch_row + Get a row as an enumerated array + + + Description + + + 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. + + 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 + Test if a field is &null; + + + Description + + + 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. + + + + + + + pg_fieldname + Returns the name of a field + + + Description + + + 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 + Returns the field number of the named field + + + Description + + + 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 + Returns the printed length + + + Description + + + 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 + + Returns the internal storage size of the named field + + + + Description + + + 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 + + Returns the type name for the corresponding field number + + + + Description + + + 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. + + + + + + + pg_freeresult + Free result memory + + + Description + + + 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 + Returns the last object identifier + + + Description + + + 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 + + Returns the host name associated with the connection + + + + Description + + + string pg_host + int connection_id + + + + pg_host will return the host name of the + given PostgreSQL connection identifier is connected to. + + + + + + + pg_loclose + Close a large object + + + Description + + + 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 + Create a large object + + + Description + + + 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). + + + + + + + pg_loexport + Export a large object to file + + + Description + + + 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 + Import a large object from file + + + Description + + + 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. + + ¬e.sm.uidcheck; + + + + + + pg_loopen + Open a large object + + + Description + + + 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 + Read a large object + + + Description + + + 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 + + Read a entire large object and send straight to browser + + + + Description + + + void pg_loreadall + int fd + + + + 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 + Delete a large object + + + Description + + + void pg_lounlink + int conn + int lobjid + + + + pg_lounlink deletes a large object with the + lobjid identifier for that large object. + + + + + + + pg_lowrite + Write a large object + + + Description + + + 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 + Returns the number of fields + + + Description + + + 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 + Returns the number of rows + + + Description + + + 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 + Get the options associated with the connection + + + Description + + + string pg_options + int connection_id + + + + pg_options will return a string containing + the options specified on the given PostgreSQL connection + identifier. + + + + + + + pg_pconnect + Open a persistant PostgreSQL connection + + + Description + + + 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 + + Return the port number associated with the connection + + + + Description + + + 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 + Send a NULL-terminated string to PostgreSQL backend + + + Description + + + 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. + + + + 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. + + 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); +?> + + + + + + + + + pg_result + Returns values from a result identifier + + + Description + + + 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 + + Set the client encoding + + + + Description + + + 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. + + + + This function requires PHP-4.0.2 or higher and PostgreSQL-7.0 or + higher. + + + The function used to be called + pg_setclientencoding. + + + + See also pg_client_encoding. + + + + + + + pg_client_encoding + + Get the client encoding + + + + Description + + + 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. + + + + This function requires PHP-4.0.2 or higher and PostgreSQL-7.0 or + higher. + + + The function used to be called + pg_clientencoding. + + + + See also pg_set_client_encoding. + + + + + + + pg_trace + Enable tracing a PostgreSQL connection + + + Description + + + bool pg_trace + string + filename + + string + mode + + int + connection + + + + + 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. + + + 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 + + Return the tty name associated with the connection + + + + Description + + + 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 + Disable tracing of a PostgreSQL connection + + + Description + + + 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. + + + + + + +