This issue is part of the AI Catalog Group Inheritance Epic https://gitlab.com/groups/gitlab-org/-/work_items/22487 see that epic for more context. ### About This is the first backend building block for group-level inheritance. It adds the database schema we need to distinguish the two kinds of enablement record and to let flow triggers belong to a group rather than a project. Two changes: 1. A new `consumer_kind` column on `ai_catalog_item_consumers`, that will be an enum to allow us to tell the existing enablement apart from the new inheritance record. All existing uses of `ai_catalog_item_consumers` will be considered type `0` (we'll call this `direct` in the model) - this includes both project and group consumers. The new group inheritance records with be type `1` (we'll call this `inheriting` in the model). 2. Group-associated flow triggers. A trigger created for an inheritance record needs to belong to a group. This makes `ai_flow_triggers.project_id` nullable, adds a `group_id`, and adds a constraint enforcing that a trigger belongs to exactly one of a project or a group. ### Proposal Schema only in this issue. Model changes (enum, validations, associations) come in the models issue. **Regular migrations** 1. Add `kind` column to `ai_catalog_item_consumers`. `smallint`, `null: false`, `default: 0`. Values: `0` = direct (all existing rows), `1` = inheriting. We keep the default until the services MR sets `kind` explicitly, otherwise existing inserts break in between. The default gets dropped in the services issue. 2. Add `group_id` column to `ai_flow_triggers` (nullable bigint) with an index on it. 3. Add foreign key `ai_flow_triggers.group_id` to `namespaces`, `on_delete: :cascade`, same as the consumers table. **Post-deploy migrations** 4. Make `ai_flow_triggers.project_id` nullable. 5. Add an "exactly one of `project_id` or `group_id`" check constraint on `ai_flow_triggers` using `add_multi_column_not_null_constraint`. This is required by the sharding key spec once we have two sharding keys, so it can't be a foll **Docs** 6. Update `db/docs/ai_catalog_item_consumers.yml` (mention `kind`) and yml` (add `group_id: namespaces` as second sharding key, note`project_id` can be null). **Out of scope** - Dropping the `kind` default and adding the Rails enum (services issue). - Any model, factory or spec changes. ### :robot: Agent planning Please see below for the original agent plan (note this plan may not reflect latest plan): <details> <summary>Click to see thinking</summary> #### 1. Add `consumer_kind` to `ai_catalog_item_consumers` Every `ItemConsumer` will carry a kind: `direct` (value `0`) or `inheriting` (value `1`). Every existing row is a `direct` (project enablements and the legacy group service-account-holder records alike), so `0` is the correct value for all current data. We want the column to be `NOT NULL` with **no default going forward** — callers must always set the kind explicitly, so a future bug that forgets to set it fails loudly rather than silently defaulting. But you can't add a `NOT NULL` column with no default to a table that already has rows. The standard pattern is to add it with a temporary default (which backfills existing rows), then immediately drop the default: ```ruby # db/migrate/XXXXXXXXXXXXXX_add_consumer_kind_to_ai_catalog_item_consumers.rb class AddConsumerKindToAiCatalogItemConsumers < Gitlab::Database::Migration[2.3] milestone '19.4' def up add_column :ai_catalog_item_consumers, :consumer_kind, :smallint, default: 0, null: false change_column_default :ai_catalog_item_consumers, :consumer_kind, from: 0, to: nil end def down remove_column :ai_catalog_item_consumers, :consumer_kind end end ``` The table is small (`table_size: small` in `db/docs/ai_catalog_item_consumers.yml`), so a single regular migration is fine — no batched backfill needed. #### 2. Make `ai_flow_triggers.project_id` nullable Triggers currently always belong to a project. An inheriting record's trigger belongs to a group instead, so `project_id` must be allowed to be null. This is a relaxing change, so it goes in a post-deploy migration: ```ruby # db/post_migrate/XXXXXXXXXXXXXX_allow_null_project_id_on_ai_flow_triggers.rb class AllowNullProjectIdOnAiFlowTriggers < Gitlab::Database::Migration[2.3] milestone '19.4' disable_ddl_transaction! def up change_column_null :ai_flow_triggers, :project_id, true end def down # Note: will fail if any rows have a null project_id (i.e. group-scoped # triggers created after this shipped). That's expected — those are real # records we can't delete. change_column_null :ai_flow_triggers, :project_id, false end end ``` #### 3. Add `group_id` to `ai_flow_triggers` The column plus its index goes in a regular migration: ```ruby # db/migrate/XXXXXXXXXXXXXX_add_group_id_to_ai_flow_triggers.rb class AddGroupIdToAiFlowTriggers < Gitlab::Database::Migration[2.3] disable_ddl_transaction! milestone '19.4' INDEX_NAME = 'index_ai_flow_triggers_on_group_id' def up with_lock_retries do add_column :ai_flow_triggers, :group_id, :bigint, null: true, if_not_exists: true end add_concurrent_index :ai_flow_triggers, :group_id, name: INDEX_NAME end def down remove_concurrent_index_by_name :ai_flow_triggers, INDEX_NAME with_lock_retries do remove_column :ai_flow_triggers, :group_id, if_exists: true end end end ``` The foreign key to `namespaces` goes in a post-deploy migration, following the standard "add concurrent FK not-valid, then validate" pattern. Because no rows have a `group_id` yet, validation is instant: ```ruby # db/post_migrate/XXXXXXXXXXXXXX_add_fk_ai_flow_triggers_to_namespaces.rb class AddFkAiFlowTriggersToNamespaces < Gitlab::Database::Migration[2.3] milestone '19.4' disable_ddl_transaction! def up add_concurrent_foreign_key :ai_flow_triggers, :namespaces, column: :group_id, on_delete: :cascade, validate: false, reverse_lock_order: true validate_foreign_key :ai_flow_triggers, :group_id end def down remove_foreign_key_if_exists :ai_flow_triggers, :namespaces, column: :group_id, reverse_lock_order: true end end ``` #### 4. Add the "exactly one of project or group" CHECK constraint This is **required, not optional**. Making `project_id` nullable and adding `group_id` turns these into a multi-column sharding key, and our sharding rules require a constraint guaranteeing exactly one is set. Database review will not approve otherwise. `ai_catalog_item_consumers` already does exactly this (`CONSTRAINT check_0acef721fa CHECK ((num_nonnulls(group_id, project_id) = 1))`) — we copy that pattern. All existing rows have `project_id` set and `group_id` null, so they already satisfy `num_nonnulls = 1` and the constraint validates immediately. Add it in a post-deploy migration: ```ruby # db/post_migrate/XXXXXXXXXXXXXX_add_project_or_group_check_to_ai_flow_triggers.rb class AddProjectOrGroupCheckToAiFlowTriggers < Gitlab::Database::Migration[2.3] milestone '19.4' disable_ddl_transaction! CONSTRAINT_NAME = 'check_ai_flow_triggers_project_or_group' def up add_check_constraint :ai_flow_triggers, 'num_nonnulls(group_id, project_id) = 1', CONSTRAINT_NAME end def down remove_check_constraint :ai_flow_triggers, CONSTRAINT_NAME end end ``` #### 5. Update `db/docs` - `db/docs/ai_catalog_item_consumers.yml`: mention `consumer_kind` in the description. - `db/docs/ai_flow_triggers.yml`: update the description to note `project_id` may be null for group-scoped triggers; update the sharding key to list both `project_id: projects` and `group_id: namespaces` (matching how `ai_catalog_item_consumers.yml` declares two sharding keys). #### Notes / ordering - Migration timestamps must be ordered so the regular migrations (`consumer_kind`, `group_id` column+index) run before the post-deploy ones (nullability, FK, CHECK). - Run the migrations locally so `db/structure.sql` regenerates. Expect unrelated schema drift in that file from the local environment — only the `consumer_kind`, `group_id`, nullable `project_id`, FK, and CHECK lines are intended. - No model/factory/spec changes belong here beyond migration specs if warranted (the migrations have no custom data logic, so specs aren't strictly required). </details>