Run through this checklist before applying the v2.0.0 migration scripts. Each item links to the page that explains why it matters.

• Full logical backup with pg_dump:

  ```bash
  pg_dump --no-owner --no-privileges -Fc -f cypex-pre-v2.dump cypex
  ```
  

• Filesystem snapshot of the PostgreSQL data directory, if your infrastructure supports it.

This page lists the upgrade scenarios that were exercised against the v2.0.0 migration scripts, the result of each, and the explicit answer to the most common question: does RLS change row visibility for existing single-tenant data?

Info

No. RLS does not change row visibility for existing single-tenant data. All existing rows remain visible to all existing users after the upgrade.

The mechanism is described in detail on RLS impact on existing data. The short version: the upgrade creates a Default Organization, maps every existing role to it, and the RLS policies explicitly allow organization_id IS NULL rows to be visible. Existing single-tenant data therefore continues to be readable.

This page answers the most common question about the v2.0.0 upgrade:

Info

Does enabling RLS change row visibility for existing single-tenant data?

No. Existing single-tenant data remains visible to all existing users after the upgrade. The migration is designed so that the transition from v1.x to v2.0.0 is transparent for end users at the row-visibility level.

This page describes the v2.0.0 role model and how roles, JWTs, and RLS policies work together to enforce multi-tenant isolation.

All three roles are created as NOLOGIN group roles. Humans (and the authenticator pool) log in as other roles that are granted membership in these groups — they never LOGIN as cypex_admin, cypex_user, or organization_admin themselves.

The v2.0.0 upgrade installs a default password policy by inserting a row into cypex.t_config with key password_policy. This page documents the policy, how to verify it on your instance, and how to override it.

The migration inserts:

1
2
3
4
5
6
7

{
  "minLength": 4,
  "minUppercase": 0,
  "minLowercase": 0,
  "minNumbers": 0,
  "minSpecial": 0
}

This is very permissive by design. The rationale is that shipping a working default is preferable to locking existing users out at upgrade time. Once the upgrade is complete, administrators should review the policy and tighten it to match their security requirements.

The v2.0.0 migrations are forward-only. There is no automatic rollback script. This page documents what you can and cannot undo if you need to revert the upgrade.

For every table that had RLS enabled by the v2.0.0 upgrade:

Info

Looking for the conceptual reference (“what is an Organization?”)? See Organizations.

After the v2.0.0 upgrade, every CYPEX deployment starts with a single Default Organization that holds all existing data. This page is the entry point for setting up additional organizations and assigning existing clients / schemas to them.

• You want to split a single-tenant deployment into multiple organizations (one per client, per business unit, or per environment).
• You need to backfill the organization_id column on existing application-schema tables.
• You are operating the cutover from “everything on Default Organization” to “each row tagged with the right organization.”

1. Prepare the existing database — pre-flight checks, downtime planning, smoke-test environment.
2. Enable RLS — the SQL primitives for enabling and configuring RLS on application-schema tables.
3. Assign clients to organizations — uses the client-add-organization-id SQL template.
4. Verify and roll back — verification queries and the rollback procedure if something goes wrong.

• Upgrading to v2.0.0 — for the upgrade-time procedure.
• RLS impact on existing data — for the visibility guarantees before you start.
• Roles and permissions — for the role model you are operating within.

• client-add-organization-id-template.sql — SQL template for adding organization_id to client application-schema tables. See Assign clients to organizations for how to customize and run it. This migration has failed in the field. Read Failure modes before production rollout.

Operator-facing upgrade guides, one per major version. Start here before deploying a new major version of CYPEX in production.

• Upgrade to v2.0.0 — the mandatory upgrade entry point for v2.0.0: pre-upgrade checklist, breaking changes, RLS impact, SSO migration, Organizations migration, Connectors enablement, post-upgrade verification, and rollback constraints.

• Migrations — the technical reference and step-by-step migration walkthroughs that this guide links out to.
• Release Management — for per-application version control on top of an upgraded platform.

This section contains upgrade guides for CYPEX administrators, DBAs, and operations engineers. Use these guides when moving an existing CYPEX deployment from one major version to the next, especially when the upgrade involves schema or permission-model changes.

From v2.0.0 onward, multi-tenant isolation is a database property: PostgreSQL Row-Level Security (RLS) scopes every query. Application-layer filters are not the security boundary.

The guides are written with factual upgrade behavior in mind: what the migrations actually do, what is additive, what is breaking, what is behavior-changing, and what the rollback constraints are.