<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.pg-pconnect" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>pg_pconnect</refname>

<refpurpose>

Établit une connexion PostgreSQL persistante

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>PgSql\Connection</type><type>false</type></type><methodname>pg_pconnect</methodname>

<methodparam><type>string</type><parameter>connection_string</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>

</methodsynopsis>

<para>

<function>pg_pconnect</function> retourne une instance <classname>PgSql\Connection</classname>

de connexion persistante.

</para>

<para>

Si un second appel est fait à <function>pg_pconnect</function> avec le même

<parameter>connection_string</parameter> comme étant une connexion

existante, la connexion existante sera retournée à moins qu'on ne passe

<constant>PGSQL_CONNECT_FORCE_NEW</constant> à

<parameter>flags</parameter>.

</para>

<para>

Pour activer les connexions persistantes, la directive de configuration

<link linkend="ini.pgsql.allow-persistent">pgsql.allow_persistent</link>

du &php.ini; doit être mise à <literal>On</literal> (ce qui est sa valeur par défaut).

Le nombre maximal de connexions peut être limité grâce

à la directive de configuration

<link linkend="ini.pgsql.max-persistent">pgsql.max_persistent</link>

dans le fichier &php.ini; (par défaut, elle vaut <literal>-1</literal>, c'est-à-dire pas de limite).

Le nombre total de connexions peut être configuré avec la directive

<link linkend="ini.pgsql.max-links">pgsql.max_links</link> du fichier

&php.ini;.

</para>

<para>

<function>pg_close</function> ne refermera pas les connexions persistantes

générées par <function>pg_pconnect</function>.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>connection_string</parameter></term>

<listitem>

<para>

La chaîne <parameter>connection_string</parameter> peut être vide pour

utiliser tous les paramètres par défaut ou elle peut contenir un ou

plusieurs paramètres de configuration séparés par des espaces.

Chaque paramètre de configuration est sous la forme <literal>code =

valeur</literal>. Les espaces autour du signe égal sont optionnels.

Pour écrire une valeur vide ou une valeur contenant des espaces,

entourez cette valeur avec des apostrophes, par exemple : <literal>code =

'une valeur'</literal>. Les apostrophes et les antislashs à l'intérieur

de la valeur doivent être échappés par un antislash, c'est-à-dire

<literal>\'</literal> et <literal>\\</literal>.

</para>

<para>

Les mots-clé actuellement reconnus sont :

<parameter>host</parameter>, <parameter>hostaddr</parameter>,

<parameter>port</parameter>,

<parameter>dbname</parameter>, <parameter>user</parameter>,

<parameter>password</parameter>,

<parameter>connect_timeout</parameter>,

<parameter>options</parameter>, <parameter>tty</parameter> (ignoré),

<parameter>sslmode</parameter>,

<parameter>requiressl</parameter> (obsolète, utiliser

<parameter>sslmode</parameter>) et

<parameter>service</parameter>.

La liste de ces arguments dépend de la version du serveur PostgreSQL.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>flags</parameter></term>

<listitem>

<para>

Si <constant>PGSQL_CONNECT_FORCE_NEW</constant> est passé en argument,

alors une nouvelle connexion sera créée, même si la chaîne

<parameter>connection_string</parameter> est identique à celle de la

connexion existante.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Retourne une instance de <classname>PgSql\Connection</classname> en cas de succès, &return.falseforfailure;.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.1.0</entry>

<entry>

Retourne désormais une instance de <classname>PgSql\Connection</classname> ;

auparavant, une &resource; était retournée.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Exemple avec <function>pg_pconnect</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>pg_connect</function></member>

<member>

<link linkend="features.persistent-connections">

Connexions Persistantes</link>

</member>

</simplelist>

</para>

</refsect1>

</refentry>