From aaef111ae270cd1b377974b89d950f72099b3a50 Mon Sep 17 00:00:00 2001 From: drebs Date: Thu, 7 Sep 2017 18:16:36 -0300 Subject: fixup! [pkg] improve naming of directory of migration script --- scripts/migration/0.9/README.md | 87 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 scripts/migration/0.9/README.md (limited to 'scripts/migration/0.9/README.md') diff --git a/scripts/migration/0.9/README.md b/scripts/migration/0.9/README.md new file mode 100644 index 00000000..c4556a59 --- /dev/null +++ b/scripts/migration/0.9/README.md @@ -0,0 +1,87 @@ +CouchDB schema migration script: from soledad-server < 0.9.0 to >= 0.9.0 +======================================================================== + +Starting with Soledad Server 0.9.0, the CouchDB database schema was changed to +improve speed of the server side storage backend. Because of that, this script +has to be run for all Leap providers that used to provide email using Soledad +Server < 0.9.0. + +If you never provided email with Leap, you don't need to run this script. + + +ATTENTION! +---------- + + - This script does not backup your data for you. Make sure you have a backup + copy of your databases before running this script! + + - Make sure you turn off any service that might be writing to the couch user + databases before running this script. From the Leap side, these would be + Leap MX in the "mx" node and Soledad Server in the "soledad" node. + + +Usage +----- + +When you run the script, you will see no output. All the output will be logged +to files, as explained in the Log section below. + +To see command line options, run: + + ./migrate.py --help + +To see what the script would do, run the following and check the logs +afterwards: + + ./migrate.py + +To actually run the migration, add the --do-migrate command line option: + + ./migrate.py --do-migrate + + +Log +--- + +The script will be installed in ``/usr/share/soledad-server/migration/0.9``, +and will log the results of any run by default to the ``logs/`` subdirectory of +that folder (i.e. ``/usr/share/soledad-server/migration/0.9/logs``). + +If you don't pass a ``--log-file`` command line option, a log will be written +to the log folder as described above. + + +Differences between old and new couch schema +-------------------------------------------- + +The differences between old and new schemas are: + + - Transaction metadata was previously stored inside each document, and we + used design doc view/list functions to retrieve that information. Now, + transaction metadata is stored in documents with special ids + (gen-0000000001 to gen-9999999999). + + - Database replica config metadata was stored in a document called + "u1db_config", and now we store it in the "_local/config" document. + + - Sync metadata was previously stored in documents with id + "u1db_sync_", and now are stored in + "_local/sync_". + + - The new schema doesn't make use of any design documents. + + +What does this script do +------------------------ + +- List all databases starting with "user-". +- For each one, do: + - Check if it contains the old "u1db_config" document. + - If it doesn't, skip this db. + - Get the transaction log using the usual design doc view/list functions. + - Write a new "gen-X" document for each line on the transaction log. + - Get the "u1db_config" document, create a new one in "_local/config", + Delete the old one. + - List all "u1db_sync_X" documents, create new ones in "_local/sync_X", + delete the old ones. + - Delete unused design documents. -- cgit v1.2.3