Breaking changes

This page lists the changes in CYPEX v2.0.0 that may require action on the part of operators, integrators, or end users. These are the changes you need to plan for during the upgrade.

The cypex_user role loses INSERT, UPDATE, and DELETE privileges on most tenant-scoped tables. After the upgrade, cypex_user is essentially read-only on those tables, with the exceptions listed below.

Affected tables include the core metadata tables (t_object, t_object_field, t_object_state, t_object_view, t_object_view_field, t_state_change, t_state_requirement, t_ui, t_ui_history, t_ui_release, t_object_annotation, t_text, t_query_group, t_function_metadata, t_export_job, t_import_job, t_log, t_log_api, t_permission_audit_log, t_user).

The following tables retain full CRUD for cypex_user:

• cypex.t_report
• cypex.t_file
• cypex.t_notification

If you have integrations that previously wrote directly to other tables using cypex_user credentials, those integrations will fail after the upgrade. Either:

• Move them to use cypex_admin (if they need full access), or
• Switch to the CYPEX HTTP API, which passes the caller’s claims through to PostgreSQL for every request.

The v2.0.0 backend issues and requires additional claims in every JWT:

• isOrganizationAdmin — boolean, true if the user is an org admin for at least one organization.
• isSuperAdmin — boolean, true if the user has system-admin privileges.
• organization_ids — array of organization IDs the user can access.
• org_id — the currently active organization for the request.

If your deployment validates JWTs externally (an API gateway, a reverse proxy, or a custom SSO integration), the verifier must accept these new claims. Old tokens issued by v1.x will not have them and will be rejected.

v2.0.0 introduces a new role:

1
2

CREATE ROLE organization_admin NOLOGIN;
GRANT cypex_admin TO organization_admin WITH ADMIN OPTION;

This role is NOLOGIN and is intended to be granted to existing roles that should have organization-admin scope. Membership in organization_admin is what causes is_organization_admin() to return true in SQL.

The following tables gain a new nullable organization_id column:

• cypex.t_ui
• cypex.t_notification
• cypex.t_file
• cypex.t_report
• cypex.t_query_group
• cypex.t_export_job
• cypex.t_import_job
• cypex.t_function_metadata
• cypex_log.t_log
• cypex_log.t_log_api
• cypex_log.t_permission_audit_log
• cypex_log.t_user

Existing rows have organization_id IS NULL. The migration does not backfill this column for the v2.0.0 release — backfilling is a per-deployment step described in Detailed organization setup.

If you have custom SQL views or reports that explicitly list every column (SELECT col1, col2, ... rather than SELECT *), they will keep working, but the new column will not appear in their result set.

PostgreSQL Row-Level Security is now enabled on every tenant-scoped table. This means:

• Direct SELECT, INSERT, UPDATE, DELETE against these tables is filtered by RLS policies.
• The active organization is read from the org_id claim on the request.jwt.claims GUC. Sessions that do not set that GUC have no active organization.
• Ad-hoc psql sessions as a non-superuser will see only rows matching the policies.

PostgreSQL superusers bypass RLS by default. If your deployment uses the database superuser for anything other than migrations, queries will ignore RLS unless FORCE ROW LEVEL SECURITY is set on the table. The default-on RLS relies on the backend never connecting as a superuser for application traffic — only for migrations.

The v2.0.0 upgrade’s RLS-enablement migration revokes broad INSERT/UPDATE/DELETE from cypex_user on the tenant-scoped tables and grants them only to cypex_admin. cypex_admin retains full access because every policy admits sessions where cypex.is_admin() is true (JWT isSuperAdmin). That is not a PostgreSQL BYPASSRLS attribute — only a superuser bypasses policies outright.

If you have custom roles that previously inherited broad write access from cypex_user, you need to explicitly grant the required privileges after the upgrade.

For the operational checklist, see Pre-upgrade checklist. For what you can and cannot undo, see Rollback constraints.