1<chapter id="quickstart" xreflabel="Quick-start guide"> 2 <title>Quick-start guide</title> 3 4 <indexterm> 5 <primary>quickstart</primary> 6 </indexterm> 7 8 <para> 9 This section gives a quick introduction to &repmgr;, including setting up a 10 sample &repmgr; installation and a basic replication cluster. 11 </para> 12 <para> 13 These instructions for demonstration purposes and are not suitable for a production 14 install, as issues such as account security considerations, and system administration 15 best practices are omitted. 16 </para> 17 <note> 18 <simpara> 19 To upgrade an existing &repmgr; 3.x installation, see section 20 <xref linkend="upgrading-from-repmgr-3"/>. 21 </simpara> 22 </note> 23 24 <sect1 id="quickstart-prerequisites"> 25 <title>Prerequisites for setting up a basic replication cluster with &repmgr;</title> 26 <para> 27 The following section will describe how to set up a basic replication cluster 28 with a primary and a standby server using the <application>repmgr</application> 29 command line tool. 30 </para> 31 <para> 32 We'll assume the primary is called <literal>node1</literal> with IP address 33 <literal>192.168.1.11</literal>, and the standby is called <literal>node2</literal> 34 with IP address <literal>192.168.1.12</literal> 35 </para> 36 <para> 37 Following software must be installed on both servers: 38 <itemizedlist spacing="compact" mark="bullet"> 39 <listitem> 40 <simpara><application>PostgreSQL</application></simpara> 41 </listitem> 42 <listitem> 43 <simpara> 44 <application>repmgr</application> (matching the installed 45 <application>PostgreSQL</application> major version) 46 </simpara> 47 </listitem> 48 </itemizedlist> 49 </para> 50 51 <para> 52 At network level, connections between the PostgreSQL port (default: <literal>5432</literal>) 53 must be possible in both directions. 54 </para> 55 <para> 56 If you want <application>repmgr</application> to copy configuration files which are 57 located outside the PostgreSQL data directory, and/or to test 58 <command><link linkend="repmgr-standby-switchover">switchover</link></command> 59 functionality, you will also need passwordless SSH connections between both servers, and 60 <application>rsync</application> should be installed. 61 </para> 62 <tip> 63 <simpara> 64 For testing <application>repmgr</application>, it's possible to use multiple PostgreSQL 65 instances running on different ports on the same computer, with 66 passwordless SSH access to <filename>localhost</filename> enabled. 67 </simpara> 68 </tip> 69 </sect1> 70 71 <sect1 id="quickstart-postgresql-configuration" xreflabel="PostgreSQL configuration"> 72 <title>PostgreSQL configuration</title> 73 <para> 74 On the primary server, a PostgreSQL instance must be initialised and running. 75 The following replication settings may need to be adjusted: 76 </para> 77 <programlisting> 78 79 # Enable replication connections; set this value to at least one more 80 # than the number of standbys which will connect to this server 81 # (note that repmgr will execute "pg_basebackup" in WAL streaming mode, 82 # which requires two free WAL senders). 83 # 84 # See: https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-WAL-SENDERS 85 86 max_wal_senders = 10 87 88 # If using replication slots, set this value to at least one more 89 # than the number of standbys which will connect to this server. 90 # Note that repmgr will only make use of replication slots if 91 # "use_replication_slots" is set to "true" in "repmgr.conf". 92 # (If you are not intending to use replication slots, this value 93 # can be set to "0"). 94 # 95 # See: https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-REPLICATION-SLOTS 96 97 max_replication_slots = 10 98 99 # Ensure WAL files contain enough information to enable read-only queries 100 # on the standby. 101 # 102 # PostgreSQL 9.5 and earlier: one of 'hot_standby' or 'logical' 103 # PostgreSQL 9.6 and later: one of 'replica' or 'logical' 104 # ('hot_standby' will still be accepted as an alias for 'replica') 105 # 106 # See: https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-WAL-LEVEL 107 108 wal_level = 'hot_standby' 109 110 # Enable read-only queries on a standby 111 # (Note: this will be ignored on a primary but we recommend including 112 # it anyway, in case the primary later becomes a standby) 113 # 114 # See: https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-HOT-STANDBY 115 116 hot_standby = on 117 118 # Enable WAL file archiving 119 # 120 # See: https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-MODE 121 122 archive_mode = on 123 124 # Set archive command to a dummy command; this can later be changed without 125 # needing to restart the PostgreSQL instance. 126 # 127 # See: https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-COMMAND 128 129 archive_command = '/bin/true' 130 </programlisting> 131 <tip> 132 <simpara> 133 Rather than editing these settings in the default <filename>postgresql.conf</filename> 134 file, create a separate file such as <filename>postgresql.replication.conf</filename> and 135 include it from the end of the main configuration file with: 136 <command>include 'postgresql.replication.conf'</command>. 137 </simpara> 138 </tip> 139 <para> 140 Additionally, if you are intending to use <application>pg_rewind</application>, 141 and the cluster was not initialised using data checksums, you may want to consider enabling 142 <varname>wal_log_hints</varname>; for more details see <xref linkend="repmgr-node-rejoin-pg-rewind"/>. 143 </para> 144 <para> 145 See also the <link linkend="configuration-postgresql">PostgreSQL configuration</link> section in the 146 <link linkend="configuration">repmgr configuration guide</link>. 147 </para> 148 </sect1> 149 150 <sect1 id="quickstart-repmgr-user-database"> 151 <title>Create the repmgr user and database</title> 152 <para> 153 Create a dedicated PostgreSQL superuser account and a database for 154 the &repmgr; metadata, e.g. 155 </para> 156 <programlisting> 157 createuser -s repmgr 158 createdb repmgr -O repmgr 159 </programlisting> 160 161 <para> 162 For the examples in this document, the name <literal>repmgr</literal> will be 163 used for both user and database, but any names can be used. 164 </para> 165 <note> 166 <para> 167 For the sake of simplicity, the <literal>repmgr</literal> user is created 168 as a superuser. If desired, it's possible to create the <literal>repmgr</literal> 169 user as a normal user. However for certain operations superuser permissions 170 are required; in this case the command line option <command>--superuser</command> 171 can be provided to specify a superuser. 172 </para> 173 <para> 174 It's also assumed that the <literal>repmgr</literal> user will be used to make the 175 replication connection from the standby to the primary; again this can be 176 overridden by specifying a separate replication user when registering each node. 177 </para> 178 </note> 179 180 <tip> 181 <para> 182 &repmgr; will install the <literal>repmgr</literal> extension, which creates a 183 <literal>repmgr</literal> schema containing the &repmgr;'s metadata tables as 184 well as other functions and views. We also recommend that you set the 185 <literal>repmgr</literal> user's search path to include this schema name, e.g. 186 <programlisting> 187 ALTER USER repmgr SET search_path TO repmgr, "$user", public;</programlisting> 188 </para> 189 </tip> 190 191 </sect1> 192 193 <sect1 id="quickstart-authentication"> 194 <title>Configuring authentication in pg_hba.conf</title> 195 <para> 196 Ensure the <literal>repmgr</literal> user has appropriate permissions in <filename>pg_hba.conf</filename> and 197 can connect in replication mode; <filename>pg_hba.conf</filename> should contain entries 198 similar to the following: 199 </para> 200 <programlisting> 201 local replication repmgr trust 202 host replication repmgr 127.0.0.1/32 trust 203 host replication repmgr 192.168.1.0/24 trust 204 205 local repmgr repmgr trust 206 host repmgr repmgr 127.0.0.1/32 trust 207 host repmgr repmgr 192.168.1.0/24 trust 208 </programlisting> 209 <para> 210 Note that these are simple settings for testing purposes. 211 Adjust according to your network environment and authentication requirements. 212 </para> 213 </sect1> 214 215 <sect1 id="quickstart-standby-preparation"> 216 <title>Preparing the standby</title> 217 <para> 218 On the standby, do <emphasis>not</emphasis> create a PostgreSQL instance (i.e. 219 do not execute <application>initdb</application> or any database creation 220 scripts provided by packages), but do ensure the destination 221 data directory (and any other directories which you want PostgreSQL to use) 222 exist and are owned by the <literal>postgres</literal> system user. Permissions 223 must be set to <literal>0700</literal> (<literal>drwx------</literal>). 224 </para> 225 <tip> 226 <simpara> 227 &repmgr; will place a copy of the primary's database files in this directory. 228 It will however refuse to run if a PostgreSQL instance has already been 229 created there. 230 </simpara> 231 </tip> 232 <para> 233 Check the primary database is reachable from the standby using <application>psql</application>: 234 </para> 235 <programlisting> 236 psql 'host=node1 user=repmgr dbname=repmgr connect_timeout=2'</programlisting> 237 238 <note> 239 <para> 240 &repmgr; stores connection information as <ulink 241 url="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING">libpq 242 connection strings</ulink> throughout. This documentation refers to them as <literal>conninfo</literal> 243 strings; an alternative name is <literal>DSN</literal> (<literal>data source name</literal>). 244 We'll use these in place of the <command>-h hostname -d databasename -U username</command> syntax. 245 </para> 246 </note> 247 </sect1> 248 249 <sect1 id="quickstart-repmgr-conf"> 250 <title>repmgr configuration file</title> 251 <para> 252 Create a <filename>repmgr.conf</filename> file on the primary server. The file must 253 contain at least the following parameters: 254 </para> 255 <programlisting> 256 node_id=1 257 node_name='node1' 258 conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2' 259 data_directory='/var/lib/postgresql/data' 260 </programlisting> 261 262 <para> 263 <filename>repmgr.conf</filename> should not be stored inside the PostgreSQL data directory, 264 as it could be overwritten when setting up or reinitialising the PostgreSQL 265 server. See sections <xref linkend="configuration"/> and <xref linkend="configuration-file"/> 266 for further details about <filename>repmgr.conf</filename>. 267 </para> 268 <note> 269 <para> 270 &repmgr; only uses <option>pg_bindir</option> when it executes 271 PostgreSQL binaries directly. 272 </para> 273 <para> 274 For user-defined scripts such as <option>promote_command</option> and the 275 various <option>service_*_command</option>s, you <emphasis>must</emphasis> 276 always explicitly provide the full path to the binary or script being 277 executed, even if it is &repmgr; itself. 278 </para> 279 <para> 280 This is because these options can contain user-defined scripts in arbitrary 281 locations, so prepending <option>pg_bindir</option> may break them. 282 </para> 283 </note> 284 285 <tip> 286 <simpara> 287 For Debian-based distributions we recommend explictly setting 288 <option>pg_bindir</option> to the directory where <command>pg_ctl</command> and other binaries 289 not in the standard path are located. For PostgreSQL 9.6 this would be <filename>/usr/lib/postgresql/9.6/bin/</filename>. 290 </simpara> 291 </tip> 292 293 <tip> 294 <simpara> 295 If your distribution places the &repmgr; binaries in a location other than the 296 PostgreSQL installation directory, specify this with <option>repmgr_bindir</option> 297 to enable &repmgr; to perform operations (e.g. 298 <command><link linkend="repmgr-cluster-crosscheck">repmgr cluster crosscheck</link></command>) 299 on other nodes. 300 </simpara> 301 </tip> 302 303 <para> 304 See the file 305 <ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/master/repmgr.conf.sample">repmgr.conf.sample</ulink> 306 for details of all available configuration parameters. 307 </para> 308 309 </sect1> 310 311 312 <sect1 id="quickstart-primary-register"> 313 <title>Register the primary server</title> 314 <para> 315 To enable &repmgr; to support a replication cluster, the primary node must 316 be registered with &repmgr;. This installs the <literal>repmgr</literal> 317 extension and metadata objects, and adds a metadata record for the primary server: 318 </para> 319 320 <programlisting> 321 $ repmgr -f /etc/repmgr.conf primary register 322 INFO: connecting to primary database... 323 NOTICE: attempting to install extension "repmgr" 324 NOTICE: "repmgr" extension successfully installed 325 NOTICE: primary node record (id: 1) registered</programlisting> 326 327 <para> 328 Verify status of the cluster like this: 329 </para> 330 <programlisting> 331 $ repmgr -f /etc/repmgr.conf cluster show 332 ID | Name | Role | Status | Upstream | Connection string 333 ----+-------+---------+-----------+----------+-------------------------------------------------------- 334 1 | node1 | primary | * running | | host=node1 dbname=repmgr user=repmgr connect_timeout=2 335 </programlisting> 336 <para> 337 The record in the <literal>repmgr</literal> metadata table will look like this: 338 </para> 339 <programlisting> 340 repmgr=# SELECT * FROM repmgr.nodes; 341 -[ RECORD 1 ]----+------------------------------------------------------- 342 node_id | 1 343 upstream_node_id | 344 active | t 345 node_name | node1 346 type | primary 347 location | default 348 priority | 100 349 conninfo | host=node1 dbname=repmgr user=repmgr connect_timeout=2 350 repluser | repmgr 351 slot_name | 352 config_file | /etc/repmgr.conf</programlisting> 353 <para> 354 Each server in the replication cluster will have its own record. If &repmgrd; 355 is in use, the fields <literal>upstream_node_id</literal>, <literal>active</literal> and 356 <literal>type</literal> will be updated when the node's status or role changes. 357 </para> 358 </sect1> 359 360 <sect1 id="quickstart-standby-clone"> 361 <title>Clone the standby server</title> 362 <para> 363 Create a <filename>repmgr.conf</filename> file on the standby server. It must contain at 364 least the same parameters as the primary's <filename>repmgr.conf</filename>, but with 365 the mandatory values <literal>node</literal>, <literal>node_name</literal>, <literal>conninfo</literal> 366 (and possibly <literal>data_directory</literal>) adjusted accordingly, e.g.: 367 </para> 368 <programlisting> 369 node_id=2 370 node_name='node2' 371 conninfo='host=node2 user=repmgr dbname=repmgr connect_timeout=2' 372 data_directory='/var/lib/postgresql/data'</programlisting> 373 <para> 374 Use the <command>--dry-run</command> option to check the standby can be cloned: 375 </para> 376 <programlisting> 377 $ repmgr -h node1 -U repmgr -d repmgr -f /etc/repmgr.conf standby clone --dry-run 378 NOTICE: using provided configuration file "/etc/repmgr.conf" 379 NOTICE: destination directory "/var/lib/postgresql/data" provided 380 INFO: connecting to source node 381 NOTICE: checking for available walsenders on source node (2 required) 382 INFO: sufficient walsenders available on source node (2 required) 383 NOTICE: standby will attach to upstream node 1 384 HINT: consider using the -c/--fast-checkpoint option 385 INFO: all prerequisites for "standby clone" are met</programlisting> 386 <para> 387 If no problems are reported, the standby can then be cloned with: 388 </para> 389 <programlisting> 390 $ repmgr -h node1 -U repmgr -d repmgr -f /etc/repmgr.conf standby clone 391 392 NOTICE: using configuration file "/etc/repmgr.conf" 393 NOTICE: destination directory "/var/lib/postgresql/data" provided 394 INFO: connecting to source node 395 NOTICE: checking for available walsenders on source node (2 required) 396 INFO: sufficient walsenders available on source node (2 required) 397 INFO: creating directory "/var/lib/postgresql/data"... 398 NOTICE: starting backup (using pg_basebackup)... 399 HINT: this may take some time; consider using the -c/--fast-checkpoint option 400 INFO: executing: 401 pg_basebackup -l "repmgr base backup" -D /var/lib/postgresql/data -h node1 -U repmgr -X stream 402 NOTICE: standby clone (using pg_basebackup) complete 403 NOTICE: you can now start your PostgreSQL server 404 HINT: for example: pg_ctl -D /var/lib/postgresql/data start 405 </programlisting> 406 <para> 407 This has cloned the PostgreSQL data directory files from the primary <literal>node1</literal> 408 using PostgreSQL's <command>pg_basebackup</command> utility. A <filename>recovery.conf</filename> 409 file containing the correct parameters to start streaming from this primary server will be created 410 automatically. 411 </para> 412 <note> 413 <simpara> 414 By default, any configuration files in the primary's data directory will be 415 copied to the standby. Typically these will be <filename>postgresql.conf</filename>, 416 <filename>postgresql.auto.conf</filename>, <filename>pg_hba.conf</filename> and 417 <filename>pg_ident.conf</filename>. These may require modification before the standby 418 is started. 419 </simpara> 420 </note> 421 <para> 422 Make any adjustments to the standby's PostgreSQL configuration files now, 423 then start the server. 424 </para> 425 <para> 426 For more details on <command>repmgr standby clone</command>, see the 427 <link linkend="repmgr-standby-clone">command reference</link>. 428 A more detailed overview of cloning options is available in the 429 <link linkend="cloning-standbys">administration manual</link>. 430 </para> 431 </sect1> 432 433 <sect1 id="quickstart-verify-replication"> 434 <title>Verify replication is functioning</title> 435 <para> 436 Connect to the primary server and execute: 437 <programlisting> 438 repmgr=# SELECT * FROM pg_stat_replication; 439 -[ RECORD 1 ]----+------------------------------ 440 pid | 19111 441 usesysid | 16384 442 usename | repmgr 443 application_name | node2 444 client_addr | 192.168.1.12 445 client_hostname | 446 client_port | 50378 447 backend_start | 2017-08-28 15:14:19.851581+09 448 backend_xmin | 449 state | streaming 450 sent_location | 0/7000318 451 write_location | 0/7000318 452 flush_location | 0/7000318 453 replay_location | 0/7000318 454 sync_priority | 0 455 sync_state | async</programlisting> 456 This shows that the previously cloned standby (<literal>node2</literal> shown in the field 457 <literal>application_name</literal>) has connected to the primary from IP address 458 <literal>192.168.1.12</literal>. 459 </para> 460 <para> 461 From PostgreSQL 9.6 you can also use the view 462 <ulink url="https://www.postgresql.org/docs/current/monitoring-stats.html#PG-STAT-WAL-RECEIVER-VIEW"> 463 <literal>pg_stat_wal_receiver</literal></ulink> to check the replication status from the standby. 464 465 <programlisting> 466 repmgr=# SELECT * FROM pg_stat_wal_receiver; 467 Expanded display is on. 468 -[ RECORD 1 ]---------+-------------------------------------------------------------------------------- 469 pid | 18236 470 status | streaming 471 receive_start_lsn | 0/3000000 472 receive_start_tli | 1 473 received_lsn | 0/7000538 474 received_tli | 1 475 last_msg_send_time | 2017-08-28 15:21:26.465728+09 476 last_msg_receipt_time | 2017-08-28 15:21:26.465774+09 477 latest_end_lsn | 0/7000538 478 latest_end_time | 2017-08-28 15:20:56.418735+09 479 slot_name | 480 sender_host | node1 481 sender_port | 5432 482 conninfo | user=repmgr dbname=replication host=node1 application_name=node2 483 </programlisting> 484 Note that the <varname>conninfo</varname> value is that generated in <filename>recovery.conf</filename> 485 and will differ slightly from the primary's <varname>conninfo</varname> as set in <filename>repmgr.conf</filename> - 486 among others it will contain the connecting node's name as <varname>application_name</varname>. 487 </para> 488 </sect1> 489 490 <sect1 id="quickstart-register-standby"> 491 <title>Register the standby</title> 492 <para> 493 Register the standby server with: 494 <programlisting> 495 $ repmgr -f /etc/repmgr.conf standby register 496 NOTICE: standby node "node2" (ID: 2) successfully registered</programlisting> 497 </para> 498 <para> 499 Check the node is registered by executing <command>repmgr cluster show</command> on the standby: 500 <programlisting> 501 $ repmgr -f /etc/repmgr.conf cluster show 502 503 ID | Name | Role | Status | Upstream | Location | Priority | Timeline | Connection string 504 ----+-------+---------+-----------+----------+----------+----------+----------+-------------------------------------- 505 1 | node1 | primary | * running | | default | 100 | 1 | host=node1 dbname=repmgr user=repmgr 506 2 | node2 | standby | running | node1 | default | 100 | 1 | host=node2 dbname=repmgr user=repmgr</programlisting> 507 </para> 508 <para> 509 Both nodes are now registered with &repmgr; and the records have been copied to the standby server. 510 </para> 511 </sect1> 512 513</chapter> 514