<primary><literal>URI</literal></primary>
   </indexterm>

   <para>
    Several <application>libpq</application> functions parse a user-specified string to obtain
    connection parameters.  There are two accepted formats for these strings:
    plain keyword/value strings
    and URIs.  URIs generally follow
    <ulink url="https://datatracker.ietf.org/doc/html/rfc3986">RFC
    3986</ulink>, except that multi-host connection strings are allowed
    as further described below.
   </para>

   <sect3 id="libpq-connstring-keyword-value">
    <title>Keyword/Value Connection Strings</title>

   <para>
    In the keyword/value format, each parameter setting is in the form
    <replaceable>keyword</replaceable> <literal>=</literal>
    <replaceable>value</replaceable>, with space(s) between settings.
    Spaces around a setting's equal sign are
    optional. To write an empty value, or a value containing spaces, surround it
    with single quotes, for example <literal>keyword = 'a value'</literal>.
    Single quotes and backslashes within
    a value must be escaped with a backslash, i.e., <literal>\'</literal> and
    <literal>\\</literal>.
   </para>

   <para>
    Example:
<programlisting>
host=localhost port=5432 dbname=mydb connect_timeout=10
</programlisting>
   </para>

   <para>
    The recognized parameter key words are listed in <xref
    linkend="libpq-paramkeywords"/>.
   </para>
   </sect3>

   <sect3 id="libpq-connstring-uris">
    <title>Connection URIs</title>

   <para>
   The general form for a connection <acronym>URI</acronym> is:
<synopsis>
postgresql://<optional><replaceable>userspec</replaceable>@</optional><optional><replaceable>hostspec</replaceable></optional><optional>/<replaceable>dbname</replaceable></optional><optional>?<replaceable>paramspec</replaceable></optional>

<phrase>where <replaceable>userspec</replaceable> is:</phrase>

<replaceable>user</replaceable><optional>:<replaceable>password</replaceable></optional>

<phrase>and <replaceable>hostspec</replaceable> is:</phrase>

<optional><replaceable>host</replaceable></optional><optional>:<replaceable>port</replaceable></optional><optional>,...</optional>

<phrase>and <replaceable>paramspec</replaceable> is:</phrase>

<replaceable>name</replaceable>=<replaceable>value</replaceable><optional>&amp;...</optional>
</synopsis>
   </para>

   <para>
    The <acronym>URI</acronym> scheme designator can be either
    <literal>postgresql://</literal> or <literal>postgres://</literal>.  Each
    of the remaining <acronym>URI</acronym> parts is optional.  The
    following examples illustrate valid <acronym>URI</acronym> syntax:
<programlisting>
postgresql://
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/mydb
postgresql://user@localhost
postgresql://user:secret@localhost
postgresql://other@localhost/otherdb?connect_timeout=10&amp;application_name=myapp
postgresql://host1:123,host2:456/somedb?target_session_attrs=any&amp;application_name=myapp
</programlisting>
    Values that would normally appear in the hierarchical part of
    the <acronym>URI</acronym> can alternatively be given as named
    parameters.  For example:
<programlisting>
postgresql:///mydb?host=localhost&amp;port=5433
</programlisting>
    All named parameters must match key words listed in
    <xref linkend="libpq-paramkeywords"/>, except that for compatibility
    with JDBC connection <acronym>URI</acronym>s, instances
    of <literal>ssl=true</literal> are translated into
    <literal>sslmode=require</literal>.
   </para>

   <para>
    The connection <acronym>URI</acronym> needs to be encoded with <ulink
    url="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1">percent-encoding</ulink>
    if it includes symbols with special meaning in any of its parts.  Here is
    an example where the equal sign (<literal>=</literal>) is replaced with
    <literal>%3D</literal> and the space character with
    <literal>%20</literal>:
<programlisting>
postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff