From 15d1f2cd361963fc8c92c717d71a9b21967389ed Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Fri, 8 Mar 2024 14:32:16 -0800 Subject: [PATCH 1/4] Add emulator state migration guide --- .../migrate/migrate-emulator-state.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 docs/tools/flow-cli/migrate/migrate-emulator-state.md diff --git a/docs/tools/flow-cli/migrate/migrate-emulator-state.md b/docs/tools/flow-cli/migrate/migrate-emulator-state.md new file mode 100644 index 0000000000..1fac0c014f --- /dev/null +++ b/docs/tools/flow-cli/migrate/migrate-emulator-state.md @@ -0,0 +1,61 @@ +--- +title: Migrating Emulator state to Cadence 1.0 +description: How to locally test storage migration and staged contract upgrades on Emulator +sidebar_position: 6 +--- + +Flow CLI provides a command `flow migrate state` to migrate your local emulator +state to Cadence 1.0, and to deploy upgraded contracts to the emulator. +This is useful for locally testing the staged contract upgrades, and to see how the +new network and the upgraded contracts would behave with the migrated data. + +## Migration Guide + +To test the migration, first you would need an emulator state, created with an emulator/CLI release +that uses a pre-1.0 Cadence version. + +### Getting the old state + +For example, to get an emulator state with Flow CLI `1.14.0`: + +- Start the emulator with the `--persist` flag. + ```shell + flow emulator --persist + ``` +- Deploy the pre-1.0 project/contracts to the emulator +- Run transactions if there are any. +- Close the emulator. It is important to make sure the emulator is closed/shutdown before taking the snapshot, + so that any pending in-memory data would be written to the persisted state properly. +- Locate the persisted state `./flowdb/emulator.sqlite` file, from the project root. + +### Migrating the state + +Download and install the latest CLI, that runs Cadence 1.0. + +- Run `migrate` command against the previously created state. +- The state file (`emulator.sqlite`) can be provided using the `-db-path` flag. +- If there are any contracts that also need to be upgraded, those can be specified using the `--contracts` flag. + Note that, the paths to these updated contracts must be specified in the `flow.json` file: + ```json + { + "contracts": { + "Test": "./updated_test_contract.cdc" + } + } + ``` +- The migration will produce a report consisting of the migration status. + This can be enabled by setting the `--save-report` flag. + +A sample `migrate` command would look like: + +```shell +flow migrate state --db-path=/path/to/emulator.sqlite --save-report=./reports --contracts="Test" +``` + +### Testing the migrated state + +Once the migration completes successfully, the emulator can be started with the migrated state. +For that, ensure the emulator is started again using the new CLI version (that runs Cadence 1.0), +with the `--persist` flag. +Now the emulator should be up and running using the migrated state and the updated contracts. +Run any transactions to verify the correctness of the existing data. \ No newline at end of file From 567f7ac93079b213a1c58c5224fe8338f50fc6d5 Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Fri, 8 Mar 2024 18:07:16 -0800 Subject: [PATCH 2/4] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bastian Müller --- .../tools/flow-cli/migrate/migrate-emulator-state.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/tools/flow-cli/migrate/migrate-emulator-state.md b/docs/tools/flow-cli/migrate/migrate-emulator-state.md index 1fac0c014f..6eee6e3fcd 100644 --- a/docs/tools/flow-cli/migrate/migrate-emulator-state.md +++ b/docs/tools/flow-cli/migrate/migrate-emulator-state.md @@ -20,11 +20,13 @@ For example, to get an emulator state with Flow CLI `1.14.0`: - Start the emulator with the `--persist` flag. ```shell - flow emulator --persist + flow emulator --persist ``` + - Deploy the pre-1.0 project/contracts to the emulator - Run transactions if there are any. -- Close the emulator. It is important to make sure the emulator is closed/shutdown before taking the snapshot, +- Stop the emulator (Ctrl-C on *nix platforms, and Ctrl-Break or Ctrl-Pause on Windows). + It is important to make sure the emulator is stopped before taking the snapshot, so that any pending in-memory data would be written to the persisted state properly. - Locate the persisted state `./flowdb/emulator.sqlite` file, from the project root. @@ -32,8 +34,8 @@ For example, to get an emulator state with Flow CLI `1.14.0`: Download and install the latest CLI, that runs Cadence 1.0. -- Run `migrate` command against the previously created state. -- The state file (`emulator.sqlite`) can be provided using the `-db-path` flag. +- Run `flow-c1 migrate` against the previously created state. +- The state file (`emulator.sqlite`) can be provided using the `--db-path` flag. - If there are any contracts that also need to be upgraded, those can be specified using the `--contracts` flag. Note that, the paths to these updated contracts must be specified in the `flow.json` file: ```json @@ -49,7 +51,7 @@ Download and install the latest CLI, that runs Cadence 1.0. A sample `migrate` command would look like: ```shell -flow migrate state --db-path=/path/to/emulator.sqlite --save-report=./reports --contracts="Test" +flow-c1 migrate state --db-path=/path/to/emulator.sqlite --save-report=./reports --contracts="Test" ``` ### Testing the migrated state From 8a35c5b0e0e92539cee54f01dc924621eca7b031 Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Tue, 12 Mar 2024 12:29:43 -0700 Subject: [PATCH 3/4] Improve instructions --- .../migrate/migrate-emulator-state.md | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/tools/flow-cli/migrate/migrate-emulator-state.md b/docs/tools/flow-cli/migrate/migrate-emulator-state.md index 6eee6e3fcd..2d7a42b28d 100644 --- a/docs/tools/flow-cli/migrate/migrate-emulator-state.md +++ b/docs/tools/flow-cli/migrate/migrate-emulator-state.md @@ -16,7 +16,12 @@ that uses a pre-1.0 Cadence version. ### Getting the old state -For example, to get an emulator state with Flow CLI `1.14.0`: +It is recommended to use the latest pre-1.0 CLI version (e.g: `v1.14.*`) for creating the old state. +This is because the emulator shipped with older CLI versions may not include some of the system contracts +(e.g: `RandomBeaconHistory` contract) that are included by default in the newer versions of the emulator/CLI. +Such contracts are required for the migration. + +To get an emulator state with Flow CLI `1.14.0`: - Start the emulator with the `--persist` flag. ```shell @@ -35,16 +40,28 @@ For example, to get an emulator state with Flow CLI `1.14.0`: Download and install the latest CLI, that runs Cadence 1.0. - Run `flow-c1 migrate` against the previously created state. + - The state file (`emulator.sqlite`) can be provided using the `--db-path` flag. + - If there are any contracts that also need to be upgraded, those can be specified using the `--contracts` flag. - Note that, the paths to these updated contracts must be specified in the `flow.json` file: + Note that, the paths to these updated contracts and their deployed addresses must be specified in the `flow.json` file. + For example, assuming the contract was deployed in the `test` account in the emulator, + and assuming the updated contract is in the `./updated_test_contract.cdc` file, the `flow.json` should include: ```json { "contracts": { "Test": "./updated_test_contract.cdc" + }, + "deployments": { + "emulator": { + "test": [ + "Test" + ] + } } } ``` + - The migration will produce a report consisting of the migration status. This can be enabled by setting the `--save-report` flag. From dba61275cd3817d782b4a931201fadb0ca4b5f68 Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Tue, 12 Mar 2024 14:29:54 -0700 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Greg Santos --- docs/tools/flow-cli/migrate/migrate-emulator-state.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tools/flow-cli/migrate/migrate-emulator-state.md b/docs/tools/flow-cli/migrate/migrate-emulator-state.md index 2d7a42b28d..f42ded4fa3 100644 --- a/docs/tools/flow-cli/migrate/migrate-emulator-state.md +++ b/docs/tools/flow-cli/migrate/migrate-emulator-state.md @@ -21,7 +21,7 @@ This is because the emulator shipped with older CLI versions may not include som (e.g: `RandomBeaconHistory` contract) that are included by default in the newer versions of the emulator/CLI. Such contracts are required for the migration. -To get an emulator state with Flow CLI `1.14.0`: +**To get an emulator state with Flow CLI `1.14.0`:** - Start the emulator with the `--persist` flag. ```shell @@ -31,8 +31,8 @@ To get an emulator state with Flow CLI `1.14.0`: - Deploy the pre-1.0 project/contracts to the emulator - Run transactions if there are any. - Stop the emulator (Ctrl-C on *nix platforms, and Ctrl-Break or Ctrl-Pause on Windows). - It is important to make sure the emulator is stopped before taking the snapshot, - so that any pending in-memory data would be written to the persisted state properly. + **It is important to make sure the emulator is stopped before taking the snapshot, + so that any pending in-memory data would be written to the persisted state properly.** - Locate the persisted state `./flowdb/emulator.sqlite` file, from the project root. ### Migrating the state @@ -44,7 +44,7 @@ Download and install the latest CLI, that runs Cadence 1.0. - The state file (`emulator.sqlite`) can be provided using the `--db-path` flag. - If there are any contracts that also need to be upgraded, those can be specified using the `--contracts` flag. - Note that, the paths to these updated contracts and their deployed addresses must be specified in the `flow.json` file. + **Note that, the paths to these updated contracts and their deployed addresses must be specified in the `flow.json` file.** For example, assuming the contract was deployed in the `test` account in the emulator, and assuming the updated contract is in the `./updated_test_contract.cdc` file, the `flow.json` should include: ```json