Updating Schema

Your First Schema Version

After you have updated your schema TypeScript files locally, you must publish it to Stately Cloud before you can use it - until then, the associated Stores will not know about your changes.

Using the CLI, stately schema put publishes a new version of your schema. This will also run your schema TypeScript files. For this to run, you need to have NodeJS installed, and have installed the dependencies for your schema package with npm install.

The first positional argument is the path to your schema’s index file (you can have schema in as many TypeScript files as you want as long as there’s a single file that exports everything). You can find your Schema ID in the Console and in the output of stately whoami.

stately schema put --schema-id <your schema ID> \
  --message "A schema update!" path/to/schema.ts

More Schema Versions

Your schema is not static—you can update it as your needs change. Unlike some other databases, updating your StatelyDB schema does not immediately change the database for all clients. Instead, each schema version is available for clients to use, and StatelyDB automatically translates between versions to maintain both backwards and forwards compatibility. This means you can update your schema, then update your clients to use the new schema version on your own schedule. Different clients can use different schema versions as long as you’d like, and they’ll all work together.

You use stately schema put to update your schema, just like when you created your first version. However, for updates to your schema, you’ll also need to write migrations along with your updated schema to describe what you’ve changed and resolve any ambiguities. The CLI will help point out where you need to add migrations.

Backwards Compatibility Check

When you’re updating your schema, stately schema put will fail if you are making a backwards-incompatible change that we can’t handle with migrations yet. We’re intentionally conservative right now about what counts as a backwards compatible change. You can add the --allow-backwards-incompatible argument to override this, but realize you’re taking the validity of your stored data into your own hands at that point. Ask us if you’re unsure about whether your change is safe. Eventually we will remove the --allow-backwards-incompatible option when migrations can handle all types of changes—in the meantime, it is sometimes necessary to override the backwards compatibility check when you know it’s safe.