fix(eventstore): add owners to unique constraints (#12740)

# Which Problems Are Solved Bulk unique-constraint deletes (org, IDP with many links, user, project) reconstruct every uniqueness key in Go and emit N `DELETE`s. That can OOM on large tenants. A one-shot owner backfill is also not enough: during a rolling deploy, older binaries still insert `owners = '{}'`, so a later owner-only delete would miss those rows. Owner-only org/user/grant delete only matches rows whose `owners` bag contains that tag. Several grant and member types stamped the aggregate resource owner, which is not always the user’s home org or the granted org. Username-scope rewrites also dropped `user:` tags, so owner-only user delete could miss rewritten username rows. Command must not switch to owner-only delete on the first 79 of a version, because leftover `'{}'` rows from rolling-update overlap are only backfilled on a later 79. A failed 79 must not turn owner-delete on, and backfill joins must not stamp the wrong org (unverified domains, org-scoped usernames colliding with instance-scoped ones). # How the Problems Are Solved Uniqueness stays the existing primary key `(instance_id, unique_type, unique_field)`. `owners` is only a lifecycle bag of tags (`org:<id>`, `user:<id>`, `idp:<id>`, `project:<id>`, `grant:<id>`). - Add `owners TEXT[] NOT NULL DEFAULT '{}'` on `eventstore.unique_constraints` (init SQL for greenfield, setup 78 for existing clusters). - Create `unique_constraints_owners_gin` with `CREATE INDEX CONCURRENTLY` **outside a transaction** (same pattern as step 76). Built-in `GIN (owners)` only; no `btree_gin`. - Stamp `WithOwners` on **add** events. Field-level removes ignore owners. `RemoveByOwner` stores the tag in `Owners` and both v1/v3 and v2 pushers run `DELETE … WHERE instance_id = $1 AND owners @> ARRAY[$tag]::text[]`. - Setup 79 backfills `owners` from projections via numbered `cmd/setup/79/*.sql` files. Table names are interpolated from `internal/query/projection` constants. Matches use `unique_field IN (x, lower(x))` so the primary key can be used. Missing projection tables (`42P01`) are skipped. - Org domains are tagged only when `is_verified`. Instance-scoped usernames join only users that are not org-scoped (organization settings or domain policy `user_login_must_be_domain`). Every username row still gets `org:` + `user:` of that user. - 79 is a **repeatable** migration. `Check` re-runs when `lastRun["version"]` changed or when setup-only `ForceFinalize` is set and `lastRun["finalized"]` is still false. `Finalized` is written only after Execute succeeds. - Failed setup events keep the last successful `lastRun`. Command reads `finalized` only from `system.migration.repeatable.done`. - Org / user / project remove skip N-key event replay **when that `finalized` bit is true**. Otherwise they keep today’s N-key lists **and** still emit `RemoveByOwner`. The “ready” result is cached in memory once true. Setup writes `finalized` on the 79 repeatable.done payload: - First 79 of a version: backfill only, `finalized=false` (unless `ForceFinalize` is already set). - Later 79: version change or `BackfillUniqueConstraintOwners.ForceFinalize` / `ZITADEL_BACKFILLUNIQUECONSTRAINTOWNERS_FORCEFINALIZE` after the rolling update is done. That run backfills leftovers and writes `finalized=true`. Member and grant owner bags now include every org that should delete the row: - Instance, org, and project members also stamp `org:<user_resource_owner>`. - User grants stamp grant, user, project, and granted orgs. - Project grant members stamp the project org, user org, and granted org. - Project grants stamp both orgs plus `grant:<id>`. Grant remove emits `RemoveByOwner(grant)`. - Username-scope rewrites keep `user:<id>` as well as `org:`. - User/grant orgs are carried as unexported add-event fields (not persisted JSON). `WithOwners` skips empty and duplicate tags. # Additional Changes - Table-driven owner-tag tests, including project grant (two `org:` tags plus `grant:`), cross-org members, user grants, and username-scope rewrite `user:` tags. - Table-driven 79 `Check` + `finalizeAfterSuccess` tests for version change, sequential version bumps, ForceFinalize restart, and already-finalized skip. - Command tests: a failed 79 event with `finalized=true` does not enable owner-delete. - Integration fixtures (verified vs unverified org domain; instance-scoped `bob` vs org-scoped `bob`). - Instance-only and global unique types stay untagged (`'{}'`). Instance wipe still uses `UniqueConstraintInstanceRemove`. - Pusher owner cases live in `eventstore_pusher_owners_test.go` so `eventstore_pusher_test.go` stays under 1k lines. # Additional Context A later cleanup can delete the N-key replay helpers once a release that ran 79 a second time (or an operator who set `ForceFinalize`) is in production. That is not required for correctness.  <div><a href="https://cursor.com/agents/bc-44f9bc9b-9a93-4cd9-8dd1-663a7b9aad2a?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-44f9bc9b-9a93-4cd9-8dd1-663a7b9aad2a&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <[email protected]> Co-authored-by: Silvan <[email protected]>
2026-11-05 22:02:15 +00:00 · 2026-09-18 15:08:42 +02:00
parent 9e1b85fa91
commit 3ff4fbc7e4
95 changed files with 2411 additions and 207 deletions
@@ -0,0 +1,285 @@
+package eventstore_test
+
+import (
+	"context"
+	"database/sql"
+	"testing"
+
+	"github.com/zitadel/zitadel/internal/database"
+	"github.com/zitadel/zitadel/internal/eventstore"
+	"github.com/zitadel/zitadel/internal/zerrors"
+)
+
+func TestEventstore_Push_UniqueConstraintOwners(t *testing.T) {
+	for pusherName, pusher := range pushers {
+		t.Run(pusherName, func(t *testing.T) {
+			runUniqueConstraintOwnerCases(t, pusher, clients[pusherName])
+		})
+	}
+}
+
+func runUniqueConstraintOwnerCases(t *testing.T, pusher eventstore.Pusher, client *database.DB) {
+	t.Helper()
+	db := eventstore.NewEventstore(&eventstore.Config{
+		Querier: queriers["v2(inmemory)"],
+		Pusher:  pusher,
+	})
+	const instanceID = "owners-instance"
+	for _, tc := range uniqueConstraintOwnerCases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Cleanup(cleanupEventstore(client))
+			tc.run(t, db, client, instanceID)
+		})
+	}
+}
+
+type uniqueConstraintOwnerCase struct {
+	name string
+	run  func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string)
+}
+
+var uniqueConstraintOwnerCases = []uniqueConstraintOwnerCase{
+	{
+		name: "add stores owners",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			_, err := db.Push(context.Background(), generateCommand("owners-add", "1",
+				withInstanceID(instanceID),
+				generateAddUniqueConstraint("usernames", "alice", "org:org-1", "user:user-1"),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertOwners(t, client, instanceID, "usernames", "alice", []string{"org:org-1", "user:user-1"})
+		},
+	},
+	{
+		name: "omit owners stores empty",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			_, err := db.Push(context.Background(), generateCommand("owners-empty", "1",
+				withInstanceID(instanceID),
+				generateAddUniqueConstraint("usernames", "bob"),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertOwners(t, client, instanceID, "usernames", "bob", nil)
+		},
+	},
+	{
+		name: "add duplicate already exists",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			cmd := func() eventstore.Command {
+				return generateCommand("owners-dup", "1",
+					withInstanceID(instanceID),
+					generateAddUniqueConstraint("usernames", "alice", "org:org-1"),
+				)
+			}
+			if _, err := db.Push(context.Background(), cmd()); err != nil {
+				t.Fatal(err)
+			}
+			_, err := db.Push(context.Background(), cmd())
+			if !zerrors.IsErrorAlreadyExists(err) {
+				t.Fatalf("expected already exists, got %v", err)
+			}
+		},
+	},
+	{
+		name: "remove by field case insensitive",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			if err := insertUniqueConstraint(client, instanceID, "usernames", "mixedcase", "org:org-1"); err != nil {
+				t.Fatal(err)
+			}
+			_, err := db.Push(context.Background(), generateCommand("owners-field-remove", "1",
+				withInstanceID(instanceID),
+				generateRemoveUniqueConstraint("usernames", "MixedCase"),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertUniqueCount(t, client, instanceID, 0)
+		},
+	},
+	{
+		name: "remove by owner org",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			if err := insertUniqueConstraint(client, instanceID, "usernames", "alice", "org:org-x", "user:u1"); err != nil {
+				t.Fatal(err)
+			}
+			if err := insertUniqueConstraint(client, instanceID, "usernames", "bob", "org:org-y", "user:u2"); err != nil {
+				t.Fatal(err)
+			}
+			_, err := db.Push(context.Background(), generateCommand("owners-org-remove", "1",
+				withInstanceID(instanceID),
+				generateRemoveUniqueConstraintsByOwner(eventstore.UniqueConstraintOwnerOrg, "org-x"),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertUniqueCount(t, client, instanceID, 1)
+			assertOwners(t, client, instanceID, "usernames", "bob", []string{"org:org-y", "user:u2"})
+		},
+	},
+	{
+		name: "remove by owner user",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			if err := insertUniqueConstraint(client, instanceID, "usernames", "alice", "org:org-1", "user:u1"); err != nil {
+				t.Fatal(err)
+			}
+			if err := insertUniqueConstraint(client, instanceID, "external_idps", "idp1ext1", "org:org-1", "idp:idp1", "user:u1"); err != nil {
+				t.Fatal(err)
+			}
+			if err := insertUniqueConstraint(client, instanceID, "usernames", "bob", "org:org-1", "user:u2"); err != nil {
+				t.Fatal(err)
+			}
+			_, err := db.Push(context.Background(), generateCommand("owners-user-remove", "1",
+				withInstanceID(instanceID),
+				generateRemoveUniqueConstraintsByOwner(eventstore.UniqueConstraintOwnerUser, "u1"),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertUniqueCount(t, client, instanceID, 1)
+			assertOwners(t, client, instanceID, "usernames", "bob", []string{"org:org-1", "user:u2"})
+		},
+	},
+	{
+		name: "remove by owner idp",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			if err := insertUniqueConstraint(client, instanceID, "external_idps", "idp1ext1", "org:org-1", "idp:idp-1", "user:u1"); err != nil {
+				t.Fatal(err)
+			}
+			if err := insertUniqueConstraint(client, instanceID, "external_idps", "idp2ext2", "org:org-1", "idp:idp-2", "user:u2"); err != nil {
+				t.Fatal(err)
+			}
+			_, err := db.Push(context.Background(), generateCommand("owners-idp-remove", "1",
+				withInstanceID(instanceID),
+				generateRemoveUniqueConstraintsByOwner(eventstore.UniqueConstraintOwnerIDP, "idp-1"),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertUniqueCount(t, client, instanceID, 1)
+			assertOwners(t, client, instanceID, "external_idps", "idp2ext2", []string{"org:org-1", "idp:idp-2", "user:u2"})
+		},
+	},
+	{
+		name: "two org tags either org deletes grant",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			if err := insertUniqueConstraint(client, instanceID, "project_grant", "granted:project", "org:granting", "org:granted", "project:project"); err != nil {
+				t.Fatal(err)
+			}
+			_, err := db.Push(context.Background(), generateCommand("owners-grant-org", "1",
+				withInstanceID(instanceID),
+				generateRemoveUniqueConstraintsByOwner(eventstore.UniqueConstraintOwnerOrg, "granted"),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertUniqueCount(t, client, instanceID, 0)
+		},
+	},
+	{
+		name: "instance remove deletes tagged rows",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			if err := insertUniqueConstraint(client, instanceID, "usernames", "alice", "org:org-1"); err != nil {
+				t.Fatal(err)
+			}
+			if err := insertUniqueConstraint(client, "other", "usernames", "alice", "org:org-1"); err != nil {
+				t.Fatal(err)
+			}
+			_, err := db.Push(context.Background(), generateCommand("owners-instance-remove", "1",
+				withInstanceID(instanceID),
+				generateRemoveInstanceUniqueConstraints(),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertUniqueCount(t, client, instanceID, 0)
+			assertUniqueCount(t, client, "other", 1)
+		},
+	},
+	{
+		name: "global and empty owners not deleted by owner",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			if err := insertUniqueConstraint(client, "", "instance_domain", "example.com"); err != nil {
+				t.Fatal(err)
+			}
+			if err := insertUniqueConstraint(client, instanceID, "usernames", "untagged"); err != nil {
+				t.Fatal(err)
+			}
+			if err := insertUniqueConstraint(client, instanceID, "usernames", "tagged", "org:org-1"); err != nil {
+				t.Fatal(err)
+			}
+			_, err := db.Push(context.Background(), generateCommand("owners-skip-empty", "1",
+				withInstanceID(instanceID),
+				generateRemoveUniqueConstraintsByOwner(eventstore.UniqueConstraintOwnerOrg, "org-1"),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertUniqueCount(t, client, "", 1)
+			assertUniqueCount(t, client, instanceID, 1)
+			assertOwners(t, client, instanceID, "usernames", "untagged", nil)
+		},
+	},
+	{
+		name: "mixed batch deletes then inserts",
+		run: func(t *testing.T, db *eventstore.Eventstore, client *database.DB, instanceID string) {
+			if err := insertUniqueConstraint(client, instanceID, "usernames", "old", "org:org-1"); err != nil {
+				t.Fatal(err)
+			}
+			if err := insertUniqueConstraint(client, instanceID, "org_name", "acme", "org:org-1"); err != nil {
+				t.Fatal(err)
+			}
+			_, err := db.Push(context.Background(), generateCommand("owners-mixed", "1",
+				withInstanceID(instanceID),
+				generateAddUniqueConstraint("usernames", "new", "org:org-1", "user:u1"),
+				generateRemoveUniqueConstraint("usernames", "old"),
+				generateRemoveUniqueConstraintsByOwner(eventstore.UniqueConstraintOwnerOrg, "org-1"),
+			))
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertUniqueCount(t, client, instanceID, 1)
+			assertOwners(t, client, instanceID, "usernames", "new", []string{"org:org-1", "user:u1"})
+		},
+	},
+}
+
+func assertUniqueCount(t *testing.T, db *database.DB, instanceID string, want int) {
+	t.Helper()
+	var count int
+	err := db.QueryRow(func(row *sql.Row) error {
+		return row.Scan(&count)
+	}, "SELECT COUNT(*) FROM eventstore.unique_constraints WHERE instance_id = $1", instanceID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if count != want {
+		t.Errorf("unique count = %d, want %d", count, want)
+	}
+}
+
+func assertOwners(t *testing.T, db *database.DB, instanceID, uniqueType, uniqueField string, want []string) {
+	t.Helper()
+	var owners database.TextArray[string]
+	err := db.QueryRow(func(row *sql.Row) error {
+		return row.Scan(&owners)
+	}, "SELECT owners FROM eventstore.unique_constraints WHERE instance_id = $1 AND unique_type = $2 AND unique_field = $3", instanceID, uniqueType, uniqueField)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(owners) != len(want) {
+		t.Fatalf("owners = %v, want %v", []string(owners), want)
+	}
+	got := map[string]int{}
+	for _, owner := range owners {
+		got[owner]++
+	}
+	for _, owner := range want {
+		if got[owner] == 0 {
+			t.Fatalf("owners = %v, want %v", []string(owners), want)
+		}
+		got[owner]--
+	}
+}
@@ -206,19 +206,23 @@ func canceledCtx() context.Context {
 	return ctx
 }

-func fillUniqueData(unique_type, field, instanceID string) error {
-	_, err := testClient.Exec("INSERT INTO eventstore.unique_constraints (unique_type, unique_field, instance_id) VALUES ($1, $2, $3)", unique_type, field, instanceID)
+func fillUniqueData(unique_type, field, instanceID string, owners ...string) error {
+	return insertUniqueConstraint(testClient, instanceID, unique_type, field, owners...)
+}
+
+func insertUniqueConstraint(db *database.DB, instanceID, uniqueType, uniqueField string, owners ...string) error {
+	if len(owners) == 0 {
+		_, err := db.Exec("INSERT INTO eventstore.unique_constraints (instance_id, unique_type, unique_field) VALUES ($1, $2, $3)", instanceID, uniqueType, uniqueField)
+		return err
+	}
+	_, err := db.Exec("INSERT INTO eventstore.unique_constraints (instance_id, unique_type, unique_field, owners) VALUES ($1, $2, $3, $4)", instanceID, uniqueType, uniqueField, database.TextArray[string](owners))
 	return err
 }

-func generateAddUniqueConstraint(table, uniqueField string) func(e *testEvent) {
+func generateAddUniqueConstraint(table, uniqueField string, owners ...string) func(e *testEvent) {
 	return func(e *testEvent) {
 		e.uniqueConstraints = append(e.uniqueConstraints,
-			&eventstore.UniqueConstraint{
-				UniqueType:  table,
-				UniqueField: uniqueField,
-				Action:      eventstore.UniqueConstraintAdd,
-			},
+			eventstore.NewAddEventUniqueConstraint(table, uniqueField, "").WithOwners(owners...),
 		)
 	}
 }
@@ -235,6 +239,24 @@ func generateRemoveUniqueConstraint(table, uniqueField string) func(e *testEvent
 	}
 }

+func generateRemoveInstanceUniqueConstraints() func(e *testEvent) {
+	return func(e *testEvent) {
+		e.uniqueConstraints = append(e.uniqueConstraints, eventstore.NewRemoveInstanceUniqueConstraints())
+	}
+}
+
+func generateRemoveUniqueConstraintsByOwner(kind, id string) func(e *testEvent) {
+	return func(e *testEvent) {
+		e.uniqueConstraints = append(e.uniqueConstraints, eventstore.NewRemoveUniqueConstraintsByOwner(kind, id))
+	}
+}
+
+func withInstanceID(instanceID string) func(e *testEvent) {
+	return func(e *testEvent) {
+		e.Agg.InstanceID = instanceID
+	}
+}
+
 func withEventType(eventType eventstore.EventType) func(e *testEvent) {
 	return func(e *testEvent) {
 		e.EventType = eventType
@@ -11,6 +11,8 @@ type UniqueConstraint struct {
 	ErrorMessage string
 	// IsGlobal defines if the unique constraint is globally unique or just within a single instance
 	IsGlobal bool
+	// Owners is a bag of kind:id tags used for bulk lifecycle deletes
+	Owners []string
 }

 type UniqueConstraintAction int8
@@ -19,14 +21,70 @@ const (
 	UniqueConstraintAdd UniqueConstraintAction = iota
 	UniqueConstraintRemove
 	UniqueConstraintInstanceRemove
+	UniqueConstraintRemoveByOwner

 	uniqueConstraintActionCount
 )

+const (
+	UniqueConstraintOwnerOrg     = "org"
+	UniqueConstraintOwnerUser    = "user"
+	UniqueConstraintOwnerIDP     = "idp"
+	UniqueConstraintOwnerProject = "project"
+	UniqueConstraintOwnerGrant   = "grant"
+
+	// UniqueConstraintOwnersBackfillStep is the setup migration that stamps owners from projections.
+	UniqueConstraintOwnersBackfillStep = "79_backfill_unique_constraint_owners"
+)
+
+// UniqueTypesWithOwners are unique_types that live writes and setup 79 stamp with owner tags.
+// Instance mail_text shares unique_type "mail_text" but stays empty by design, so it is omitted.
+var UniqueTypesWithOwners = []string{
+	"usernames",
+	"external_idps",
+	"org_name",
+	"org_domain",
+	"project_names",
+	"appname",
+	"project_role",
+	"entity_ids",
+	"project_grant",
+	"project_grant_member",
+	"user_grant",
+	"member",
+	"group_name",
+	"action_names",
+	"idp_config_names",
+}
+
 func (f UniqueConstraintAction) Valid() bool {
 	return f >= 0 && f < uniqueConstraintActionCount
 }

+func OwnerTag(kind, id string) string {
+	if kind == "" || id == "" {
+		return ""
+	}
+	return kind + ":" + id
+}
+
+func (u *UniqueConstraint) WithOwners(tags ...string) *UniqueConstraint {
+	owners := make([]string, 0, len(tags))
+	seen := make(map[string]struct{}, len(tags))
+	for _, tag := range tags {
+		if tag == "" {
+			continue
+		}
+		if _, ok := seen[tag]; ok {
+			continue
+		}
+		seen[tag] = struct{}{}
+		owners = append(owners, tag)
+	}
+	u.Owners = owners
+	return u
+}
+
 func NewAddEventUniqueConstraint(
 	uniqueType,
 	uniqueField,
@@ -36,6 +94,7 @@ func NewAddEventUniqueConstraint(
 		UniqueField:  uniqueField,
 		ErrorMessage: errMessage,
 		Action:       UniqueConstraintAdd,
+		Owners:       []string{},
 	}
 }

@@ -55,6 +114,16 @@ func NewRemoveInstanceUniqueConstraints() *UniqueConstraint {
 	}
 }

+func NewRemoveUniqueConstraintsByOwner(kind, id string) *UniqueConstraint {
+	constraint := &UniqueConstraint{
+		Action: UniqueConstraintRemoveByOwner,
+	}
+	if tag := OwnerTag(kind, id); tag != "" {
+		constraint.Owners = []string{tag}
+	}
+	return constraint
+}
+
 func NewAddGlobalUniqueConstraint(
 	uniqueType,
 	uniqueField,
@@ -65,6 +134,7 @@ func NewAddGlobalUniqueConstraint(
 		ErrorMessage: errMessage,
 		IsGlobal:     true,
 		Action:       UniqueConstraintAdd,
+		Owners:       []string{},
 	}
 }

@@ -0,0 +1,74 @@
+package eventstore
+
+import "testing"
+
+func TestOwnerTag(t *testing.T) {
+	tests := []struct {
+		name string
+		kind string
+		id   string
+		want string
+	}{
+		{name: "org", kind: UniqueConstraintOwnerOrg, id: "123", want: "org:123"},
+		{name: "empty id", kind: UniqueConstraintOwnerOrg, id: "", want: ""},
+		{name: "empty kind", kind: "", id: "123", want: ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := OwnerTag(tt.kind, tt.id); got != tt.want {
+				t.Errorf("OwnerTag() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestUniqueConstraintAction_Valid(t *testing.T) {
+	if !UniqueConstraintAdd.Valid() {
+		t.Error("UniqueConstraintAdd should be valid")
+	}
+	if !UniqueConstraintRemove.Valid() {
+		t.Error("UniqueConstraintRemove should be valid")
+	}
+	if !UniqueConstraintInstanceRemove.Valid() {
+		t.Error("UniqueConstraintInstanceRemove should be valid")
+	}
+	if !UniqueConstraintRemoveByOwner.Valid() {
+		t.Error("UniqueConstraintRemoveByOwner should be valid")
+	}
+	if uniqueConstraintActionCount.Valid() {
+		t.Error("uniqueConstraintActionCount should be invalid")
+	}
+}
+
+func TestUniqueConstraint_WithOwners(t *testing.T) {
+	got := NewAddEventUniqueConstraint("usernames", "alice", "err").WithOwners(
+		OwnerTag(UniqueConstraintOwnerOrg, "org1"),
+		"",
+		OwnerTag(UniqueConstraintOwnerUser, "user1"),
+		OwnerTag(UniqueConstraintOwnerOrg, "org1"),
+	)
+	if len(got.Owners) != 2 || got.Owners[0] != "org:org1" || got.Owners[1] != "user:user1" {
+		t.Errorf("unexpected owners: %#v", got.Owners)
+	}
+	remove := NewRemoveUniqueConstraintsByOwner(UniqueConstraintOwnerOrg, "org1")
+	if remove.Action != UniqueConstraintRemoveByOwner {
+		t.Error("expected UniqueConstraintRemoveByOwner")
+	}
+	if len(remove.Owners) != 1 || remove.Owners[0] != "org:org1" {
+		t.Errorf("unexpected remove owners: %#v", remove.Owners)
+	}
+	if empty := NewRemoveUniqueConstraintsByOwner("", "org1"); len(empty.Owners) != 0 {
+		t.Errorf("empty kind should not stamp owners: %#v", empty.Owners)
+	}
+}
+
+func TestUniqueTypesWithOwners(t *testing.T) {
+	if len(UniqueTypesWithOwners) == 0 {
+		t.Fatal("UniqueTypesWithOwners must not be empty")
+	}
+	for _, typ := range UniqueTypesWithOwners {
+		if typ == "mail_text" {
+			t.Fatal("mail_text must be omitted: instance rows stay empty")
+		}
+	}
+}
@@ -46,8 +46,8 @@ func handleUniqueConstraints(ctx context.Context, tx database.Transaction, comma
 			switch constraint.Action {
 			case eventstore.UniqueConstraintAdd:
 				constraint.UniqueField = strings.ToLower(constraint.UniqueField)
-				addPlaceholders = append(addPlaceholders, fmt.Sprintf("($%d, $%d, $%d)", len(addArgs)+1, len(addArgs)+2, len(addArgs)+3))
-				addArgs = append(addArgs, instanceID, constraint.UniqueType, constraint.UniqueField)
+				addPlaceholders = append(addPlaceholders, fmt.Sprintf("($%d, $%d, $%d, $%d)", len(addArgs)+1, len(addArgs)+2, len(addArgs)+3, len(addArgs)+4))
+				addArgs = append(addArgs, instanceID, constraint.UniqueType, constraint.UniqueField, constraint.Owners)
 				addConstraints[fmt.Sprintf(uniqueConstraintPlaceholderFmt, instanceID, constraint.UniqueType, constraint.UniqueField)] = constraint
 			case eventstore.UniqueConstraintRemove:
 				deletePlaceholders = append(deletePlaceholders, fmt.Sprintf(deleteConstraintPlaceholdersStmt, len(deleteArgs)+1, len(deleteArgs)+2, len(deleteArgs)+3))
@@ -57,6 +57,14 @@ func handleUniqueConstraints(ctx context.Context, tx database.Transaction, comma
 				deletePlaceholders = append(deletePlaceholders, fmt.Sprintf("(instance_id = $%d)", len(deleteArgs)+1))
 				deleteArgs = append(deleteArgs, instanceID)
 				deleteConstraints[fmt.Sprintf(uniqueConstraintPlaceholderFmt, instanceID, constraint.UniqueType, constraint.UniqueField)] = constraint
+			case eventstore.UniqueConstraintRemoveByOwner:
+				if len(constraint.Owners) == 0 {
+					continue
+				}
+				tag := constraint.Owners[0]
+				deletePlaceholders = append(deletePlaceholders, fmt.Sprintf("(instance_id = $%d AND owners @> ARRAY[$%d]::text[])", len(deleteArgs)+1, len(deleteArgs)+2))
+				deleteArgs = append(deleteArgs, instanceID, tag)
+				deleteConstraints[fmt.Sprintf("%s:%s", instanceID, tag)] = constraint
 			}
 		}
 	}
@@ -2,5 +2,6 @@ INSERT INTO eventstore.unique_constraints (
    instance_id
    , unique_type
    , unique_field
+    , owners
 ) VALUES 
-    %s
+    %s