Update Your Custom Root Record Model with Migrations

When you make a change to your root Record, or any of the records you store in Quip, your live app can sometimes break. Quip allows you to write migrations, which are scripts that tell Quip how to migrate a live app’s old data model to a new one.

Update the Root Record​

1. Update the live app version using quip-cli bump. This is important as Quip uses the live app’s version number to check when the data model changed and decide whether to run the migration script.

2. Make the required changes to your root Record. For instance, let’s change a sample root Record as follows:

Old root Record properties:

static getProperties() {
  return {
    amount: "number"
  }
}

New root Record properties:

static getProperties() {
  return {
    amount: "string"
  }
}

3. Create the migration script by running this command in your Terminal: quip-cli migration nameOfMigration. For example: quip-cli migration amountToString. This creates a JavaScript file in your live app folder, in a subfolder called “migrations”.

4. Open the migration file and fill in the function that updates the old root Record to the new one. The function returns the new root Record. For example, in our case above, the migration file would look like this:

quip.apps.registerMigration((rootRecord) => {
  const oldAmount = rootRecord.get("amount"); //number
  const newAmount = `${oldAmount} dollars`; // string

  rootRecord.set("amount", newAmount);

  return rootRecord;
});

5. Build, publish, and deploy your live app.

Now, anytime a user opens a live app using a root Record created before the current version number, the migration script runs and updates the root Record.

If you have multiple migrations across multiple versions of your live app, Quip runs the migration scripts in the correct order. That way, your data model is updated correctly! For example:

• A Quip user (example: jsmith) added version 1 of a live app (example: Lunch) to a document, then stopped using the document.
• You create migration scripts for versions 2 and 3 of Lunch. Now version 3 of Lunch is in production. Any Quip users who add Lunch to a document are automatically using version 3.
• jsmith opens the same document where version 1 of Lunch was used.
• Quip runs your migration scripts for version 2 then version 3 of Lunch. Now jsmith’s document is running version 3 of Lunch.