feat(db): adding relational instance table (#10007)

<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Don't remove any of the sections.
It is important that the commit history clearly shows what is changed
and why.
Important: By submitting a contribution you agree to the terms from our
Licensing Policy as described here:
https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
-->

# Which Problems Are Solved

Implementing Instance table to new relational database schema

# How the Problems Are Solved


The following fields must be managed in this table:

- `id`
- `name`
- `default_org_id`
- `zitadel_project_id`
- `console_client_id`
- `console_app_id`
- `default_language`
- `created_at`
- `updated_at`
- `deleted_at`

The repository must provide the following functions:

Manipulations:
- create
  - `name`
  - `default_org_id`
  - `zitadel_project_id`
  - `console_client_id`
  - `console_app_id`
  - `default_language`
- update
  - `name`
  - `default_language`
- delete

Queries:
- get returns single instance matching the criteria and pagination,
should return error if multiple instances were found
- list returns list of instances matching the criteria, pagination

Criteria are the following:
- by id

pagination:
- by created_at
- by updated_at
- by name

### instance events

The following events must be applied on the table using a projection
(`internal/query/projection`)

- `instance.added` results in create
- `instance.changed` changes the `name` field
- `instance.removed` sets the the `deleted_at` field
- `instance.default.org.set` sets the `default_org_id` field
- `instance.iam.project.set` sets the `zitadel_project_id` field
- `instance.iam.console.set` sets the `console_client_id` and
`console_app_id` fields
- `instance.default.language.set` sets the `default_language` field
- if answer is yes to discussion: `instance.domain.primary.set` sets the
`primary_domain` field

### acceptance criteria

- [x] migration is implemented and gets executed
- [x] domain interfaces are implemented and documented for service layer
- [x] repository is implemented and implements domain interface
- [x] testing
  - [x] the repository methods
  - [x] events get reduced correctly
  - [x] unique constraints

# Additional Context

- Closes https://github.com/zitadel/zitadel/issues/9935

backend/v3/storage/database/repository/instance.go

@@ -0,0 +1,275 @@
+package repository
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgconn"
+
+	"github.com/zitadel/zitadel/backend/v3/domain"
+	"github.com/zitadel/zitadel/backend/v3/storage/database"
+)
+
+var _ domain.InstanceRepository = (*instance)(nil)
+
+type instance struct {
+	repository
+}
+
+func InstanceRepository(client database.QueryExecutor) domain.InstanceRepository {
+	return &instance{
+		repository: repository{
+			client: client,
+		},
+	}
+}
+
+// -------------------------------------------------------------
+// repository
+// -------------------------------------------------------------
+
+const queryInstanceStmt = `SELECT id, name, default_org_id, iam_project_id, console_client_id, console_app_id, default_language, created_at, updated_at, deleted_at` +
+	` FROM zitadel.instances`
+
+// Get implements [domain.InstanceRepository].
+func (i *instance) Get(ctx context.Context, opts ...database.Condition) (*domain.Instance, error) {
+	var builder database.StatementBuilder
+
+	builder.WriteString(queryInstanceStmt)
+
+	// return only non deleted instances
+	opts = append(opts, database.IsNull(i.DeletedAtColumn()))
+	i.writeCondition(&builder, database.And(opts...))
+
+	return scanInstance(i.client.QueryRow(ctx, builder.String(), builder.Args()...))
+}
+
+// List implements [domain.InstanceRepository].
+func (i *instance) List(ctx context.Context, opts ...database.Condition) ([]*domain.Instance, error) {
+	var builder database.StatementBuilder
+
+	builder.WriteString(queryInstanceStmt)
+
+	// return only non deleted instances
+	opts = append(opts, database.IsNull(i.DeletedAtColumn()))
+	notDeletedCondition := database.And(opts...)
+	i.writeCondition(&builder, notDeletedCondition)
+
+	rows, err := i.client.Query(ctx, builder.String(), builder.Args()...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	return scanInstances(rows)
+}
+
+const createInstanceStmt = `INSERT INTO zitadel.instances (id, name, default_org_id, iam_project_id, console_client_id, console_app_id, default_language)` +
+	` VALUES ($1, $2, $3, $4, $5, $6, $7)` +
+	` RETURNING created_at, updated_at`
+
+// Create implements [domain.InstanceRepository].
+func (i *instance) Create(ctx context.Context, instance *domain.Instance) error {
+	var builder database.StatementBuilder
+
+	builder.AppendArgs(instance.ID, instance.Name, instance.DefaultOrgID, instance.IAMProjectID, instance.ConsoleClientID, instance.ConsoleAppID, instance.DefaultLanguage)
+	builder.WriteString(createInstanceStmt)
+
+	err := i.client.QueryRow(ctx, builder.String(), builder.Args()...).Scan(&instance.CreatedAt, &instance.UpdatedAt)
+	if err != nil {
+		var pgErr *pgconn.PgError
+		if errors.As(err, &pgErr) {
+			// constraint violation
+			if pgErr.Code == "23514" {
+				if pgErr.ConstraintName == "instances_name_check" {
+					return errors.New("instance name not provided")
+				}
+				if pgErr.ConstraintName == "instances_id_check" {
+					return errors.New("instance id not provided")
+				}
+			}
+			// duplicate
+			if pgErr.Code == "23505" {
+				if pgErr.ConstraintName == "instances_pkey" {
+					return errors.New("instance id already exists")
+				}
+			}
+		}
+	}
+	return err
+}
+
+// Update implements [domain.InstanceRepository].
+func (i instance) Update(ctx context.Context, condition database.Condition, changes ...database.Change) (int64, error) {
+	var builder database.StatementBuilder
+
+	builder.WriteString(`UPDATE zitadel.instances SET `)
+
+	// don't update deleted instances
+	conditions := []database.Condition{condition, database.IsNull(i.DeletedAtColumn())}
+	database.Changes(changes).Write(&builder)
+	i.writeCondition(&builder, database.And(conditions...))
+
+	stmt := builder.String()
+
+	rowsAffected, err := i.client.Exec(ctx, stmt, builder.Args()...)
+	return rowsAffected, err
+}
+
+// Delete implements [domain.InstanceRepository].
+func (i instance) Delete(ctx context.Context, condition database.Condition) error {
+	if condition == nil {
+		return errors.New("Delete must contain a condition") // (otherwise ALL instances will be deleted)
+	}
+	var builder database.StatementBuilder
+
+	builder.WriteString(`UPDATE zitadel.instances SET deleted_at = $1`)
+	builder.AppendArgs(time.Now())
+
+	i.writeCondition(&builder, condition)
+	_, err := i.client.Exec(ctx, builder.String(), builder.Args()...)
+	return err
+}
+
+// -------------------------------------------------------------
+// changes
+// -------------------------------------------------------------
+
+// SetName implements [domain.instanceChanges].
+func (i instance) SetName(name string) database.Change {
+	return database.NewChange(i.NameColumn(), name)
+}
+
+// -------------------------------------------------------------
+// conditions
+// -------------------------------------------------------------
+
+// IDCondition implements [domain.instanceConditions].
+func (i instance) IDCondition(id string) database.Condition {
+	return database.NewTextCondition(i.IDColumn(), database.TextOperationEqual, id)
+}
+
+// NameCondition implements [domain.instanceConditions].
+func (i instance) NameCondition(op database.TextOperation, name string) database.Condition {
+	return database.NewTextCondition(i.NameColumn(), op, name)
+}
+
+// -------------------------------------------------------------
+// columns
+// -------------------------------------------------------------
+
+// IDColumn implements [domain.instanceColumns].
+func (instance) IDColumn() database.Column {
+	return database.NewColumn("id")
+}
+
+// NameColumn implements [domain.instanceColumns].
+func (instance) NameColumn() database.Column {
+	return database.NewColumn("name")
+}
+
+// CreatedAtColumn implements [domain.instanceColumns].
+func (instance) CreatedAtColumn() database.Column {
+	return database.NewColumn("created_at")
+}
+
+// DefaultOrgIdColumn implements [domain.instanceColumns].
+func (instance) DefaultOrgIDColumn() database.Column {
+	return database.NewColumn("default_org_id")
+}
+
+// IAMProjectIDColumn implements [domain.instanceColumns].
+func (instance) IAMProjectIDColumn() database.Column {
+	return database.NewColumn("iam_project_id")
+}
+
+// ConsoleClientIDColumn implements [domain.instanceColumns].
+func (instance) ConsoleClientIDColumn() database.Column {
+	return database.NewColumn("console_client_id")
+}
+
+// ConsoleAppIDColumn implements [domain.instanceColumns].
+func (instance) ConsoleAppIDColumn() database.Column {
+	return database.NewColumn("console_app_id")
+}
+
+// DefaultLanguageColumn implements [domain.instanceColumns].
+func (instance) DefaultLanguageColumn() database.Column {
+	return database.NewColumn("default_language")
+}
+
+// UpdatedAtColumn implements [domain.instanceColumns].
+func (instance) UpdatedAtColumn() database.Column {
+	return database.NewColumn("updated_at")
+}
+
+// DeletedAtColumn implements [domain.instanceColumns].
+func (instance) DeletedAtColumn() database.Column {
+	return database.NewColumn("deleted_at")
+}
+
+func (i *instance) writeCondition(
+	builder *database.StatementBuilder,
+	condition database.Condition,
+) {
+	if condition == nil {
+		return
+	}
+	builder.WriteString(" WHERE ")
+	condition.Write(builder)
+}
+
+func scanInstance(scanner database.Scanner) (*domain.Instance, error) {
+	var instance domain.Instance
+	err := scanner.Scan(
+		&instance.ID,
+		&instance.Name,
+		&instance.DefaultOrgID,
+		&instance.IAMProjectID,
+		&instance.ConsoleClientID,
+		&instance.ConsoleAppID,
+		&instance.DefaultLanguage,
+		&instance.CreatedAt,
+		&instance.UpdatedAt,
+		&instance.DeletedAt,
+	)
+	if err != nil {
+		// if no results returned, this is not a error
+		// it just means the instance was not found
+		// the caller should check if the returned instance is nil
+		if err.Error() == "no rows in result set" {
+			return nil, nil
+		}
+		return nil, err
+	}
+
+	return &instance, nil
+}
+
+func scanInstances(rows database.Rows) ([]*domain.Instance, error) {
+	instances := make([]*domain.Instance, 0)
+	for rows.Next() {
+
+		var instance domain.Instance
+		err := rows.Scan(
+			&instance.ID,
+			&instance.Name,
+			&instance.DefaultOrgID,
+			&instance.IAMProjectID,
+			&instance.ConsoleClientID,
+			&instance.ConsoleAppID,
+			&instance.DefaultLanguage,
+			&instance.CreatedAt,
+			&instance.UpdatedAt,
+			&instance.DeletedAt,
+		)
+		if err != nil {
+			return nil, err
+		}
+
+		instances = append(instances, &instance)
+
+	}
+	return instances, nil
+}