CustomModel schema change behavior

[mjfortier]

Hi there!

Our team is starting to test the use of CustomModels and ModelExtensions. We wanted to know what behavior to expect on schema change? If for example we add a column and push the plugin, what effect will it have on existing data in those tables?

Thanks!

[rmagier1]

Hi @mjfortier

Great question — schema evolution behaves differently for CustomModels (which back real database tables) versus ModelExtensions (which don't), so I'll cover each.

CustomModels

Custom Data uses a deliberately simplified, additive schema system rather than a full Django-style migration framework. The guiding principle is safe, non-destructive changes only — operations that could trigger an expensive table rewrite or risk existing data are simply not performed.

For your specific question — adding a column and pushing the plugin:

• The new column is added to the existing table (the runner issues ALTER TABLE ... ADD COLUMN IF NOT EXISTS).
• Your existing data is untouched. Existing rows are preserved exactly as they were.
• The new column is nullable with no default, so existing rows get NULL for that column. (No defaults are applied specifically to avoid a full-table rewrite.)
• If you need values backfilled for existing rows, you do that yourself in plugin code after deploying.

Here's the full support matrix for schema changes on CustomModels:

Operation	Supported?	Behavior
Create model (new table)	✅ Yes	Table created if it doesn't exist
Add field (new column)	✅ Yes	Nullable column added, no default, existing data preserved
Add unique constraint	✅ Yes	Unique index created if absent. Fails if existing data has duplicates
Add index	✅ Yes	Index created if absent
Alter field (change type, length, etc.)	❌ No	Not applied. Add a new field and copy data over instead
Drop field	❌ No	The column stays in the DB; removing it from your model just means it's ignored
Drop unique constraint / index	❌ No	Removing it from the model stops enforcement in the ORM, but the DB index remains
Alter model / Drop model	❌ No	The table is left in place; rename means creating a new model and copying data

A couple of practical notes:

• One change to watch for: changing a field's type is not applied. If you, say, change an IntegerField to a DecimalField, the existing column keeps its original type — the change is silently ignored rather than migrated. The supported pattern is to add a new field and copy data across.
• During local/dev iteration, if you rename or remove models and want to clean up orphaned tables, the CLI has canvas namespace inspect, canvas namespace reset, and canvas namespace drop to manage a namespace. (In production, tables and columns are never dropped automatically.)

ModelExtensions

ModelExtensions are a different mechanism — they're proxy models over existing SDK tables (e.g. Patient, Staff, Note). They do not create or modify any database tables, so the concept of a "schema change" doesn't really apply. You can add, change, or remove an extension and push it freely without any database effect — it's purely a code-level change in your plugin. (If you attach a ForeignKey from one of your CustomModels to an SDK model, the column lives on your CustomModel's table and follows the CustomModel rules above.)

Docs

These are all documented here, which may be useful as your team ramps up:

• CustomModel lifecycle & schema-change matrix: https://docs.canvasmedical.com/sdk/custom-data-custom-models/
• Namespace lifecycle & CLI cleanup commands: https://docs.canvasmedical.com/sdk/custom-data-namespace-lifecycle/
• Extending SDK models (ModelExtensions): https://docs.canvasmedical.com/sdk/custom-data-extending-sdk-models/
• Design considerations (when to use CustomModel vs. AttributeHub): https://docs.canvasmedical.com/sdk/custom-data-design-considerations/

Happy to dig into any specific scenario you have in mind — just let us know what models you're working with.