Epochs: when new code cannot read old data
purpose for app developers for administrators
A refresh replaces a snap's code and keeps its data so a release with a new data format could leave users with data it cannot read. An epoch states which data formats a revision can read and write. snapd and the store only move a device to a revision that can read what the current one wrote and a publisher can ship a migrating revision as the step in between. Most snaps stay at epoch 0 and need none of this.
On the map: getting snaps district
01 New code, old data
"An Epoch represents the ability of the snap to read and write its data." snapd only moves a device to a revision that can read what its current revision wrote. The photo editor's versions and epochs in this deck are invented for the example.
The photo editor's next version has a faster catalogue. It also can't read the old one, and you have six years of photos in the old one. What should happen tonight, when the refresh runs? A refresh replaces the program and leaves your data where it is. Here, it would hand your catalogue to code that can't open it. So the snap states which data it can read. That statement is the epoch. In the code's words, it's the ability of the snap to read and write its data. And snapd won't make the jump to a revision that can't read what the current one wrote.
02 Most snaps need none of this
Snaps default to epoch 0, and "most developers need not worry about it". The epoch changes only when new code cannot read old data.
If you publish a snap and you've never typed the word epoch, relax. You've been using one all along. Every snap has an epoch, and the default is zero. The comment in the code says it plainly: most developers need not worry about it. Zero reads zero, so every refresh between your revisions is allowed. You don't bump the epoch for a new version. You don't even bump it for a new file format, as long as the new code still reads the old files. You bump it only at a real break, when the new code can't read the old data.
03 The step in between for app developers
epoch: N reads and writes N. epoch: N* also reads N-1, so it can migrate. The snap converts its own data; snapd only checks that the revision can read what the installed one wrote.
You're the developer now, and you really do need that new catalogue format. Version 3.0 says epoch 1 in its snap.yaml, and epoch 1 can't read zero. Ship the step in between first: version 2.9, revision 43, with epoch: 1*. The star means it can also read the epoch before it. So it reads zero and one, and writes one. Now there's a path: 42 to 43, then 43 to 44. And who does the work? Converting the catalogue is revision 43's job, in its own code or its hooks. Snapd only compares the numbers. For anything more elaborate, there's a long form with read and write lists.
04 One refresh, two revisions
A refresh across an epoch change goes through the migrating revision and on to the latest in the same change. A first install sends no installed epoch, so the store can offer the latest revision directly.
So what does all this look like from your side of the screen? One command. You type snap refresh photo-editor, or the timer does. Snapd tells the store which revision you have, and its epoch. The store offers a revision that can read your data: 43, not the newest. 43 is installed, and its migration runs. Then the change asks the store once more, about the snaps it just refreshed. Your data is epoch 1 now, so the answer is 44. Look at the task list afterwards: two downloads, one refresh. A first install has no old data to read, so the store can offer 44 straight away.
05 When snapd says no
snapd refuses a local install or a store refresh whose epoch cannot read the installed one, and a snapshot restore that the installed revision cannot read. The message names both epochs.
Mostly the store routes you around the gap. Here's what happens when something jumps it anyway. Say you build 3.0 yourself and install the file over 2.4. Snapd refuses, and the message names both epochs. The test for this states why: an update mustn't leave the snap unable to read the previous version's data. The same check runs on a revision that comes from the store. And it runs in one place you might not expect: restoring a snapshot. A snapshot remembers the epoch it was taken under. If the installed revision can't read it, the restore is refused. In all three cases, your data is left as it was.
06 Epoch, track, or revert
An epoch orders a migration for everyone on a channel. A track keeps an older line of releases available. snap revert returns to the previous revision and its own data, but not data shared by all revisions.
Three tools live close together, and people reach for the wrong one. Ask yourself where you want your users to end up. An epoch is for a break that everyone should cross. It makes sure they cross in the right order, and it doesn't keep the old version around. If some people should stay on version two, that's a track: a second line of releases the publisher keeps side by side. If the new version went wrong, snap revert photo-editor puts the previous revision back, with its own copy of the data. One caveat: data shared by all revisions isn't rolled back. The epoch converts nothing and undoes nothing.
07 Where to go from here
Roads: snap packaging, refresh, the store, snapshots, remove and revert, and who decides when a snap updates.
That's the whole idea: a number that stops new code from meeting data it can't read. Zero by default, and a starred step in between when the format breaks. The machinery around it lives in other decks. Snap packaging shows where each revision keeps its data. The refresh deck has the task that asks the store again. The store deck covers tracks, and what a refresh request says. Snapshots has the epoch check on restore. Remove and revert covers what a revert doesn't undo. And the update control deck lists everyone else who can make an update wait.
Read more
The ways to write an epoch
| In snap.yaml | Reads | Writes | Use |
|---|---|---|---|
nothing, or epoch: 0 | 0 | 0 | the default |
epoch: N | N | N | after the break |
epoch: N* | N-1 and N | N | the migrating revision |
epoch: {read: [1, 2, 3], write: [1, 3]} | the read list | the write list | anything else |
Rules for the long form: at most 10 entries per list, strictly increasing, and the two lists must share at least one number. read defaults to write; write defaults to the last entry of read. Numbers are written in base 10 with no zero padding and must be less than 2³². 0* is invalid.
The rule
A revision may replace the installed one only if its read list and the installed revision's write list have a number in common.
| Installed | Offered | Allowed |
|---|---|---|
| 0 | 0 | yes |
| 0 | 1 | no |
| 0 | 1* | yes |
| 1* | 1 | yes |
| 1 | 0 | no |
| 1 | 2* | yes |
Where the epoch is checked
| Moment | Who checks | Result if unreadable |
|---|---|---|
| choosing a revision to offer | the store, from the epoch snapd reports | a readable revision is offered instead |
| refresh from the store | snapd | cannot refresh "<snap>" to new revision <n> with epoch <e>, because it can't read the current epoch of <e> |
snap install --dangerous or snap try over an installed snap | snapd | cannot refresh "<snap>" to local snap with epoch <e>, because it can't read the current epoch of <e> |
| end of a refresh change | snapd asks the store again for the snaps it refreshed | a revision with a different epoch is added to the same change |
snap restore | snapd | cannot restore snapshot for "<snap>": current snap (epoch <e>) cannot read snapshot data (epoch <e>) |
snap revert | no epoch check was found | - |
Epoch, track and revert
| Tool | Decided by | Effect |
|---|---|---|
| epoch | the publisher, in snap.yaml | devices move across a data format change in a readable order |
| track | the publisher, in the store | an older line of releases stays available to those who follow it |
snap revert | the administrator | the previous revision and its own data return; data shared by all revisions is not rolled back |
Further reading
- Glossary: epoch: the published definition.
- Channels and tracks: the tool for keeping an older line of releases.
- Manage updates: refresh and revert from the administrator's side.
Roads from here
GETTING SNAPS
- Snap packaging — where a revision's data lives and the default epoch in snap.yaml
- The store — tracks and what a refresh request tells the store
RUNNING SNAPS
- Refresh — the task that asks the store again after a refresh
- Snapshots — restoring a snapshot taken under another epoch
- Remove and revert — reverting to the previous revision and its data
- Who decides when a snap updates — every other way an update is made to wait