Data Tables in Packages
What a Package can carry, what an install provisions, and what happens on update and uninstall.
A Package can ship the shape of a Data Table — its name and its ordered typed columns — and never a row. Every install provisions the table empty, in the project you install into, and the Package's own workflows are what fill it.
There is no field anywhere in a table definition that can hold a cell, so a Package cannot carry somebody's customer records by accident. A definition that tries is refused rather than ignored.
Authoring a Package? The field-by-field reference is Data Tables in the portable-definitions spec. This page is what it means on the receiving end.
Install
Data Tables live in a project, so a Package that declares one cannot be installed at the organization level. The CLI says so before its first prompt rather than after its last, and the install wizard asks you to choose a project.
What an install does:
- creates each declared table, empty, with the declared columns in the declared order;
- points the Package's Data Table nodes at the tables it just created — a node references a table by the Package's own name for it, never by an id, and the installer rewrites that into the real id of the installed table;
- gives an Agent that reads or writes a table the table it just created — tables are provisioned before the Agents that name them;
- refuses, before writing anything, if a table name is already taken in the target project. Rename the table at install, or point the Package at the table you already have.
An install that fails part way removes the tables it created. They are empty by construction, so there is nothing to lose.
Update
A newer version of the Package may add columns to a table it already installed. The table and its rows survive, and the new columns are added in place.
Removing a column, renaming one, or changing one's type is refused, because each of those would destroy or silently reinterpret rows you already have. The whole update is refused before anything is written.
For the same reason, you cannot rename a column of a table the Package tracks while it is installed: the next update would see the declared column as removed and refuse. Uninstall the Package, keeping the table, to rename its columns.
A table the new version no longer declares is not deleted. The update leaves it standing as an ordinary table you own.
Uninstall
The Package author declares a policy per table, and it decides only one thing: whether the table is offered for removal.
| Policy | On uninstall |
|---|---|
| keep (default) | The table is not offered for removal. It stays as an ordinary Data Table you own. |
| delete | The table is offered for removal alongside the Package's other objects. |
Even under delete, the table is only removed if you explicitly ask for it — with one
exception: a Package whose entry point is the table (a Package whose whole job is to hold a
register) takes its entry point down unasked, because that is what uninstalling it means. A
keep table is never removed, entry point or not.
Hiding an installation removes nothing at all.
The default is keep because by the time you uninstall, what is in the table is your data rather than the author's structure.
Compliance
A table a Package ships is a place your records accumulate, so the Package's own compliance declaration has to cover it:
- what it holds belongs in the Package's data categories — a register of counterparties and dates is personal data whatever the workflow writing it is called;
- how long it holds it belongs in its retention statement — a table kept on uninstall is retained until you delete it yourself.
Check both on the Package's page before installing it into a project that holds customer data.