Upgrades and maintenance
Plan how to evaluate, merge, migrate, validate, and recover from future template updates.
If your project does not need an upgrade, you can keep using its current version. This chapter is a maintenance guide for future reference. It does not require you to download a new version, update dependencies, run migrations, or redeploy now, and it does not specify a version you must upgrade to.
An initialized project already contains the template source code, and you manage subsequent changes in your own project. Updating the template requires comparing and merging changes. It cannot happen automatically the way replacing a regular dependency package does.
Understand the different kinds of updates
| Action | What it does | Does it automatically update existing application code? |
|---|---|---|
| Update the Saavo CLI | Updates tooling for tasks such as project creation | No |
| Create another project from the template | Produces another initialized copy of the source code | Does not merge it into the original project |
| Update npm dependencies | Changes dependency versions and may change runtime behavior | Does not sync template configuration or application logic |
| Merge a newer template | Incorporates selected source changes into your project | Requires evaluating and handling each change |
npm run deploy:update | Validates and deploys the application in the current working directory | Does not download a newer template |
Edit config/upgrade.ts | Configures plan upgrade suggestions on the OAuth consent page | Unrelated to project version upgrades |
The CLI currently has no upgrade command that automatically merges changes into an existing project. saavo refresh refreshes sign-in credentials, not project source code.
When to plan an upgrade
Start with your actual needs. Does the new version fix a problem you have encountered, affect security or runtime components you use, or provide functionality you need? If the changes only affect unused features, you can record them and defer the upgrade. You do not need to change your application just to match version numbers.
Resolving a problem does not always require merging the entire template. You can adopt a related set of fixes, but you must check the types, data structures, configuration, and tests they depend on. Copying only the most obvious function is not enough.
Three articles in this chapter
- Evaluate and merge template updates: Confirm the template's source, compare the old template, new template, and your project, and decide which changes to adopt.
- Migrate data and configuration: Handle existing databases, configuration, resource bindings, and persistent business identifiers, and identify incompatible changes.
- Validation, deployment, and maintenance records: Validate existing data and new behavior, choose a recovery approach based on the deployment stage, and keep the information needed for future maintenance.
If an update does not change databases or resources, you can read just the first and third articles. There is no need to write extra migrations simply to complete an upgrade process.
Information you can keep now
These records will help with future comparisons without requiring changes to how your project runs now:
- The template name, version, and source code origin at initialization.
- The project's initial commit, along with your application's current version and release commit.
- Core modules you have modified, ongoing customizations, and known limitations.
- The current mapping between Workers and resources, and the secure storage location of existing credentials.
The CLI initializes the version in a new project's package.json to 0.0.1. This is the application's own version and cannot be used to infer the template version. If the template's source is unclear, record it as unknown, then confirm it using the initial files and records from when you obtained the source code. Do not guess.
Define a specific goal before proceeding
The commands in the following articles are examples for future maintenance. Before running them, confirm the target version, scope of changes, and how you will protect your data. In particular, do not treat resetting databases or regenerating SAAS_SECRET as routine upgrade steps.
For an active incident, start with Troubleshooting. For routine releases of your own application changes, follow Deployment.