|
| 1 | +# Canister snapshot download and upload |
| 2 | + |
| 3 | +This example demonstrates the process of downloading and uploading canister snapshots. It features a canister called `quotes` which has some faulty data in its stable memory. You may think of it as data corrupted during a data migration or something similar. For the purposes of this example, it's simply a quote with a typo. |
| 4 | + |
| 5 | +The steps in this readme can be run all in sequence by invoking the `run.sh` script in bash. |
| 6 | + |
| 7 | +## Prerequisites |
| 8 | + |
| 9 | +This example requires an installation of: |
| 10 | + |
| 11 | +- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install). Note: the Canister Snapshots feature requires `dfx` version `0.23.0-beta.3` or later. |
| 12 | +- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` |
| 13 | + |
| 14 | +Begin by opening a terminal window. |
| 15 | + |
| 16 | +## Step 1: Setup the project environment |
| 17 | + |
| 18 | +Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands: |
| 19 | + |
| 20 | +```bash |
| 21 | +cd examples/rust/canister-snapshot-download |
| 22 | +dfx start --clean --background |
| 23 | +``` |
| 24 | + |
| 25 | +## Step 2: Compile and deploy `quotes` canister |
| 26 | + |
| 27 | +```bash |
| 28 | +dfx deploy |
| 29 | +``` |
| 30 | + |
| 31 | +Also setup its initial state: |
| 32 | + |
| 33 | +```bash |
| 34 | +dfx canister call quotes "setup" |
| 35 | +``` |
| 36 | + |
| 37 | +And check what the `print` endpoint returns: |
| 38 | + |
| 39 | +```bash |
| 40 | +dfx canister call quotes "print" |
| 41 | +``` |
| 42 | + |
| 43 | +Output: |
| 44 | +```bash |
| 45 | +Colourless green ideas sleep furiously. |
| 46 | +``` |
| 47 | + |
| 48 | +Clearly, this British spelling is not correct, as the author of the quote is American. Let's fix it by downloading the canister state, fixing the stable memory and loading the fixed version. |
| 49 | + |
| 50 | +## Step 3: Create and download snapshot |
| 51 | + |
| 52 | +```bash |
| 53 | +dfx canister stop quotes |
| 54 | +dfx canister snapshot create quotes |
| 55 | +``` |
| 56 | + |
| 57 | +This returns a snapshot id, similar to |
| 58 | +```bash |
| 59 | +0000000000000000ffffffffff9000010101 |
| 60 | +``` |
| 61 | + |
| 62 | +Create a local directory and download the new snapshot: |
| 63 | +```bash |
| 64 | +mkdir ./snapshots |
| 65 | +dfx canister snapshot download --dir ./snapshots quotes 0000000000000000ffffffffff9000010101 |
| 66 | +``` |
| 67 | + |
| 68 | +## Step 4: Manipulate and upload the snapshot |
| 69 | +View the file in ./snapshot/stable_memory.bin. This is a binary file, but the first few bytes are ASCII characters. |
| 70 | + |
| 71 | +Fix the spelling by running: |
| 72 | +```bash |
| 73 | +sed -i -e 's/Colour/Color/g' ./snapshots/stable_memory.bin |
| 74 | +``` |
| 75 | + |
| 76 | +Upload the fixed snapshot. |
| 77 | +```bash |
| 78 | +dfx canister snapshot upload --dir ./snapshots quotes |
| 79 | +``` |
| 80 | + |
| 81 | +This will return a new snapshot id, similar to |
| 82 | +```bash |
| 83 | +0000000000000001ffffffffff9000010101 |
| 84 | +``` |
| 85 | + |
| 86 | +## Step 5: Load the snapshot and verify |
| 87 | + |
| 88 | +```bash |
| 89 | +dfx canister snapshot load quotes 0000000000000001ffffffffff9000010101 |
| 90 | +dfx canister start quotes |
| 91 | +dfx canister call quotes "print" |
| 92 | +``` |
| 93 | + |
| 94 | +Output: |
| 95 | +```bash |
| 96 | +Colorless green ideas sleep furiously. |
| 97 | +``` |
| 98 | + |
| 99 | +Clean up. |
| 100 | +```bash |
| 101 | +rm -rf ./snapshots |
| 102 | +dfx stop |
| 103 | +``` |
| 104 | + |
| 105 | +## Conclusion |
| 106 | + |
| 107 | +The ability to download and upload snapshots enables various new use cases: |
| 108 | +- Keeping canister backups on disk rather than on-chain. |
| 109 | +- Cloning canister state into another canister. |
| 110 | +- Migrating canister state to a different subnet. |
| 111 | +- Fixing faulty state or performing data migrations that would be prohibitive on-chain. |
0 commit comments