Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit a5f5885

Browse files
author
Liudmila Mantrova
committed
[Doc]: Switch to PGPRO10: autocommit based on fd1b8a7
1 parent 2990d88 commit a5f5885

File tree

6 files changed

+231
-0
lines changed

6 files changed

+231
-0
lines changed

‎doc/src/sgml/config.sgml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -635,6 +635,21 @@ include_dir 'conf.d'
635635
</listitem>
636636
</varlistentry>
637637

638+
<varlistentry id="listen-rdma-addresses" xreflabel="listen_rdma_addresses">
639+
<term><varname>listen_rdma_addresses</varname> (<type>string</type>)
640+
<indexterm>
641+
<primary><varname>listen_rdma_addresses</> configuration parameter</primary>
642+
</indexterm>
643+
</term>
644+
<listitem>
645+
<para>
646+
Specifies the TCP/IP address(es) on which the server is to listen for new remote direct memory access (<literal>RDMA</literal>) connections via <literal>rsocket</literal> from client applications. The value takes the form of a comma-separated list of host names
647+
and/or numeric IP addresses. The special entry <literal>*</>
648+
corresponds to all available IP interfaces.
649+
</para>
650+
</listitem>
651+
</varlistentry>
652+
638653
<varlistentry id="guc-port" xreflabel="port">
639654
<term><varname>port</varname> (<type>integer</type>)
640655
<indexterm>

‎doc/src/sgml/installation.sgml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -798,6 +798,17 @@ su - postgres
798798
</listitem>
799799
</varlistentry>
800800

801+
802+
<varlistentry>
803+
<term><option>--with-rsocket</option></term>
804+
<listitem>
805+
<para>
806+
Enable <literal>rsocket</literal> API support for remote direct memory access (<acronym>RDMA</acronym>).
807+
You must also set the <xref linkend="listen-rdma-addresses"> variable for your server to enable <acronym>RDMA</acronym> connections via <literal>rsocket</literal>.
808+
</para>
809+
</listitem>
810+
</varlistentry>
811+
801812
<varlistentry>
802813
<term><option>--with-openssl</option>
803814
<indexterm>

‎doc/src/sgml/libpq.sgml

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1130,6 +1130,17 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
11301130
</listitem>
11311131
</varlistentry>
11321132

1133+
<varlistentry id="libpq-with-rsocket" xreflabel="libpq_with_rsocket">
1134+
<term><literal>with_rsocket</literal></term>
1135+
<listitem>
1136+
<para>
1137+
Connects to the server using <literal>rsocket</literal> API.
1138+
You must also set the <xref linkend="listen-rdma-addresses"> variable for your server to enable <acronym>RDMA</acronym> connections via <literal>rsocket</literal>.
1139+
</para>
1140+
</listitem>
1141+
</varlistentry>
1142+
1143+
11331144
<varlistentry id="libpq-connect-application-name" xreflabel="application_name">
11341145
<term><literal>application_name</literal></term>
11351146
<listitem>
@@ -7247,6 +7258,16 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
72477258
linkend="libpq-connect-target-session-attrs"> connection parameter.
72487259
</para>
72497260
</listitem>
7261+
7262+
<listitem>
7263+
<para>
7264+
<indexterm>
7265+
<primary><envar>WITH_RSOCKET</envar></primary>
7266+
</indexterm>
7267+
<envar>WITH_RSOCKET</envar> behaves the same as the <xref linkend="libpq-with-rsocket"> connection parameter.
7268+
</para>
7269+
</listitem>
7270+
72507271
</itemizedlist>
72517272
</para>
72527273

‎doc/src/sgml/ref/pg_basebackup.sgml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -553,6 +553,16 @@ doc/src/sgml/ref/pg_basebackup.sgml
553553
</listitem>
554554
</varlistentry>
555555

556+
<varlistentry>
557+
<term><option>--with-rsocket</option></term>
558+
<listitem>
559+
<para>
560+
Connects to the server using <literal>rsocket</literal> API.
561+
You must also set the <xref linkend="listen-rdma-addresses"> variable for your server to enable <acronym>RDMA</acronym> connections via <literal>rsocket</literal>.
562+
</para>
563+
</listitem>
564+
</varlistentry>
565+
556566
<varlistentry>
557567
<term><option>-s <replaceable class="parameter">interval</replaceable></option></term>
558568
<term><option>--status-interval=<replaceable class="parameter">interval</replaceable></option></term>

‎doc/src/sgml/ref/pgbench.sgml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -732,6 +732,16 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
732732
</listitem>
733733
</varlistentry>
734734

735+
<varlistentry>
736+
<term><option>--with-rsocket</option></term>
737+
<listitem>
738+
<para>
739+
Connect to the server using <literal>rsocket</literal> API.
740+
You must also set the <xref linkend="listen-rdma-addresses"> variable for your server to enable <acronym>RDMA</acronym> connections via <literal>rsocket</literal>.
741+
</para>
742+
</listitem>
743+
</varlistentry>
744+
735745
<varlistentry>
736746
<term><option>-U</option> <replaceable>login</></term>
737747
<term><option>--username=</option><replaceable>login</></term>

‎doc/src/sgml/runtime.sgml

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2515,6 +2515,170 @@ ssh -L 63333:db.foo.com:5432 joe@shell.foo.com
25152515
</para>
25162516
</tip>
25172517

2518+
</sect1>
2519+
2520+
<sect1 id="rdma-connections">
2521+
<title>RDMA Connections</title>
2522+
2523+
<para><productname>&productname;</productname> provides support for client/server connections that use remote direct memory access (<acronym>RDMA</acronym>) technology. You must have an <acronym>RDMA</acronym> implementation set up on both client and server systems.</para>
2524+
<para>With <acronym>RDMA</acronym>, data can be sent directly into the memory of the remote system, bypassing the operating system kernel. As a result, this reduces the CPU load, ensures low network latency in distributed systems, and yields better performance.
2525+
</para>
2526+
2527+
<sect2 id="rdma-setup">
2528+
<title>Enabling <productname>&productname;</productname> Client/Server <acronym>RDMA</acronym> Connections</title>
2529+
2530+
<para>For client/server <acronym>RDMA</acronym> connections, <productname>&productname;</productname> uses <application>libpq</application> with <literal>rsocket</literal> API.
2531+
To enable <acronym>RDMA</acronym> connections for your <productname>&productname;</productname> database via <literal>rsocket</literal>, you must configure both client and server systems, as follows:
2532+
</para>
2533+
2534+
<orderedlist>
2535+
<listitem>
2536+
<para>On the server side, add the <xref linkend="listen-rdma-addresses"> GUC variable to the <filename>postgresql.conf</filename> configuration file to specify TCP/IP address(es) on which the server is to listen for new <acronym>RDMA</acronym> connections via <literal>rsocket</literal> from client applications. For example:
2537+
<programlisting>
2538+
listen_rdma_addresses = '<replaceable>hostname1</replaceable>, <replaceable>hostname2</replaceable>'
2539+
</programlisting>
2540+
You can specify a comma-separated list of host names and/or numeric IP addresses. If set to <literal>*</>, this variable will enable <acronym>RDMA</acronym> connections via <literal>rsocket</literal> to all the available IP interfaces.
2541+
</para>
2542+
</listitem>
2543+
2544+
<listitem>
2545+
<para>
2546+
On the client side, modify the <application>libpq</application> connection parameters to use <literal>rsocket</literal> API. This can be done in one of the following ways:
2547+
</para>
2548+
<itemizedlist>
2549+
<listitem>
2550+
<para>Add the following <literal>rsocket</literal> settings to the <application>libpq</application> <link linkend="libpq-pgservice">connection service file</link> <filename>pg_service.conf</filename>:
2551+
<programlisting>
2552+
# rsocket configuration
2553+
[rsocket]
2554+
host=<replaceable>hostname</>
2555+
port=5433
2556+
user=<replaceable>username</>
2557+
with_rsocket=true
2558+
</programlisting>
2559+
When the client is connecting to the server via <application>libpq</application>, the name of the service provided in square brackets in the <filename>pg_service.conf</filename> file must be specified in the <link linkend="LIBPQ-PARAMKEYWORDS"><option>service</option></link> parameter keyword, or in the corresponding <link linkend="libpq-envars"><envar>PGSERVICE</envar></link> environment variable. This approach enables you to dynamically control client/server connection type.
2560+
</para>
2561+
</listitem>
2562+
2563+
<listitem>
2564+
<para>Alternatively, you can set the <envar>WITH_RSOCKET</envar> environment variable:
2565+
<programlisting>
2566+
export WITH_RSOCKET=true
2567+
</programlisting>
2568+
In this case, all the client/server connections will use <literal>rsocket</literal> API.
2569+
</para>
2570+
</listitem>
2571+
</itemizedlist>
2572+
</listitem>
2573+
</orderedlist>
2574+
2575+
</sect2>
2576+
2577+
<sect2>
2578+
<title>Using <acronym>RDMA</acronym> with <application>pg_dump</application></title>
2579+
<para>To connect <application>pg_dump</application> to the server over <acronym>RDMA</acronym> via <literal>rsocket</literal>:</para>
2580+
<orderedlist>
2581+
<listitem>
2582+
<para>Set up the server as described in <xref linkend="rdma-setup">.
2583+
</para>
2584+
</listitem>
2585+
<listitem>
2586+
<para>Set the <envar>WITH_RSOCKET</envar> environment variable:
2587+
<programlisting>
2588+
export WITH_RSOCKET=true
2589+
</programlisting>
2590+
</para>
2591+
</listitem>
2592+
</orderedlist>
2593+
<para>Once the setup is complete, launch <application>pg_dump</application> as usual. For example:
2594+
</para>
2595+
<programlisting>
2596+
pg_dump <replaceable>mydb</> -h <replaceable>hostname</> > db.sql
2597+
</programlisting>
2598+
2599+
</sect2>
2600+
2601+
<sect2>
2602+
<title>Using <acronym>RDMA</acronym> for Master-Slave Replication</title>
2603+
<para>To enable master-slave replication over <acronym>RDMA</acronym> connections via <literal>rsocket</literal>, you need to configure master and slave nodes as described below.</para>
2604+
2605+
<para><emphasis role="strong">To set up the master node for replication over <acronym>RDMA</acronym> connections via <literal>rsocket</literal>:</emphasis>
2606+
</para>
2607+
<orderedlist>
2608+
<listitem>
2609+
<para>Edit the <filename>pg_hba.conf</filename> file to allow client connections and replication at the specified IP addresses. For example:
2610+
<programlisting>
2611+
host all postgres 172.0.3.0/24 md5
2612+
host replication postgres 172.0.3.0/24 md5
2613+
</programlisting>
2614+
</para>
2615+
</listitem>
2616+
<listitem>
2617+
<para>
2618+
Edit the <filename>postgresql.conf</filename> file:
2619+
<programlisting>
2620+
listen_rdma_addresses = '172.0.3.21'
2621+
wal_level = hot_standby
2622+
hot_standby = on
2623+
max_wal_senders = 1
2624+
</programlisting>
2625+
The <varname>listen_rdma_addresses</varname> specifies the TCP/IP address(es) on which the server is to listen for new <acronym>RDMA</acronym> connections via <literal>rsocket</literal>.
2626+
</para>
2627+
</listitem>
2628+
<listitem>
2629+
<para>Restart the master node.
2630+
</para>
2631+
</listitem>
2632+
</orderedlist>
2633+
2634+
<tip>
2635+
<para>If you set <varname>log_connections</varname> and <varname>log_disconnections</varname> GUC variables, the log file will include detailed information on each client connection and disconnection, respectively. For example:
2636+
<programlisting>
2637+
LOG: connection received: host=172.0.3.22 port=37709 with_rsocket=true
2638+
LOG: disconnection: session time: 0:00:00.622 user=postgres database= host=172.0.3.22 port=37709 with_rsocket=true
2639+
</programlisting>
2640+
</para>
2641+
</tip>
2642+
2643+
<para><emphasis role="strong">To set up the slave node:</emphasis>
2644+
</para>
2645+
<orderedlist>
2646+
<listitem>
2647+
<para>Set the <envar>WITH_RSOCKET<envar> environment variable:
2648+
<programlisting>
2649+
export WITH_RSOCKET=true
2650+
</programlisting>
2651+
</para>
2652+
</listitem>
2653+
<listitem>
2654+
<para>Copy the data from the master node using <application>pg_basebackup</application>:
2655+
<programlisting>
2656+
pg_basebackup -D <replaceable>datadir</> -x -R -h 172.0.3.21 -U postgres
2657+
</programlisting>
2658+
All the data appears on the slave node under the specified <replaceable>datadir</> directory.
2659+
</para>
2660+
</listitem>
2661+
<listitem>
2662+
<para>Make sure the <replaceable>datadir</>/recovery.conf contains the <literal>with_rsocket</literal> parameter.
2663+
<programlisting>
2664+
standby_mode = 'on'
2665+
primary_conninfo = 'user=postgres host=172.0.3.21 port=5432 with_rsocket=true'
2666+
</programlisting>
2667+
</para>
2668+
</listitem>
2669+
<listitem>
2670+
<para>In the <filename>postgresql.conf</filename> file, clear the <varname>listen_rdma_addresses</varname> parameter:
2671+
<programlisting>
2672+
listen_rdma_addresses = ''
2673+
</programlisting>
2674+
</para>
2675+
</listitem>
2676+
</orderedlist>
2677+
2678+
<para>Once the setup is complete, start the slave node. The streaming replication is now performed over the <acronym>RDMA</acronym> connections using <literal>rsocket</literal> API.</para>
2679+
2680+
</sect2>
2681+
25182682
</sect1>
25192683

25202684
<sect1 id="event-log-registration">

0 commit comments

Comments
 (0)