12

I am having trouble understanding what exactly to expect from the CleanupTime option in the Ola Hallengren Server Maintenance Solution. I'm finding some related questions, and elaborate answers, but the explanations still puzzle me a bit.

Specifically:

I am doing a weekly FULL backup, a daily DIFF backup, and an hourly LOG backup. The FULL backup is using the default CleanupTime of 24h. The DIFF and LOG backup have NULL as CleanupTime.

From the documentation of the CleanupTime paramter, I fail to understand if setting the CleanupTime setting for a backup of BackupType FULL, will also delete older DIFF and LOG backup files, or only FULL backup files.

Specify the time, in hours, after which the backup files are deleted. If no time is specified, then no backup files are deleted.

The latter paragraph makes me think that setting CleanupTime on backups of BackupType FULL will also delete older transaction logs. Yet it is unclear if this paragraph only applies to backups of the BackupType LOG, or also to backups of the BackupType FULL.

DatabaseBackup has a check to verify that transaction log backups that are newer than the most recent full or differential backup are not deleted.

What I am trying to achieve, is that I can do a point-in-time recovery up to 1 week. (We have a very slowly changing database, so this is feasible) The way I understand it now, this would require a week old full backup, and a weeks worth of Transaction log backup. Since the full, and differential backups can only be used to restore to one specific point in time.

So, should I just set the CleanupTime option of my FULL backup job to 24*7? What I'm guessing now is that setting it to 24h, will cause the next FULL backup to delete all older Full, diff and Transaction log backup files, leaving me with a point-in-time recovery window of ... 0 hours. Right?

3 Answers 3

28

The @CleanupTime is always specified for a specific backup job. For example, if you create a Full backup job, a Differential backup job and a Transaction Log backup job, then the @CleanupTime always relates to the extension of the job.

Let's take a look at a Full backup example.

Full Backup

If you create a full backup job, then you will normally add one or more of the following parameters:

  • @Databases : Which databases get backed up (not really relevant for this example)
  • @Directory : The directory to store the backups
  • @BackupType : Full, Differential, TLog
  • @CleanupTime : How much hours worth of backups to keep
  • @FileExtensionFull : The extension of your backup.

So you have a backup job in place that will create a full backup according to the schedule you defined for the at job. Let's assume the following:

  • this job runs at 20:00 (8 p.m.)
  • @FileExtensionFull has been set to 'BAK'
  • @Directory has been set to 'F:\SQLBACKUP'
  • @CleanupTime has been set to 24 (hours)

If we look at the MaintenanceSolution.sql file then you will find the description for the parameter:

SET @CleanupTime         = NULL         
-- Time in hours, after which backup files are deleted. If no time is specified, then no backup files are deleted.

Well, that's not helping much. Same as in the official documentation on the site. Let's dig further. If you scan through the script you will eventually find a section that looks like this:

The script has been wrapped to increase readability

IF @BackupSoftware IS NULL
    BEGIN
        SET @CurrentCommandType02 = 'xp_delete_file'
        SET @CurrentCommand02 = 
            'DECLARE @ReturnCode int 
            EXECUTE @ReturnCode = [master].dbo.xp_delete_file 0, 
                N''' + REPLACE(@CurrentDirectoryPath,'''','''''') + ''', -- first parameter
                ''' + @CurrentFileExtension + ''', --second parameter
                ''' + CONVERT(nvarchar(19),@CurrentCleanupDate,126) + ''' -- third parameter
        IF @ReturnCode  0 RAISERROR(''Error deleting files.'', 16, 1)'
    END

So Ola is basically using the built-in xp_delete_file function of SQL Server to delete a file at a certain time according to:

  • @CurrentDirectoryPath
  • @CurrentFileExtension
  • @CurrentCleanupDate

But wait what would for example, the @CurrentCleanupDate be? If we go back a bit in the script you can find a section that looks like this:

INSERT INTO @CurrentCleanupDates (CleanupDate, Mirror)
    SELECT DATEADD(hh,-(@CleanupTime),GETDATE()), 0

Ah, so the @CurrentCleanupDate is a date addition which is calculated from the @CleanupTime and the current time GETDATE(). Cool.
(...and we might have just found a typo in the code, because the sections for normal and mirror database both contain Mirror in the code.)

What is the relevant section then for @CurrentFileExtension? Let's search around a bit again. And we find:

SELECT @CurrentFileExtension = CASE
    WHEN @CurrentBackupType = 'FULL' THEN @FileExtensionFull
    WHEN @CurrentBackupType = 'DIFF' THEN @FileExtensionDiff
    WHEN @CurrentBackupType = 'LOG' THEN @FileExtensionLog
    END

So there you have it.

Summary

If the parameters for your Full backup job are set as @FileExtensionFull='BAK' and you have set a @CleanupTime=24 then the procedure will delete all Full backup files that are at least a day old (24 hours).

The @CurrentCommand02 that gets executed is basically:

xp_delete_file 0, 'F:\SQLBACKUP', 'BAK', '2018-08-20 20:00:00.045'

So it doesn't touch on any other backup files. (Unless of course you have defined 'BAK' to be the extension of all backup types, in which case you lose).

3
  • 1
    With the current version there is no issue generated by having non-custom file extensions for DIFF, LOG and normal backups. What I wanted to mention though, was that @CleanupTime works for the currently executing type of backup. So if you're performing daily FULL backups with 24h cleanup time, it will essentially delete ALL full backups older than 24h. Then if you also do DIFF backups with a 24h cleanup time, and for example if you perform these backups every 2 hours, you will end up with DIFF backups that have NO corresponding FULL backup, because some diffs are not yet older than 24 hours. Commented Oct 8, 2020 at 9:12
  • Continued - So a fix to the above situation I pointed out, would be to add additional time to the FULL backup's cleanup time, equal to the amount of time in hours between the last DIFF backup's time and the next FULL backup's time. So that would be 29 hours. For safety, I would also add one extra hour. I currently use 30 hours for FULL backups and 24 hours for DIFF backups that run every 2 hours between 10 and 22 (10 PM). I don't do TLog backups in this example. Commented Oct 8, 2020 at 9:19
  • Continued - You could plot the backups by type, as time spans on a common time axis, with length = their cleanup times (ie. lifetimes!). If a set (FULL + its DIFFs or at least the LAST DIFF! + its TLogs or ALL TLogs after the LAST DIFF) overlaps vertically, then you have correct cleanup times for all of them. If not, you may end up with missing dependencies. Commented Oct 8, 2020 at 9:24
9

I upvoted @hot2use's answer as it covers this question in detail, but I did want to share an easy way to test this stuff.

It might help you (as it helped me) to fully understand how the script works if you:

  1. Install the backup script (and other dependencies) on a test instance - I tested on my local computer.
  2. Now, alter the script and search/replace hh with minute. The only references I can find with hh are where the script is dealing with the cleanup time. This allows you to quickly run backups of various types (FULL, DIFF, LOG) see the effects of the execution because the retention is in minutes and not hours.

Run a FULL, DIFF and LOG backup of a test database and note the files created in the individual folders. This is what I used (note the CleanupTime of 1 minute due to alter the script from hours to minutes):

exec [dbo].[DatabaseBackup]
@Databases = 'test',
@Directory = 'C:\OlaBackupTest',
@BackupType = 'full',
@Verify = 'N',
@CleanupTime = 1,
@CleanupMode = 'AFTER_BACKUP'

exec [dbo].[DatabaseBackup]
@Databases = 'test',
@Directory = 'C:\OlaBackupTest',
@BackupType = 'diff',
@Verify = 'N',
@CleanupTime = 1,
@CleanupMode = 'AFTER_BACKUP'

exec [dbo].[DatabaseBackup]
@Databases = 'test',
@Directory = 'C:\OlaBackupTest',
@BackupType = 'log',
@Verify = 'N',
@CleanupTime = 1,
@CleanupMode = 'AFTER_BACKUP'

My testing revealed the following observations:

FULL

Every execution of a FULL backup created a new FULL backup and deleted any FULL backup files older than 1 minute. No DIFF or LOG backup files were ever affected.

DIFF

Every execution of a DIFF backup created a new DIFF backup and deleted any DIFF backup files older than 1 minute. No FULL or LOG backup files were ever affected.

LOG

Every execution of a LOG backup created a new LOG backup. Continuous LOG backups (without intervening FULL or DIFF backups) simply continued to accumulate in the LOG backup folder without regard to the cleanup time. If a FULL or DIFF backup was eventually taken, the NEXT run of the LOG backup deleted any LOG backups older than the latest FULL or DIFF and also older than 1 minute.

No FULL or DIFF backup files were ever affected while running LOG backups.


I would recommend keeping more than 1 week of FULL backups in the event you need to go back in time to restore. Assuming 2 weeks of FULL backups, you'd need a CleanupTime of 336 hours.

During your testing of the 1 minute stuff, you'll see that:

  • Running FULL backups never delete DIFF or LOG backups
  • Running DIFF backups never delete FULL or LOG backups
  • Running LOG backups never delete FULL or DIFF backups
0
2

Expanding on the other two answers, because I just encountered this:

May be worth noting (to whomever may google this). to allow for a little bit more than the exact time you want to keep your backup.

If op wants to keep the 1-week old backup, the 24x7 hours won´t always keep the 1-week old file. Reason: Databases are growing. You new backup might take slightly Longer.

If your first backup file was create 2020-03-15 03:00:05.000 And the next backup takes a bit longer and file is created 2020-03-22 30:00:06.000 - that´s more than the specified 168 hours (one second, mind you)

So to be safe, make it 24x7+1!

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.