# Upgrade a module's data schema

Source: https://zotonic.com/docs/2962/upgrade-a-module-s-data-schema

URI: https://zotonic.com/id/2962

Language: en

Version schema changes through the module's installation and upgrade mechanism. Inspect a module using -mod_schema and manage_schema/2 before adding your own versioned step.

Version schema changes through the module's installation and upgrade mechanism. Inspect a module using `-mod_schema` and `manage_schema/2` before adding your own versioned step.

Make each step safe for the state it may encounter after a partial attempt. Separate database structure changes from long-running data conversion when a single startup transaction would be too costly.

Test a fresh install and an upgrade from the previously released schema. Keep a database backup for the upgrade test and verify application behavior after migration, not just the table definitions.

If version 1 installed the Garden fixture, change the declaration to `-mod_schema(2).` for the next release. Keep the fresh-install clause and add a `manage_schema({upgrade, 2}, Context)` clause for the version-1-to-2 change. Erlang function clauses are separated with semicolons. Do not return success for an upgrade you have not implemented.

The manager calls upgrades in sequence, within a database transaction per schema step, then applies any returned datamodel and records the version. A code reload alone is not an upgrade test: run the module activation/startup lifecycle on the test site. Use `manage_data/2` for a deliberate follow-up after schema work, or queue longer conversions. Compare fresh-install and upgraded data before release.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/2962?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/2962?language=en>)
