---
name: roles-schema-sync
description: When changing DB schema or permission dimensions, consider predefined roles and bucket_role / role-related code.
---

# Roles and schema / permission changes

## When to use

When changing **DB schema** (especially permission-related columns or new resource types), or when **adding/removing CRUD dimensions** for bucket admins.

## What to consider

1. **Predefined roles** are defined in code (`packages/helpers/src/bucketRoles/constants.ts`) and may need:
   - New entries (e.g. a new predefined role id and nameKey).
   - Updated bitmasks (`bucketCrud`, `bucketMessagesCrud`, `bucketAdminsCrud`) if CRUD semantics change.
   - i18n keys in apps (e.g. `roles.full`, `roles.noUpdate`) and in management-web/originals.

   Use parent-prefixed names for nested resources (e.g. `bucketMessagesCrud`); see **nested-resource-prefix-naming**.

2. **Custom roles** live in schema tables (`bucket_role`, `management_admin_role`). Adding columns or changing CRUD semantics may require:
   - Migrations and init SQL updates together (keep both in sync):
     - Main DB: `infra/k8s/base/db/source/app/0001_app_schema.sql` (canonical)
     - Management DB: `infra/k8s/base/db/source/management/0001_management_schema.sql` (canonical)
   - ORM entity and `BucketRoleService` updates.
   - Management-api schemas (Joi), controller, and OpenAPI updates.
   - Helpers-requests types and API helpers.

3. **UI** that lists or applies roles (dropdowns, Roles tab, role create/edit forms) may need to:
   - Reflect new permission dimensions or labels.
   - Update CrudCheckboxes or role option shapes if CRUD bits change.

## Key files

- Predefined: `packages/helpers/src/bucketRoles/constants.ts`
- DB (main): `infra/k8s/base/db/source/app/0001_app_schema.sql`
- DB (management): `infra/k8s/base/db/source/management/0001_management_schema.sql`
- ORM: `packages/orm` (BucketRole entity, BucketRoleService)
- API: `apps/management-api` (bucket roles routes, controller, schemas)
- Client: `packages/helpers-requests` (bucket roles), `packages/ui` (BucketAdminsView, EditBucketAdminForm, BucketSettingsTabs)