mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
* Add examples to the 3 remaining functions that didn't have them: pg_convert(), pg_field_prtlen() and pg_set_client_encoding().
* Large rewrite of the PostgreSQL overview page. Bring it up to date and similar to the MySQL extension overview page. Remove complexities, clutter and references to truly old versions. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@195156 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Christopher Kings-Lynne
parent
1a2bfd872a
commit
e1ddb8003d
4 changed files with 194 additions and 271 deletions
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.13 $ -->
|
||||
<!-- $Revision: 1.14 $ -->
|
||||
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.80 -->
|
||||
<refentry id='function.pg-convert'>
|
||||
<refnamediv>
|
||||
|
|
@ -88,7 +88,31 @@
|
|||
An <type>array</type> of converted values, or &false; on error.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
<example>
|
||||
<title><function>pg_convert</function> example</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$dbconn = pg_connect('dbname=foo');
|
||||
|
||||
$tmp = array(
|
||||
'author' => 'Joe Thackery',
|
||||
'year' => 2005,
|
||||
'title' => 'My Life, by Joe Thackery'
|
||||
);
|
||||
|
||||
$vals = pg_convert($dbconn, 'authors', $tmp);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.10 $ -->
|
||||
<!-- $Revision: 1.11 $ -->
|
||||
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
|
||||
<refentry id="function.pg-field-prtlen">
|
||||
<refnamediv>
|
||||
|
|
@ -75,7 +75,56 @@
|
|||
The field printed length, or &false; on error.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
<example>
|
||||
<title>Getting information about fields</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
|
||||
|
||||
$res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
|
||||
$i = pg_num_fields($res);
|
||||
for ($j = 0; $j < $i; $j++) {
|
||||
echo "column $j\n";
|
||||
$fieldname = pg_field_name($res, $j);
|
||||
echo "fieldname: $fieldname\n";
|
||||
echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
|
||||
echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
|
||||
echo "field type: " . pg_field_type($res, $j) . " \n\n";
|
||||
}
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
column 0
|
||||
fieldname: author
|
||||
printed length: 6 characters
|
||||
storage length: -1 bytes
|
||||
field type: varchar
|
||||
|
||||
column 1
|
||||
fieldname: year
|
||||
printed length: 4 characters
|
||||
storage length: 2 bytes
|
||||
field type: int2
|
||||
|
||||
column 2
|
||||
fieldname: title
|
||||
printed length: 24 characters
|
||||
storage length: -1 bytes
|
||||
field type: varchar
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.9 $ -->
|
||||
<!-- $Revision: 1.10 $ -->
|
||||
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.16 -->
|
||||
<refentry id="function.pg-set-client-encoding">
|
||||
<refnamediv>
|
||||
|
|
@ -77,7 +77,44 @@
|
|||
Returns 0 on success or -1 on error.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
<example>
|
||||
<title><function>pg_set_client_encoding</function> example</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
|
||||
$conn = pg_pconnect("dbname=publisher");
|
||||
if (!$conn) {
|
||||
echo "An error occured.\n";
|
||||
exit;
|
||||
}
|
||||
|
||||
// Set the client encoding to UNICODE. Data will be automatically
|
||||
// converted from the backend encoding to the frontend.
|
||||
pg_set_client_encoding($conn, UNICODE);
|
||||
|
||||
$result = pg_query($conn, "SELECT author, email FROM authors");
|
||||
if (!$result) {
|
||||
echo "An error occured.\n";
|
||||
exit;
|
||||
}
|
||||
|
||||
// Write out UTF-8 data
|
||||
while ($row = pg_fetch_row($result)) {
|
||||
echo "Author: $row[0] E-mail: $row[1]";
|
||||
echo "<br />\n";
|
||||
}
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.26 $ -->
|
||||
<!-- $Revision: 1.27 $ -->
|
||||
<!-- Purpose: database.vendors -->
|
||||
<!-- Membership: bundled, external -->
|
||||
|
||||
|
|
@ -26,7 +26,7 @@
|
|||
<para>
|
||||
To use PostgreSQL support, you need PostgreSQL 6.5 or
|
||||
later, PostgreSQL 8.0 or later to enable all PostgreSQL module
|
||||
features. PostgreSQL supports many character encoding including
|
||||
features. PostgreSQL supports many character encodings including
|
||||
multibyte character encoding. The current version and more
|
||||
information about PostgreSQL is available at
|
||||
<ulink url="&url.pgsql;">&url.pgsql;</ulink> and
|
||||
|
|
@ -38,282 +38,95 @@
|
|||
|
||||
&reference.pgsql.ini;
|
||||
|
||||
<section id="pgsql.using">
|
||||
<title>How to use and hints</title>
|
||||
<warning>
|
||||
<para>
|
||||
Using the PostgreSQL module with PHP 4.0.6 is not recommended due to
|
||||
a bug in the notice message handling code. Use 4.1.0 or later.
|
||||
</para>
|
||||
</warning>
|
||||
<warning>
|
||||
<para>
|
||||
PostgreSQL function names will be changed in 4.2.0 release to
|
||||
confirm to current coding standards. Most of new names will have
|
||||
additional underscores, e.g. pg_lo_open(). Some functions are
|
||||
renamed to different name for consistency. e.g. pg_exec() to
|
||||
pg_query(). Older names can be used in 4.2.0 and a few releases
|
||||
from 4.2.0, but they may be deleted in the future.
|
||||
</para>
|
||||
<table>
|
||||
<title>Function names changed</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Old name</entry>
|
||||
<entry>New name</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><function>pg_cmdtuples</function></entry>
|
||||
<entry><function>pg_affected_rows</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_errormessage</function></entry>
|
||||
<entry><function>pg_last_error</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_exec</function></entry>
|
||||
<entry><function>pg_query</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_fieldname</function></entry>
|
||||
<entry><function>pg_field_name</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_fieldsize</function></entry>
|
||||
<entry><function>pg_field_size</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_fieldnum</function></entry>
|
||||
<entry><function>pg_field_num</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_fieldprtlen</function></entry>
|
||||
<entry><function>pg_field_prtlen</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_fieldisnull</function></entry>
|
||||
<entry><function>pg_field_is_null</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_freeresult</function></entry>
|
||||
<entry><function>pg_free_result</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_getlastoid</function></entry>
|
||||
<entry><function>pg_last_oid</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_loreadall</function></entry>
|
||||
<entry><function>pg_lo_read_all</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_locreate</function></entry>
|
||||
<entry><function>pg_lo_create</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_lounlink</function></entry>
|
||||
<entry><function>pg_lo_unlink</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_loopen</function></entry>
|
||||
<entry><function>pg_lo_open</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_loclose</function></entry>
|
||||
<entry><function>pg_lo_close</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_loread</function></entry>
|
||||
<entry><function>pg_lo_read</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_lowrite</function></entry>
|
||||
<entry><function>pg_lo_write</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_loimport</function></entry>
|
||||
<entry><function>pg_lo_import</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_loexport</function></entry>
|
||||
<entry><function>pg_lo_export</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_numrows</function></entry>
|
||||
<entry><function>pg_num_rows</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_numfields</function></entry>
|
||||
<entry><function>pg_num_fields</function></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>pg_result</function></entry>
|
||||
<entry><function>pg_fetch_result</function></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
<section id="pgsql.resources">
|
||||
&reftitle.resources;
|
||||
<para>
|
||||
The old <function>pg_connect</function>/<function>pg_pconnect</function>
|
||||
syntax will be deprecated to support asynchronous connections in the
|
||||
future. Please use a connection string for <function>pg_connect</function>
|
||||
and <function>pg_pconnect</function>.
|
||||
There are two resource types used in the PostgreSQL module. The first one
|
||||
is the link identifier for a database connection, the second a resource
|
||||
which holds the result of a query.
|
||||
</para>
|
||||
</warning>
|
||||
<para>
|
||||
Not all functions are supported by all builds. It depends on your
|
||||
libpq (The PostgreSQL C Client interface) version and how libpq is
|
||||
compiled. If there is missing function, libpq does not support
|
||||
the feature required for the function.
|
||||
</para>
|
||||
<para>
|
||||
It is also important that you do not use an older libpq than the PostgreSQL
|
||||
Server to which you will be connecting. If you use libpq older than PostgreSQL
|
||||
Server expects, you may have problems.
|
||||
</para>
|
||||
<para>
|
||||
Since version 6.3 (03/02/1998) PostgreSQL uses unix domain sockets
|
||||
by default. TCP port will NOT be opened by default. A table is
|
||||
shown below describing these new connection possibilities. This
|
||||
socket will be found in <filename>/tmp/.s.PGSQL.5432</filename>.
|
||||
This option can be enabled with the '-i' flag to
|
||||
<command>postmaster</command> and its meaning is: "listen on
|
||||
TCP/IP sockets as well as Unix domain sockets".
|
||||
<table>
|
||||
<title>Postmaster and PHP</title>
|
||||
<tgroup cols="3">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Postmaster</entry>
|
||||
<entry>PHP</entry>
|
||||
<entry>Status</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>postmaster &</entry>
|
||||
<entry>pg_connect("dbname=MyDbName");</entry>
|
||||
<entry>OK</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>postmaster -i &</entry>
|
||||
<entry>pg_connect("dbname=MyDbName");</entry>
|
||||
<entry>OK</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>postmaster &</entry>
|
||||
<entry>pg_connect("host=localhost dbname=MyDbName");</entry>
|
||||
<entry>
|
||||
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.php on line 20.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>postmaster -i &</entry>
|
||||
<entry>pg_connect("host=localhost dbname=MyDbName");</entry>
|
||||
<entry>OK</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
<para>
|
||||
A connection to PostgreSQL server can be established with the
|
||||
following value pairs set in the command string: <command>$conn =
|
||||
pg_connect("host=myHost port=myPort tty=myTTY options=myOptions
|
||||
dbname=myDB user=myUser password=myPassword ");
|
||||
</command>
|
||||
</para>
|
||||
<para>
|
||||
The previous syntax of:
|
||||
<command>
|
||||
$conn = pg_connect ("host", "port", "options", "tty", "dbname")
|
||||
</command>
|
||||
has been deprecated.
|
||||
</para>
|
||||
<para>
|
||||
Environmental variables affect PostgreSQL server/client
|
||||
behavior. For example, PostgreSQL module will lookup PGHOST
|
||||
environment variable when the hostname is omitted in the connection
|
||||
string. Supported environment variables are different from version
|
||||
to version. Refer to PostgreSQL Programmer's Manual (libpq -
|
||||
Environment Variables) for details.
|
||||
</para>
|
||||
<para>
|
||||
Make sure you set environment variables for appropriate user. Use
|
||||
<literal>$_ENV</literal> or <function>getenv</function> to check
|
||||
which environment variables are available to the current process.
|
||||
</para>
|
||||
<example>
|
||||
<title>Setting default parameters</title>
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
PGHOST=pgsql.example.com
|
||||
PGPORT=7890
|
||||
PGDATABASE=web-system
|
||||
PGUSER=web-user
|
||||
PGPASSWORD=secret
|
||||
PGDATESTYLE=ISO
|
||||
PGTZ=JST
|
||||
PGCLIENTENCODING=EUC-JP
|
||||
|
||||
export PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD PGDATESTYLE PGTZ PGCLIENTENCODING
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
<note>
|
||||
<para>
|
||||
PostgreSQL automatically folds all identifiers (e.g. table/column names)
|
||||
to lower-case values. To get it to recognize upper-case values, you must
|
||||
always wrap the identifier in quotes.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
||||
|
||||
&reference.pgsql.constants;
|
||||
|
||||
<section id="pgsql.notes">
|
||||
&reftitle.notes;
|
||||
<note>
|
||||
<para>
|
||||
Not all functions are supported by all builds. It depends on your
|
||||
libpq (The PostgreSQL C client library) version and how libpq is
|
||||
compiled. If PHP PostgreSQL extensions are missing, then it is because
|
||||
your libpq version does not support them.
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>
|
||||
Most PostgreSQL functions accept <parameter>connection</parameter> as
|
||||
the first optional parameter. If it is not provided, the last opened
|
||||
connection is used. If it doesn't exist, functions return &false;.
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>
|
||||
PostgreSQL automatically folds all identifiers (e.g. table/column names)
|
||||
to lower-case values at object creation time and at query time.
|
||||
To force the use of mixed or upper case identifiers, you must escape
|
||||
the identifier using double quotes ("").
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>
|
||||
PostgreSQL does not have special commands for fetching database schema
|
||||
information (eg. all the tables in the current database). Instead, there
|
||||
is a standard schema named <literal>information_schema</literal> in
|
||||
PostgreSQL 7.4 and above containing
|
||||
system views with all the necessary information, in an easily
|
||||
queryable form. See the <ulink url="&url.pgsql.manual;">PostgreSQL Documentation</ulink>
|
||||
for full details.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
||||
|
||||
<section id="pgsql.examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
Starting with PostgreSQL 7.1.0, you can store up to 1GB into a
|
||||
field of type text. In older versions, this was limited to the block
|
||||
size (default was 8KB, maximum was 32KB, defined at compile time)
|
||||
</para>
|
||||
<para>
|
||||
To use the large object (lo) interface, it is required to enclose
|
||||
large object functions within a transaction block. A transaction
|
||||
block starts with a SQL statement <command>BEGIN</command> and if
|
||||
the transaction was valid ends with <command>COMMIT</command> or
|
||||
<command>END</command>. If the transaction fails the transaction
|
||||
should be closed with <command>ROLLBACK</command> or
|
||||
<command>ABORT</command>.
|
||||
<example>
|
||||
<title>Using Large Objects</title>
|
||||
<programlisting role="php">
|
||||
<para>
|
||||
This simple example shows how to connect, execute a query, print
|
||||
resulting rows and disconnect from a PostgreSQL database.
|
||||
<example>
|
||||
<title>PostgreSQL extension overview example</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$database = pg_connect("dbname=jacarta");
|
||||
pg_query($database, "begin");
|
||||
$oid = pg_lo_create($database);
|
||||
echo "$oid\n";
|
||||
$handle = pg_lo_open($database, $oid, "w");
|
||||
echo "$handle\n";
|
||||
pg_lo_write($handle, "large object data");
|
||||
pg_lo_close($handle);
|
||||
pg_query($database, "commit");
|
||||
// Connecting, selecting database
|
||||
$db = pg_connect("host=localhost dbname=publishing user=www password=foo");
|
||||
or die('Could not connect: ' . pg_last_error());
|
||||
|
||||
// Performing SQL query
|
||||
$query = 'SELECT * FROM authors';
|
||||
$result = pg_query($query) or die('Query failed: ' . pg_last_error());
|
||||
|
||||
// Printing results in HTML
|
||||
echo "<table>\n";
|
||||
while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
|
||||
echo "\t<tr>\n";
|
||||
foreach ($line as $col_value) {
|
||||
echo "\t\t<td>$col_value</td>\n";
|
||||
}
|
||||
echo "\t</tr>\n";
|
||||
}
|
||||
echo "</table>\n";
|
||||
|
||||
// Free resultset
|
||||
pg_free_result($result);
|
||||
|
||||
// Closing connection
|
||||
pg_close($link);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
You should not close the connection to the PostgreSQL server
|
||||
before closing the large object.
|
||||
</para>
|
||||
</section>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</section>
|
||||
</partintro>
|
||||
|
||||
&reference.pgsql.functions;
|
||||
|
|
|
|||
Loading…
Reference in a new issue