Merge branch 'issue_146'

Author: gsmolk

doc/pgprobackup.xml

@@ -2402,6 +2402,11 @@ primary_conninfo = 'user=backup passfile=/var/lib/pgsql/.pgpass port=5432 sslmod
           password is not included.
         </para>
         </listitem>
+        <listitem>
+        <para>
+          <literal>note</literal> — text note attached to backup.
+        </para>
+        </listitem>
       </itemizedlist>
       </para>
       <para>
@@ -3377,15 +3382,28 @@ pg_probackup set-config -B <replaceable>backup_dir</replaceable> --instance <rep
       <title>set-backup</title>
       <programlisting>
 pg_probackup set-backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable>
-{--ttl=<replaceable>ttl</replaceable> | --expire-time=<replaceable>time</replaceable>} [--help]
+{--ttl=<replaceable>ttl</replaceable> | --expire-time=<replaceable>time</replaceable>}
+[--note=<replaceable>backup_note</replaceable>] [--help]
 </programlisting>
       <para>
         Sets the provided backup-specific settings into the
         <filename>backup.control</filename> configuration file, or modifies the previously
         defined values.
       </para>
+      <varlistentry>
+<term><option>--note=<replaceable>backup_note</replaceable></option></term>
+      <listitem>
       <para>
-        For all available settings, see the section
+        Sets the text note for backup copy.
+        If <replaceable>backup_note</replaceable> contain newline characters,
+        then only substring before first newline character will be saved.
+        Max size of text note is 1 KB.
+        The <replaceable>'none'</replaceable> value removes current note.
+      </para>
+      </listitem>
+      </varlistentry>
+      <para>
+        For all available pinning settings, see the section
         <link linkend="pbk-pinning-options">Pinning Options</link>.
       </para>
     </refsect3>
@@ -3445,7 +3463,7 @@ pg_probackup backup -B <replaceable>backup_dir</replaceable> -b <replaceable>bac
 [--no-validate] [--skip-block-validation]
 [-w --no-password] [-W --password]
 [--archive-timeout=<replaceable>timeout</replaceable>] [--external-dirs=<replaceable>external_directory_path</replaceable>]
-[--no-sync]
+[--no-sync] [--note=<replaceable>backup_note</replaceable>]
 [<replaceable>connection_options</replaceable>] [<replaceable>compression_options</replaceable>] [<replaceable>remote_options</replaceable>]
 [<replaceable>retention_options</replaceable>] [<replaceable>pinning_options</replaceable>] [<replaceable>logging_options</replaceable>]
 </programlisting>
@@ -3612,6 +3630,19 @@ pg_probackup backup -B <replaceable>backup_dir</replaceable> -b <replaceable>bac
       </para>
       </listitem>
       </varlistentry>
+      <varlistentry>
+<term><option>--note=<replaceable>backup_note</replaceable></option></term>
+      <listitem>
+      <para>
+        Sets the text note for backup copy.
+        If <replaceable>backup_note</replaceable> contain newline characters,
+        then only substring before first newline character will be saved.
+        Max size of text note is 1 KB.
+        The <replaceable>'none'</replaceable> value removes current note.
+      </para>
+      </listitem>
+      </varlistentry>
+
       </variablelist>
       </para>
 

src/backup.c

@@ -156,7 +156,6 @@ do_backup_instance(PGconn *backup_conn, PGNodeInfo *nodeInfo, bool no_sync)
 	/* used for multitimeline incremental backup */
 	parray       *tli_list = NULL;
 
-
 	/* for fancy reporting */
 	time_t		start_time, end_time;
 	char		pretty_time[20];
@@ -820,6 +819,7 @@ do_backup(time_t start_time, bool no_validate,
 	/* Update backup status and other metainfo. */
 	current.status = BACKUP_STATUS_RUNNING;
 	current.start_time = start_time;
+
 	StrNCpy(current.program_version, PROGRAM_VERSION,
 			sizeof(current.program_version));
 
@@ -902,6 +902,10 @@ do_backup(time_t start_time, bool no_validate,
 		if (instance_config.master_conn_opt.pghost == NULL)
 			elog(ERROR, "Options for connection to master must be provided to perform backup from replica");
 
+	/* add note to backup if requested */
+	if (set_backup_params && set_backup_params->note)
+		add_note(&current, set_backup_params->note);
+
 	/* backup data */
 	do_backup_instance(backup_conn, &nodeInfo, no_sync);
 	pgut_atexit_pop(backup_cleanup, NULL);
@@ -934,8 +938,7 @@ do_backup(time_t start_time, bool no_validate,
 		(set_backup_params->ttl > 0 ||
 		 set_backup_params->expire_time > 0))
 	{
-		if (!pin_backup(&current, set_backup_params))
-			elog(ERROR, "Failed to pin the backup %s", base36enc(current.backup_id));
+		pin_backup(&current, set_backup_params);
 	}
 
 	if (!no_validate)

src/catalog.c

@@ -1534,18 +1534,23 @@ do_set_backup(const char *instance_name, time_t backup_id,
 
 	target_backup = (pgBackup *) parray_get(backup_list, 0);
 
-	if (!pin_backup(target_backup, set_backup_params))
-		elog(ERROR, "Failed to pin the backup %s", base36enc(backup_id));
+	/* Pin or unpin backup if requested */
+	if (set_backup_params->ttl >= 0 || set_backup_params->expire_time > 0)
+		pin_backup(target_backup, set_backup_params);
+
+	if (set_backup_params->note)
+		add_note(target_backup, set_backup_params->note);
 }
 
 /*
  * Set 'expire-time' attribute based on set_backup_params, or unpin backup
  * if ttl is equal to zero.
  */
-bool
+void
 pin_backup(pgBackup	*target_backup, pgSetBackupParams *set_backup_params)
 {
 
+	/* sanity, backup must have positive recovery-time */
 	if (target_backup->recovery_time <= 0)
 		elog(ERROR, "Failed to set 'expire-time' for backup %s: invalid 'recovery-time'",
 						base36enc(target_backup->backup_id));
@@ -1563,15 +1568,16 @@ pin_backup(pgBackup	*target_backup, pgSetBackupParams *set_backup_params)
 		{
 			elog(WARNING, "Backup %s is not pinned, nothing to unpin",
 									base36enc(target_backup->start_time));
-			return false;
+			return;
 		}
 		target_backup->expire_time = 0;
 	}
 	/* Pin comes from expire-time */
 	else if (set_backup_params->expire_time > 0)
 		target_backup->expire_time = set_backup_params->expire_time;
 	else
-		return false;
+		/* nothing to do */
+		return;
 
 	/* Update backup.control */
 	write_backup(target_backup);
@@ -1587,7 +1593,44 @@ pin_backup(pgBackup	*target_backup, pgSetBackupParams *set_backup_params)
 	else
 		elog(INFO, "Backup %s is unpinned", base36enc(target_backup->start_time));
 
-	return true;
+	return;
+}
+
+/*
+ * Add note to backup metadata or unset already existing note.
+ * It is a job of the caller to make sure that note is not NULL.
+ */
+void
+add_note(pgBackup *target_backup, char *note)
+{
+
+	char *note_string;
+
+	/* unset note */
+	if (pg_strcasecmp(note, "none") == 0)
+	{
+		target_backup->note = NULL;
+		elog(INFO, "Removing note from backup %s",
+				base36enc(target_backup->start_time));
+	}
+	else
+	{
+		/* Currently we do not allow string with newlines as note,
+		 * because it will break parsing of backup.control.
+		 * So if user provides string like this "aaa\nbbbbb",
+		 * we save only "aaa"
+		 * Example: tests.set_backup.SetBackupTest.test_add_note_newlines
+		 */
+		note_string = pgut_malloc(MAX_NOTE_SIZE);
+		sscanf(note, "%[^\n]", note_string);
+
+		target_backup->note = note_string;
+		elog(INFO, "Adding note to backup %s: '%s'",
+				base36enc(target_backup->start_time), target_backup->note);
+	}
+
+	/* Update backup.control */
+	write_backup(target_backup);
 }
 
 /*
@@ -1682,6 +1725,10 @@ pgBackupWriteControl(FILE *out, pgBackup *backup)
 	/* print external directories list */
 	if (backup->external_dir_str)
 		fio_fprintf(out, "external-dirs = '%s'\n", backup->external_dir_str);
+
+	if (backup->note)
+		fio_fprintf(out, "note = '%s'\n", backup->note);
+
 }
 
 /*
@@ -1919,6 +1966,7 @@ readBackupControlFile(const char *path)
 		{'b', 0, "from-replica",		&backup->from_replica, SOURCE_FILE_STRICT},
 		{'s', 0, "primary-conninfo",	&backup->primary_conninfo, SOURCE_FILE_STRICT},
 		{'s', 0, "external-dirs",		&backup->external_dir_str, SOURCE_FILE_STRICT},
+		{'s', 0, "note",				&backup->note, SOURCE_FILE_STRICT},
 		{0}
 	};
 
@@ -2185,6 +2233,8 @@ pgBackupInit(pgBackup *backup)
 	backup->external_dir_str = NULL;
 	backup->root_dir = NULL;
 	backup->files = NULL;
+	backup->note = NULL;
+
 }
 
 /* free pgBackup object */
@@ -2196,6 +2246,7 @@ pgBackupFree(void *backup)
 	pfree(b->primary_conninfo);
 	pfree(b->external_dir_str);
 	pfree(b->root_dir);
+	pfree(b->note);
 	pfree(backup);
 }
 

src/help.c

@@ -106,7 +106,8 @@ help_pg_probackup(void)
 	printf(_("                 [--help]\n"));
 
 	printf(_("\n  %s set-backup -B backup-path --instance=instance_name\n"), PROGRAM_NAME);
-	printf(_("                 -i backup-id [--ttl] [--expire-time]\n"));
+	printf(_("                 -i backup-id [--ttl=interval] [--expire-time=timestamp]\n"));
+	printf(_("                 [--note=text]\n"));
 	printf(_("                 [--help]\n"));
 
 	printf(_("\n  %s show-config -B backup-path --instance=instance_name\n"), PROGRAM_NAME);
@@ -140,7 +141,7 @@ help_pg_probackup(void)
 	printf(_("                 [--remote-proto] [--remote-host]\n"));
 	printf(_("                 [--remote-port] [--remote-path] [--remote-user]\n"));
 	printf(_("                 [--ssh-options]\n"));
-	printf(_("                 [--ttl] [--expire-time]\n"));
+	printf(_("                 [--ttl=interval] [--expire-time=timestamp] [--note=text]\n"));
 	printf(_("                 [--help]\n"));
 
 
@@ -285,7 +286,7 @@ help_backup(void)
 	printf(_("                 [--remote-proto] [--remote-host]\n"));
 	printf(_("                 [--remote-port] [--remote-path] [--remote-user]\n"));
 	printf(_("                 [--ssh-options]\n"));
-	printf(_("                 [--ttl] [--expire-time]\n\n"));
+	printf(_("                 [--ttl=interval] [--expire-time=timestamp] [--note=text]\n\n"));
 
 	printf(_("  -B, --backup-path=backup-path    location of the backup storage area\n"));
 	printf(_("  -b, --backup-mode=backup-mode    backup mode=FULL|PAGE|DELTA|PTRACK\n"));
@@ -304,6 +305,8 @@ help_backup(void)
 	printf(_("                                   backup some directories not from pgdata \n"));
 	printf(_("                                   (example: --external-dirs=/tmp/dir1:/tmp/dir2)\n"));
 	printf(_("      --no-sync                    do not sync backed up files to disk\n"));
+	printf(_("      --note=text                  add note to backup\n"));
+	printf(_("                                   (example: --note='backup before app update to v13.1')\n"));
 
 	printf(_("\n  Logging options:\n"));
 	printf(_("      --log-level-console=log-level-console\n"));
@@ -341,8 +344,9 @@ help_backup(void)
 	printf(_("      --dry-run                    perform a trial run without any changes\n"));
 
 	printf(_("\n  Pinning options:\n"));
-	printf(_("      --ttl=ttl                    pin backup for specified amount of time; 0 unpin\n"));
+	printf(_("      --ttl=interval               pin backup for specified amount of time; 0 unpin\n"));
 	printf(_("                                   available units: 'ms', 's', 'min', 'h', 'd' (default: s)\n"));
+	printf(_("                                   (example: --ttl=20d)\n"));
 	printf(_("      --expire-time=time           pin backup until specified time stamp\n"));
 	printf(_("                                   (example: --expire-time='2024-01-01 00:00:00+03')\n"));
 
@@ -710,12 +714,15 @@ help_set_backup(void)
 {
 	printf(_("\n%s set-backup -B backup-path --instance=instance_name\n"), PROGRAM_NAME);
 	printf(_("                 -i backup-id\n"));
-	printf(_("                 [--ttl] [--expire-time]\n\n"));
+	printf(_("                 [--ttl=interval] [--expire-time=time] [--note=text]\n\n"));
 
-	printf(_("      --ttl=ttl                    pin backup for specified amount of time; 0 unpin\n"));
+	printf(_("      --ttl=interval               pin backup for specified amount of time; 0 unpin\n"));
 	printf(_("                                   available units: 'ms', 's', 'min', 'h', 'd' (default: s)\n"));
+	printf(_("                                   (example: --ttl=20d)\n"));
 	printf(_("      --expire-time=time           pin backup until specified time stamp\n"));
 	printf(_("                                   (example: --expire-time='2024-01-01 00:00:00+03')\n"));
+	printf(_("      --note=text                  add note to backup; 'none' to remove note\n"));
+	printf(_("                                   (example: --note='backup before app update to v13.1')\n"));
 }
 
 static void

src/merge.c

@@ -702,6 +702,15 @@ merge_chain(parray *parent_chain, pgBackup *full_backup, pgBackup *dest_backup)
 	full_backup->compress_alg = dest_backup->compress_alg;
 	full_backup->compress_level = dest_backup->compress_level;
 
+	/* If incremental backup is pinned,
+	 * then result FULL backup must also be pinned.
+	 */
+	if (dest_backup->expire_time)
+		full_backup->expire_time = dest_backup->expire_time;
+
+	if (dest_backup->note)
+		full_backup->note = pgut_strdup(dest_backup->note);
+
 	/* FULL backup must inherit wal mode. */
 	full_backup->stream = dest_backup->stream;
 

src/pg_probackup.c

@@ -75,10 +75,10 @@ char	   *replication_slot = NULL;
 bool		temp_slot = false;
 
 /* backup options */
-bool		backup_logs = false;
-bool		smooth_checkpoint;
-char       *remote_agent;
-
+bool         backup_logs = false;
+bool         smooth_checkpoint;
+char        *remote_agent;
+static char *backup_note = NULL;
 /* restore options */
 static char		   *target_time = NULL;
 static char		   *target_xid = NULL;
@@ -183,6 +183,7 @@ static ConfigOption cmd_options[] =
 	{ 'b', 183, "delete-expired",	&delete_expired,	SOURCE_CMD_STRICT },
 	{ 'b', 184, "merge-expired",	&merge_expired,		SOURCE_CMD_STRICT },
 	{ 'b', 185, "dry-run",			&dry_run,			SOURCE_CMD_STRICT },
+	{ 's', 238, "note",				&backup_note,		SOURCE_CMD_STRICT },
 	/* restore options */
 	{ 's', 136, "recovery-target-time",	&target_time,	SOURCE_CMD_STRICT },
 	{ 's', 137, "recovery-target-xid",	&target_xid,	SOURCE_CMD_STRICT },
@@ -746,11 +747,15 @@ main(int argc, char *argv[])
 					 expire_time_string);
 		}
 
-		if (expire_time > 0 || ttl >= 0)
+		if (expire_time > 0 || ttl >= 0 || backup_note)
 		{
 			set_backup_params = pgut_new(pgSetBackupParams);
 			set_backup_params->ttl = ttl;
 			set_backup_params->expire_time = expire_time;
+			set_backup_params->note = backup_note;
+
+			if (backup_note && strlen(backup_note) > MAX_NOTE_SIZE)
+				elog(ERROR, "Backup note cannot exceed %u bytes", MAX_NOTE_SIZE);
 		}
 	}