Lifecycle rules instruct the B2 service to automatically hide and/or delete old files. You can set up rules to do things like delete old versions of files 30 days after a newer version was uploaded.

A bucket can have up to 100 lifecycle rules. Each rule has a fileNamePrefix that specifies which files in the bucket it applies to. Any file whose name starts with the prefix is subject to the rule. A prefix of the empty string, "", means that the rule applies to all files in the bucket.

You're not allowed to create two rules that both apply to the same files. For example, a rule with a file name prefix of photos/ and a rule with a file name prefix of photos/kittens/ would both apply to a file named photos/kittens/fluffy.jpg, so you're not allowed to have both rules at the same time.

Each lifecycle rule specifies two things: daysFromUploadingToHiding and daysFromHidingToDeleting. Either can be null, which means that part of the rule doesn't apply. Setting both to null is not allowed, because the rule would do nothing.

Setting either daysFromUploadingToHiding or daysFromHidingToDeleting to 0 is not allowed. When either is set, it must be a positive number.

The most commonly used setting is daysFromHidingToDeleting, which says how long to keep file versions that are not the current version. A file version counts as hidden when explicitly hidden with b2_hide_file, or when a newer file with the same name is uploaded. When a rule with this setting applies, the file will be deleted the given number of days after it is hidden.

For example, if you are backing up your files to B2 using the B2 command-line tool, or another software package that uploads files when they change, B2 will keep old versions of the file. This is very helpful, because it means the old versions are there if the original file is accidentally deleted. On the other hand, keeping them forever can clutter things up. For an application like this, you might want a lifecycle rule that keeps old versions in the backup/ folder for 30 days, and then deletes them:

    {
        "daysFromHidingToDeleting": 30,
        "daysFromUploadingToHiding": null,
        "fileNamePrefix": "backup/"
    }

The daysFromUploadingToHiding setting is less frequently used. It causes files to be hidden automatically after the given number of days. This can be useful for things like server log files that can be deleted after a while. This rule will keep files in the logs/ folder for 7 days, and then hide them. They will then be deleted one day after hiding.

    {
        "daysFromHidingToDeleting": 1,
        "daysFromUploadingToHiding": 7,
        "fileNamePrefix": "logs/"
    }

Every lifecycle rule includes an implicit rule: When the oldest version of a file is a hide marker, the marker is deleted, independent of its age.

The API calls related to lifecycle rules are:

b2_create_bucket - creates a new bucket
b2_update_bucket - changes the settings on a bucket

When you create a new bucket, you can specify the lifecycle rules. Later, you can change the rules on a bucket by updating it.

When Things Happen

Lifecycle rules are applied once a day. The smallest number of days you can set in a rule is 1. Rules will be applied at the next daily run after that number of days has passed.

As an example, suppose you upload the first version of file.txt on May 2. Then you upload a new version of file.txt on May 9 at 06:00. At this point there are two versions, the May 2 version and the May 9 version. The May 2 version is hidden by the May 9 version, so it became hidden at the time the May 9 version was uploaded.

Suppose there's a lifecycle rule to delete files one day after they are hidden. If the lifecycle rules get applied at 01:00 on May 10, nothing will happen yet. It has been 19 hours since the May 2 version was hidden. Because it hasn't been a full day, nothing will happen.

The next day, on May 11, when the lifecycle get applied something will happen. If it runs at 01:00, it's now been 43 hours since the May 2 version was hidden, so the rule now applies and the old version will be deleted.

Setting Lifecycle Rules on the Web

The "Buckets" page for your account on the Backblaze web site has options for common lifecycle rule settings:

Keep all versions of the file (default) removes all lifecycle rules from the bucket, and keeps all versions of all files until you explicitly delete them.

Keep only the last version of the file deletes prior versions of a file one day after uploading a new version or hiding the file. The rule looks like this:

    {
        "daysFromHidingToDeleting": 1,
        "daysFromUploadingToHiding": null,
        "fileNamePrefix": ""
    }

Keep prior versions for this number of days lets you pick a number of days, and deletes prior versions of a file that many days after uploading a new version or hiding the file. The rule looks like this if you pick 30 days:

    {
        "daysFromHidingToDeleting": 30,
        "daysFromUploadingToHiding": null,
        "fileNamePrefix": ""
    }