refactor: database interaction and error handling (#10762)

This pull request introduces a significant refactoring of the database
interaction layer, focusing on improving explicitness, transactional
control, and error handling. The core change is the removal of the
stateful `QueryExecutor` from repository instances. Instead, it is now
passed as an argument to each method that interacts with the database.

This change makes transaction management more explicit and flexible, as
the same repository instance can be used with a database pool or a
specific transaction without needing to be re-instantiated.

### Key Changes

- **Explicit `QueryExecutor` Passing:**
- All repository methods (`Get`, `List`, `Create`, `Update`, `Delete`,
etc.) in `InstanceRepository`, `OrganizationRepository`,
`UserRepository`, and their sub-repositories now require a
`database.QueryExecutor` (e.g., a `*pgxpool.Pool` or `pgx.Tx`) as the
first argument.
- Repository constructors no longer accept a `QueryExecutor`. For
example, `repository.InstanceRepository(pool)` is now
`repository.InstanceRepository()`.

- **Enhanced Error Handling:**
- A new `database.MissingConditionError` is introduced to enforce
required query conditions, such as ensuring an `instance_id` is always
present in `UPDATE` and `DELETE` operations.
- The database error wrapper in the `postgres` package now correctly
identifies and wraps `pgx.ErrTooManyRows` and similar errors from the
`scany` library into a `database.MultipleRowsFoundError`.

- **Improved Database Conditions:**
- The `database.Condition` interface now includes a
`ContainsColumn(Column) bool` method. This allows for runtime checks to
ensure that critical filters (like `instance_id`) are included in a
query, preventing accidental cross-tenant data modification.
- A new `database.Exists()` condition has been added to support `EXISTS`
subqueries, enabling more complex filtering logic, such as finding an
organization that has a specific domain.

- **Repository and Interface Refactoring:**
- The method for loading related entities (e.g., domains for an
organization) has been changed from a boolean flag (`Domains(true)`) to
a more explicit, chainable method (`LoadDomains()`). This returns a new
repository instance configured to load the sub-resource, promoting
immutability.
- The custom `OrgIdentifierCondition` has been removed in favor of using
the standard `database.Condition` interface, simplifying the API.

- **Code Cleanup and Test Updates:**
  - Unnecessary struct embeddings and metadata have been removed.
- All integration and repository tests have been updated to reflect the
new method signatures, passing the database pool or transaction object
explicitly.
- New tests have been added to cover the new `ExistsDomain`
functionality and other enhancements.

These changes make the data access layer more robust, predictable, and
easier to work with, especially in the context of database transactions.

backend/v3/storage/database/events_testing/instance_domain_test.go

@@ -21,8 +21,8 @@ import (
 func TestServer_TestInstanceDomainReduces(t *testing.T) {
 	instance := integration.NewInstance(CTX)
 
-	instanceRepo := repository.InstanceRepository(pool)
-	instanceDomainRepo := instanceRepo.Domains(true)
+	instanceRepo := repository.InstanceRepository()
+	instanceDomainRepo := repository.InstanceDomainRepository()
 
 	t.Cleanup(func() {
 		_, err := instance.Client.InstanceV2Beta.DeleteInstance(CTX, &v2beta.DeleteInstanceRequest{
@@ -36,7 +36,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 	// Wait for instance to be created
 	retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 	assert.EventuallyWithT(t, func(t *assert.CollectT) {
-		_, err := instanceRepo.Get(CTX,
+		_, err := instanceRepo.Get(CTX, pool,
 			database.WithCondition(instanceRepo.IDCondition(instance.ID())),
 		)
 		assert.NoError(t, err)
@@ -66,7 +66,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 		// Test that domain add reduces
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			domain, err := instanceDomainRepo.Get(CTX,
+			domain, err := instanceDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						instanceDomainRepo.InstanceIDCondition(instance.Instance.Id),
@@ -96,7 +96,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 
 		t.Cleanup(func() {
 			// first we change the primary domain to something else
-			domain, err := instanceDomainRepo.Get(CTX,
+			domain, err := instanceDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						instanceDomainRepo.InstanceIDCondition(instance.Instance.Id),
@@ -125,7 +125,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 		// Wait for domain to be created
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			domain, err := instanceDomainRepo.Get(CTX,
+			domain, err := instanceDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						instanceDomainRepo.InstanceIDCondition(instance.Instance.Id),
@@ -151,7 +151,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 		// Test that set primary reduces
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			domain, err := instanceDomainRepo.Get(CTX,
+			domain, err := instanceDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						instanceDomainRepo.InstanceIDCondition(instance.Instance.Id),
@@ -180,7 +180,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 		// Wait for domain to be created and verify it exists
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			_, err := instanceDomainRepo.Get(CTX,
+			_, err := instanceDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						instanceDomainRepo.InstanceIDCondition(instance.Instance.Id),
@@ -202,7 +202,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 		// Test that domain remove reduces
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			domain, err := instanceDomainRepo.Get(CTX,
+			domain, err := instanceDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						instanceDomainRepo.InstanceIDCondition(instance.Instance.Id),
@@ -241,7 +241,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 		// Test that domain add reduces
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			domain, err := instanceDomainRepo.Get(CTX,
+			domain, err := instanceDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						instanceDomainRepo.InstanceIDCondition(instance.Instance.Id),
@@ -271,7 +271,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 		// Wait for domain to be created and verify it exists
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			_, err := instanceDomainRepo.Get(CTX,
+			_, err := instanceDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						instanceDomainRepo.InstanceIDCondition(instance.Instance.Id),
@@ -293,7 +293,7 @@ func TestServer_TestInstanceDomainReduces(t *testing.T) {
 		// Test that domain remove reduces
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			domain, err := instanceDomainRepo.Get(CTX,
+			domain, err := instanceDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						instanceDomainRepo.InstanceIDCondition(instance.Instance.Id),

backend/v3/storage/database/events_testing/instance_test.go

@@ -17,7 +17,7 @@ import (
 )
 
 func TestServer_TestInstanceReduces(t *testing.T) {
-	instanceRepo := repository.InstanceRepository(pool)
+	instanceRepo := repository.InstanceRepository()
 
 	t.Run("test instance add reduces", func(t *testing.T) {
 		instanceName := gofakeit.Name()
@@ -46,7 +46,7 @@ func TestServer_TestInstanceReduces(t *testing.T) {
 
 		retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			instance, err := instanceRepo.Get(CTX,
+			instance, err := instanceRepo.Get(CTX, pool,
 				database.WithCondition(instanceRepo.IDCondition(instance.GetInstanceId())),
 			)
 			require.NoError(t, err)
@@ -92,7 +92,7 @@ func TestServer_TestInstanceReduces(t *testing.T) {
 		// check instance exists
 		retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			instance, err := instanceRepo.Get(CTX,
+			instance, err := instanceRepo.Get(CTX, pool,
 				database.WithCondition(instanceRepo.IDCondition(res.GetInstanceId())),
 			)
 			require.NoError(t, err)
@@ -110,7 +110,7 @@ func TestServer_TestInstanceReduces(t *testing.T) {
 
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			instance, err := instanceRepo.Get(CTX,
+			instance, err := instanceRepo.Get(CTX, pool,
 				database.WithCondition(instanceRepo.IDCondition(res.GetInstanceId())),
 			)
 			require.NoError(t, err)
@@ -137,7 +137,7 @@ func TestServer_TestInstanceReduces(t *testing.T) {
 		// check instance exists
 		retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			instance, err := instanceRepo.Get(CTX,
+			instance, err := instanceRepo.Get(CTX, pool,
 				database.WithCondition(instanceRepo.IDCondition(res.GetInstanceId())),
 			)
 			require.NoError(t, err)
@@ -151,7 +151,7 @@ func TestServer_TestInstanceReduces(t *testing.T) {
 
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			instance, err := instanceRepo.Get(CTX,
+			instance, err := instanceRepo.Get(CTX, pool,
 				database.WithCondition(instanceRepo.IDCondition(res.GetInstanceId())),
 			)
 			// event instance.removed

backend/v3/storage/database/events_testing/org_domain_test.go

@@ -22,8 +22,8 @@ func TestServer_TestOrgDomainReduces(t *testing.T) {
 	})
 	require.NoError(t, err)
 
-	orgRepo := repository.OrganizationRepository(pool)
-	orgDomainRepo := orgRepo.Domains(false)
+	orgRepo := repository.OrganizationRepository()
+	orgDomainRepo := repository.OrganizationDomainRepository()
 
 	t.Cleanup(func() {
 		_, err := OrgClient.DeleteOrganization(CTX, &v2beta.DeleteOrganizationRequest{
@@ -37,8 +37,13 @@ func TestServer_TestOrgDomainReduces(t *testing.T) {
 	// Wait for org to be created
 	retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 	assert.EventuallyWithT(t, func(t *assert.CollectT) {
-		_, err := orgRepo.Get(CTX,
-			database.WithCondition(orgRepo.IDCondition(org.GetId())),
+		_, err := orgRepo.Get(CTX, pool,
+			database.WithCondition(
+				database.And(
+					orgRepo.InstanceIDCondition(Instance.Instance.Id),
+					orgRepo.IDCondition(org.GetId()),
+				),
+			),
 		)
 		assert.NoError(t, err)
 	}, retryDuration, tick)
@@ -68,7 +73,7 @@ func TestServer_TestOrgDomainReduces(t *testing.T) {
 		// Test that domain add reduces
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			gottenDomain, err := orgDomainRepo.Get(CTX,
+			gottenDomain, err := orgDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						orgDomainRepo.InstanceIDCondition(Instance.Instance.Id),
@@ -107,7 +112,7 @@ func TestServer_TestOrgDomainReduces(t *testing.T) {
 		// Test that domain remove reduces
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			domain, err := orgDomainRepo.Get(CTX,
+			domain, err := orgDomainRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						orgDomainRepo.InstanceIDCondition(Instance.Instance.Id),

backend/v3/storage/database/events_testing/organization_test.go

@@ -19,7 +19,7 @@ import (
 
 func TestServer_TestOrganizationReduces(t *testing.T) {
 	instanceID := Instance.ID()
-	orgRepo := repository.OrganizationRepository(pool)
+	orgRepo := repository.OrganizationRepository()
 
 	t.Run("test org add reduces", func(t *testing.T) {
 		beforeCreate := time.Now()
@@ -42,7 +42,7 @@ func TestServer_TestOrganizationReduces(t *testing.T) {
 
 		retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(tt *assert.CollectT) {
-			organization, err := orgRepo.Get(CTX,
+			organization, err := orgRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						orgRepo.IDCondition(org.GetId()),
@@ -92,7 +92,7 @@ func TestServer_TestOrganizationReduces(t *testing.T) {
 
 		retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			organization, err := orgRepo.Get(CTX,
+			organization, err := orgRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						orgRepo.IDCondition(organization.Id),
@@ -137,7 +137,7 @@ func TestServer_TestOrganizationReduces(t *testing.T) {
 
 		retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			organization, err := orgRepo.Get(CTX,
+			organization, err := orgRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						orgRepo.IDCondition(organization.Id),
@@ -177,11 +177,11 @@ func TestServer_TestOrganizationReduces(t *testing.T) {
 		})
 		require.NoError(t, err)
 
-		orgRepo := repository.OrganizationRepository(pool)
+		orgRepo := repository.OrganizationRepository()
 		// 3. check org deactivated
 		retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			organization, err := orgRepo.Get(CTX,
+			organization, err := orgRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						orgRepo.IDCondition(organization.Id),
@@ -203,7 +203,7 @@ func TestServer_TestOrganizationReduces(t *testing.T) {
 
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			organization, err := orgRepo.Get(CTX,
+			organization, err := orgRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						orgRepo.IDCondition(organization.Id),
@@ -230,10 +230,10 @@ func TestServer_TestOrganizationReduces(t *testing.T) {
 		require.NoError(t, err)
 
 		// 2. check org retrievable
-		orgRepo := repository.OrganizationRepository(pool)
+		orgRepo := repository.OrganizationRepository()
 		retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			_, err := orgRepo.Get(CTX,
+			_, err := orgRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						orgRepo.IDCondition(organization.Id),
@@ -252,7 +252,7 @@ func TestServer_TestOrganizationReduces(t *testing.T) {
 
 		retryDuration, tick = integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
 		assert.EventuallyWithT(t, func(t *assert.CollectT) {
-			organization, err := orgRepo.Get(CTX,
+			organization, err := orgRepo.Get(CTX, pool,
 				database.WithCondition(
 					database.And(
 						orgRepo.IDCondition(organization.Id),