2 * contrib/pg_standby/pg_standby.c
7 * Production-ready example of how to create a Warm Standby
8 * database server using continuous archiving as a
9 * replication mechanism
11 * We separate the parameters for archive and nextWALfile
12 * so that we can check the archive exists, even if the
13 * WAL file doesn't (yet).
15 * This program will be executed once in full for each file
16 * requested by the warm standby server.
18 * It is designed to cater to a variety of needs, as well
19 * providing a customizable section.
21 * Original author: Simon Riggs simon@2ndquadrant.com
22 * Current maintainer: Simon Riggs
24 #include "postgres_fe.h"
33 #include "pg_getopt.h"
37 /* Options and defaults */
38 int sleeptime = 5; /* amount of time to sleep between file checks */
39 int waittime = -1; /* how long we have been waiting, -1 no wait
41 int maxwaittime = 0; /* how long are we prepared to wait for? */
42 int keepfiles = 0; /* number of WAL files to keep, 0 keep all */
43 int maxretries = 3; /* number of retries on restore command */
44 bool debug = false; /* are we debugging? */
45 bool need_cleanup = false; /* do we need to remove files from
49 static volatile sig_atomic_t signaled = false;
52 char *archiveLocation; /* where to find the archive? */
53 char *triggerPath; /* where to find the trigger file? */
54 char *xlogFilePath; /* where we are going to restore to */
55 char *nextWALFileName; /* the file we need to get from archive */
56 char *restartWALFileName; /* the file from which we can restart restore */
57 char *priorWALFileName; /* the file we need to get from archive */
58 char WALFilePath[MAXPGPATH]; /* the file path including archive */
59 char restoreCommand[MAXPGPATH]; /* run this to restore */
60 char exclusiveCleanupFileName[MAXPGPATH]; /* the file we need to
64 * Two types of failover are supported (smart and fast failover).
66 * The content of the trigger file determines the type of failover. If the
67 * trigger file contains the word "smart" (or the file is empty), smart
68 * failover is chosen: pg_standby acts as cp or ln command itself, on
69 * successful completion all the available WAL records will be applied
70 * resulting in zero data loss. But, it might take a long time to finish
71 * recovery if there's a lot of unapplied WAL.
73 * On the other hand, if the trigger file contains the word "fast", the
74 * recovery is finished immediately even if unapplied WAL files remain. Any
75 * transactions in the unapplied WAL files are lost.
77 * An empty trigger file performs smart failover. SIGUSR or SIGINT triggers
78 * fast failover. A timeout causes fast failover (smart failover would have
79 * the same effect, since if the timeout is reached there is no unapplied WAL).
82 #define SmartFailover 1
83 #define FastFailover 2
85 static int Failover = NoFailover;
87 #define RESTORE_COMMAND_COPY 0
88 #define RESTORE_COMMAND_LINK 1
89 int restoreCommandType;
92 #define XLOG_HISTORY 1
93 #define XLOG_BACKUP_LABEL 2
96 #define SET_RESTORE_COMMAND(cmd, arg1, arg2) \
97 snprintf(restoreCommand, MAXPGPATH, cmd " \"%s\" \"%s\"", arg1, arg2)
101 /* =====================================================================
103 * Customizable section
105 * =====================================================================
107 * Currently, this section assumes that the Archive is a locally
108 * accessible directory. If you want to make other assumptions,
109 * such as using a vendor-specific archive and access API, these
110 * routines are the ones you'll need to change. You're
111 * encouraged to submit any changes to pgsql-hackers@postgresql.org
112 * or personally to the current maintainer. Those changes may be
113 * folded in to later versions of this program.
116 #define XLOG_DATA_FNAME_LEN 24
117 /* Reworked from access/xlog_internal.h */
118 #define XLogFileName(fname, tli, log, seg) \
119 snprintf(fname, XLOG_DATA_FNAME_LEN + 1, "%08X%08X%08X", tli, log, seg)
122 * Initialize allows customized commands into the warm standby program.
124 * As an example, and probably the common case, we use either
125 * cp/ln commands on *nix, or copy/move command on Windows.
128 CustomizableInitialize(void)
131 snprintf(WALFilePath, MAXPGPATH, "%s\\%s", archiveLocation, nextWALFileName);
132 switch (restoreCommandType)
134 case RESTORE_COMMAND_LINK:
135 SET_RESTORE_COMMAND("mklink", WALFilePath, xlogFilePath);
137 case RESTORE_COMMAND_COPY:
139 SET_RESTORE_COMMAND("copy", WALFilePath, xlogFilePath);
143 snprintf(WALFilePath, MAXPGPATH, "%s/%s", archiveLocation, nextWALFileName);
144 switch (restoreCommandType)
146 case RESTORE_COMMAND_LINK:
147 #if HAVE_WORKING_LINK
148 SET_RESTORE_COMMAND("ln -s -f", WALFilePath, xlogFilePath);
151 case RESTORE_COMMAND_COPY:
153 SET_RESTORE_COMMAND("cp", WALFilePath, xlogFilePath);
159 * This code assumes that archiveLocation is a directory You may wish to
160 * add code to check for tape libraries, etc.. So, since it is a
161 * directory, we use stat to test if it's accessible
163 if (stat(archiveLocation, &stat_buf) != 0)
165 fprintf(stderr, "%s: archive location \"%s\" does not exist\n", progname, archiveLocation);
172 * CustomizableNextWALFileReady()
174 * Is the requested file ready yet?
177 CustomizableNextWALFileReady()
179 if (stat(WALFilePath, &stat_buf) == 0)
182 * If it's a backup file, return immediately. If it's a regular file
183 * return only if it's the right size already.
185 if (strlen(nextWALFileName) > 24 &&
186 strspn(nextWALFileName, "0123456789ABCDEF") == 24 &&
187 strcmp(nextWALFileName + strlen(nextWALFileName) - strlen(".backup"),
190 nextWALFileType = XLOG_BACKUP_LABEL;
193 else if (stat_buf.st_size == XLOG_SEG_SIZE)
198 * Windows 'cp' sets the final file size before the copy is
199 * complete, and not yet ready to be opened by pg_standby. So we
200 * wait for sleeptime secs before attempting to restore. If that
201 * is not enough, we will rely on the retry/holdoff mechanism.
202 * GNUWin32's cp does not have this problem.
204 pg_usleep(sleeptime * 1000000L);
206 nextWALFileType = XLOG_DATA;
211 * If still too small, wait until it is the correct size
213 if (stat_buf.st_size > XLOG_SEG_SIZE)
217 fprintf(stderr, "file size greater than expected\n");
227 #define MaxSegmentsPerLogFile ( 0xFFFFFFFF / XLOG_SEG_SIZE )
230 CustomizableCleanupPriorWALFiles(void)
233 * Work out name of prior file from current filename
235 if (nextWALFileType == XLOG_DATA)
242 * Assume it's OK to keep failing. The failure situation may change
243 * over time, so we'd rather keep going on the main processing than
244 * fail because we couldn't clean up yet.
246 if ((xldir = opendir(archiveLocation)) != NULL)
248 while ((xlde = readdir(xldir)) != NULL)
251 * We ignore the timeline part of the XLOG segment identifiers
252 * in deciding whether a segment is still needed. This
253 * ensures that we won't prematurely remove a segment from a
254 * parent timeline. We could probably be a little more
255 * proactive about removing segments of non-parent timelines,
256 * but that would be a whole lot more complicated.
258 * We use the alphanumeric sorting property of the filenames
259 * to decide which ones are earlier than the
260 * exclusiveCleanupFileName file. Note that this means files
261 * are not removed in the order they were originally written,
262 * in case this worries you.
264 if (strlen(xlde->d_name) == XLOG_DATA_FNAME_LEN &&
265 strspn(xlde->d_name, "0123456789ABCDEF") == XLOG_DATA_FNAME_LEN &&
266 strcmp(xlde->d_name + 8, exclusiveCleanupFileName + 8) < 0)
269 snprintf(WALFilePath, MAXPGPATH, "%s\\%s", archiveLocation, xlde->d_name);
271 snprintf(WALFilePath, MAXPGPATH, "%s/%s", archiveLocation, xlde->d_name);
275 fprintf(stderr, "\nremoving file \"%s\"", WALFilePath);
277 rc = unlink(WALFilePath);
280 fprintf(stderr, "\n%s: ERROR: could not remove file \"%s\": %s\n",
281 progname, WALFilePath, strerror(errno));
287 fprintf(stderr, "\n");
290 fprintf(stderr, "%s: could not open archive location \"%s\": %s\n",
291 progname, archiveLocation, strerror(errno));
298 /* =====================================================================
299 * End of Customizable section
300 * =====================================================================
304 * SetWALFileNameForCleanup()
306 * Set the earliest WAL filename that we want to keep on the archive
307 * and decide whether we need_cleanup
310 SetWALFileNameForCleanup(void)
317 bool cleanup = false;
319 if (restartWALFileName)
322 * Don't do cleanup if the restartWALFileName provided is later than
323 * the xlog file requested. This is an error and we must not remove
324 * these files from archive. This shouldn't happen, but better safe
327 if (strcmp(restartWALFileName, nextWALFileName) > 0)
330 strlcpy(exclusiveCleanupFileName, restartWALFileName, sizeof(exclusiveCleanupFileName));
336 sscanf(nextWALFileName, "%08X%08X%08X", &tli, &log, &seg);
337 if (tli > 0 && seg > 0)
339 log_diff = keepfiles / MaxSegmentsPerLogFile;
340 seg_diff = keepfiles % MaxSegmentsPerLogFile;
344 seg = MaxSegmentsPerLogFile - (seg_diff - seg);
362 XLogFileName(exclusiveCleanupFileName, tli, log, seg);
368 * CheckForExternalTrigger()
370 * Is there a trigger file? Sets global 'Failover' variable to indicate
371 * what kind of a trigger file it was. A "fast" trigger file is turned
372 * into a "smart" file as a side-effect.
375 CheckForExternalTrigger(void)
382 * Look for a trigger file, if that option has been selected
384 * We use stat() here because triggerPath is always a file rather than
385 * potentially being in an archive
387 if (!triggerPath || stat(triggerPath, &stat_buf) != 0)
391 * An empty trigger file performs smart failover. There's a little race
392 * condition here: if the writer of the trigger file has just created the
393 * file, but not yet written anything to it, we'll treat that as smart
394 * shutdown even if the other process was just about to write "fast" to
395 * it. But that's fine: we'll restore one more WAL file, and when we're
396 * invoked next time, we'll see the word "fast" and fail over immediately.
398 if (stat_buf.st_size == 0)
400 Failover = SmartFailover;
401 fprintf(stderr, "trigger file found: smart failover\n");
406 if ((fd = open(triggerPath, O_RDWR, 0)) < 0)
408 fprintf(stderr, "WARNING: could not open \"%s\": %s\n",
409 triggerPath, strerror(errno));
414 if ((len = read(fd, buf, sizeof(buf))) < 0)
416 fprintf(stderr, "WARNING: could not read \"%s\": %s\n",
417 triggerPath, strerror(errno));
424 if (strncmp(buf, "smart", 5) == 0)
426 Failover = SmartFailover;
427 fprintf(stderr, "trigger file found: smart failover\n");
433 if (strncmp(buf, "fast", 4) == 0)
435 Failover = FastFailover;
437 fprintf(stderr, "trigger file found: fast failover\n");
441 * Turn it into a "smart" trigger by truncating the file. Otherwise if
442 * the server asks us again to restore a segment that was restored
443 * already, we would return "not found" and upset the server.
445 if (ftruncate(fd, 0) < 0)
447 fprintf(stderr, "WARNING: could not read \"%s\": %s\n",
448 triggerPath, strerror(errno));
457 fprintf(stderr, "WARNING: invalid content in \"%s\"\n", triggerPath);
463 * RestoreWALFileForRecovery()
465 * Perform the action required to restore the file from archive
468 RestoreWALFileForRecovery(void)
475 fprintf(stderr, "running restore: ");
479 while (numretries <= maxretries)
481 rc = system(restoreCommand);
486 fprintf(stderr, "OK\n");
491 pg_usleep(numretries++ * sleeptime * 1000000L);
495 * Allow caller to add additional info
498 fprintf(stderr, "not restored\n");
505 printf("%s allows PostgreSQL warm standby servers to be configured.\n\n", progname);
507 printf(" %s [OPTION]... ARCHIVELOCATION NEXTWALFILE XLOGFILEPATH [RESTARTWALFILE]\n", progname);
508 printf("\nOptions:\n");
509 printf(" -c copy file from archive (default)\n");
510 printf(" -d generate lots of debugging output (testing only)\n");
511 printf(" -k NUMFILESTOKEEP if RESTARTWALFILE is not used, remove files prior to limit\n"
513 printf(" -l does nothing; use of link is now deprecated\n");
514 printf(" -r MAXRETRIES max number of times to retry, with progressive wait\n"
516 printf(" -s SLEEPTIME seconds to wait between file checks (min=1, max=60,\n"
518 printf(" -t TRIGGERFILE trigger file to initiate failover (no default)\n");
519 printf(" -V, --version output version information, then exit\n");
520 printf(" -w MAXWAITTIME max seconds to wait for a file (0=no limit) (default=0)\n");
521 printf(" -?, --help show this help, then exit\n");
523 "Main intended use as restore_command in recovery.conf:\n"
524 " restore_command = 'pg_standby [OPTION]... ARCHIVELOCATION %%f %%p %%r'\n"
526 " restore_command = 'pg_standby /mnt/server/archiverdir %%f %%p %%r'\n");
527 printf("\nReport bugs to <pgsql-bugs@postgresql.org>.\n");
537 /* We don't want SIGQUIT to core dump */
539 sigquit_handler(int sig)
541 pqsignal(SIGINT, SIG_DFL);
542 kill(getpid(), SIGINT);
546 /*------------ MAIN ----------------------------------------*/
548 main(int argc, char **argv)
552 progname = get_progname(argv[0]);
556 if (strcmp(argv[1], "--help") == 0 || strcmp(argv[1], "-?") == 0)
561 if (strcmp(argv[1], "--version") == 0 || strcmp(argv[1], "-V") == 0)
563 puts("pg_standby (PostgreSQL) " PG_VERSION);
571 * You can send SIGUSR1 to trigger failover.
573 * Postmaster uses SIGQUIT to request immediate shutdown. The default
574 * action is to core dump, but we don't want that, so trap it and commit
575 * suicide without core dump.
577 * We used to use SIGINT and SIGQUIT to trigger failover, but that turned
578 * out to be a bad idea because postmaster uses SIGQUIT to request
579 * immediate shutdown. We still trap SIGINT, but that may change in a
582 * There's no way to trigger failover via signal on Windows.
584 (void) pqsignal(SIGUSR1, sighandler);
585 (void) pqsignal(SIGINT, sighandler); /* deprecated, use SIGUSR1 */
586 (void) pqsignal(SIGQUIT, sigquit_handler);
589 while ((c = getopt(argc, argv, "cdk:lr:s:t:w:")) != -1)
593 case 'c': /* Use copy */
594 restoreCommandType = RESTORE_COMMAND_COPY;
596 case 'd': /* Debug mode */
599 case 'k': /* keepfiles */
600 keepfiles = atoi(optarg);
603 fprintf(stderr, "%s: -k keepfiles must be >= 0\n", progname);
607 case 'l': /* Use link */
610 * Link feature disabled, possibly permanently. Linking causes
611 * a problem after recovery ends that is not currently
612 * resolved by PostgreSQL. 25 Jun 2009
615 restoreCommandType = RESTORE_COMMAND_LINK;
618 case 'r': /* Retries */
619 maxretries = atoi(optarg);
622 fprintf(stderr, "%s: -r maxretries must be >= 0\n", progname);
626 case 's': /* Sleep time */
627 sleeptime = atoi(optarg);
628 if (sleeptime <= 0 || sleeptime > 60)
630 fprintf(stderr, "%s: -s sleeptime incorrectly set\n", progname);
634 case 't': /* Trigger file */
635 triggerPath = strdup(optarg);
637 case 'w': /* Max wait time */
638 maxwaittime = atoi(optarg);
641 fprintf(stderr, "%s: -w maxwaittime incorrectly set\n", progname);
646 fprintf(stderr, "Try \"%s --help\" for more information.\n", progname);
653 * Parameter checking - after checking to see if trigger file present
657 fprintf(stderr, "%s: not enough command-line arguments\n", progname);
662 * We will go to the archiveLocation to get nextWALFileName.
663 * nextWALFileName may not exist yet, which would not be an error, so we
664 * separate the archiveLocation and nextWALFileName so we can check
665 * separately whether archiveLocation exists, if not that is an error
669 archiveLocation = argv[optind];
674 fprintf(stderr, "%s: must specify archive location\n", progname);
675 fprintf(stderr, "Try \"%s --help\" for more information.\n", progname);
681 nextWALFileName = argv[optind];
686 fprintf(stderr, "%s: must specify WAL file name as second non-option argument (use \"%%f\")\n", progname);
687 fprintf(stderr, "Try \"%s --help\" for more information.\n", progname);
693 xlogFilePath = argv[optind];
698 fprintf(stderr, "%s: must specify xlog destination as third non-option argument (use \"%%p\")\n", progname);
699 fprintf(stderr, "Try \"%s --help\" for more information.\n", progname);
705 restartWALFileName = argv[optind];
709 CustomizableInitialize();
711 need_cleanup = SetWALFileNameForCleanup();
715 fprintf(stderr, "Trigger file: %s\n", triggerPath ? triggerPath : "<not set>");
716 fprintf(stderr, "Waiting for WAL file: %s\n", nextWALFileName);
717 fprintf(stderr, "WAL file path: %s\n", WALFilePath);
718 fprintf(stderr, "Restoring to: %s\n", xlogFilePath);
719 fprintf(stderr, "Sleep interval: %d second%s\n",
720 sleeptime, (sleeptime > 1 ? "s" : " "));
721 fprintf(stderr, "Max wait interval: %d %s\n",
722 maxwaittime, (maxwaittime > 0 ? "seconds" : "forever"));
723 fprintf(stderr, "Command for restore: %s\n", restoreCommand);
724 fprintf(stderr, "Keep archive history: ");
726 fprintf(stderr, "%s and later\n", exclusiveCleanupFileName);
728 fprintf(stderr, "no cleanup required\n");
733 * Check for initial history file: always the first file to be requested
734 * It's OK if the file isn't there - all other files need to wait
736 if (strlen(nextWALFileName) > 8 &&
737 strspn(nextWALFileName, "0123456789ABCDEF") == 8 &&
738 strcmp(nextWALFileName + strlen(nextWALFileName) - strlen(".history"),
741 nextWALFileType = XLOG_HISTORY;
742 if (RestoreWALFileForRecovery())
748 fprintf(stderr, "history file not found\n");
760 /* Check for trigger file or signal first */
761 CheckForExternalTrigger();
765 Failover = FastFailover;
768 fprintf(stderr, "signaled to exit: fast failover\n");
775 * Check for fast failover immediately, before checking if the
776 * requested WAL file is available
778 if (Failover == FastFailover)
781 if (CustomizableNextWALFileReady())
784 * Once we have restored this file successfully we can remove some
785 * prior WAL files. If this restore fails we musn't remove any
786 * file because some of them will be requested again immediately
787 * after the failed restore, or when we restart recovery.
789 if (RestoreWALFileForRecovery())
792 CustomizableCleanupPriorWALFiles();
798 /* Something went wrong in copying the file */
803 /* Check for smart failover if the next WAL file was not available */
804 if (Failover == SmartFailover)
808 pg_usleep(sleeptime * 1000000L);
810 waittime += sleeptime;
811 if (waittime >= maxwaittime && maxwaittime > 0)
813 Failover = FastFailover;
816 fprintf(stderr, "Timed out after %d seconds: fast failover\n",
823 fprintf(stderr, "WAL file not present yet.");
825 fprintf(stderr, " Checking for trigger file...");
826 fprintf(stderr, "\n");