Core concepts

Entities and records

An entity is a table definition. A record is a row. Record data lives in a JSONB column, which is why adding a field does not require a migration, and why entities can evolve without downtime.

Every record has a record_id. Entities usually also carry their own business key — issue_id, component_id — which is what upsert and delete match on.

Some entities are physical tables rather than JSONB, prefixed with __: __user, __group. Records can reference them like anything else.

Configuration versus data

The sharpest line in the platform.

Configuration is structure: entities, guest code, automations, groups, share rules, senders. It is retrievable, diffable, and deployable between workspaces.

Data is records. It moves with upsert and query, never with deploy.

Users are data, not configuration

User accounts are deliberately excluded from the configuration bundle, so a deploy can never create or delete users. Seed them with polymesa upsert --entity __user.

Guest code

TypeScript you write runs sandboxed: no filesystem, no network, no Deno global. Everything reachable comes through a platform:* module. See the runtime overview.

Four kinds, by what starts them:

Kind	Runs when
Trigger	A record changes
Scheduled job	A cron schedule fires
Controller	A view calls a method
View	A user opens a page

Bulk

Triggers receive arrays. Saving one record and importing ten thousand call the same method. Code that assumes a single record still works — it just becomes ten thousand round trips.

Query once for the batch, build a Map, then loop.

Identity and sharing

Guest code runs as the user who triggered it. Plain sql is filtered by row-level security, so it only sees what that user may see. Scheduled jobs have no triggering user and run as the built-in SYSTEM account.

sql.systemMode bypasses that filtering entirely. It exists for work with no user context, and it is the one place a mistake becomes a data leak.

Tip

The default is safe. If you find yourself reaching for systemMode to make something work, first check whether the sharing rules are what is actually wrong.

Workspaces

A workspace is an isolated tenant with its own schema, users, and configuration. One account can belong to several. CLI commands take --workspace to act in a specific one, and credentials are stored per alias — so a single machine can address production, staging, and local without re-authenticating.

Pages

A page is a custom React view attached to an entity, either as its detail view or its create form. Pages are compiled at runtime and call controllers for data.