pool

type Connection struct {
	DSN      string
	ReadOnly bool
}

type Option func(*Options)

type Options struct {
	Connections []Connection

	MaxOpen     int
	MaxIdle     int
	MaxLifetime time.Duration

	PreferSimpleProtocol   bool
	SkipDefaultTransaction bool

	TraceConfig     config.ConfigurationDatabaseTracing
	InsertBatchSize int

	PreparedStatements bool
}

type Pool interface {
	DB(ctx context.Context, readOnly bool) *gorm.DB

	// WithTenancy runs fn inside a database transaction in which the
	// Postgres session variables app.tenant_id and app.partition_id have
	// been populated from the auth claims attached to ctx. Combined with
	// Row-Level Security policies that consult current_setting() on
	// every tenancy-scoped table, this means callers can write SQL that
	// makes no mention of tenant_id / partition_id — the database
	// enforces isolation transparently.
	//
	// When ctx carries no claims (system services, migrations) or the
	// tenancy-checks-skipped flag is set, the session variables are left
	// unset and the RLS policy's NULL-OK branch keeps the row visible.
	// Same behaviour as the auto-applied TenancyPartition scope, so the
	// contract is consistent between GORM query-builder paths and
	// Raw-SQL paths.
	//
	// Use this for any Raw SQL or multi-table-join report where you do
	// not want tenancy logic in the application. For trivially-scoped
	// GORM-builder paths (.Model(&X{}).Where(...).Find(...)), the
	// auto-applied TenancyPartition scope already filters correctly and
	// this helper is unnecessary.
	WithTenancy(ctx context.Context, readOnly bool, fn func(tx *gorm.DB) error) error

	// WithRequestTx is the per-request middleware primitive. It opens a
	// tenancy-scoped transaction the same way WithTenancy does, then
	// binds the transaction to a child context (via ContextWithTx) and
	// invokes fn with the bound context. Inside fn, callers can use
	// pool.DB(ctx, _) and receive the bound transaction transparently —
	// application code never references tenant_id or partition_id and
	// never wraps individual queries in WithTenancy.
	//
	// Commits when fn returns nil, rolls back on error. Nesting is
	// safe: a nested WithRequestTx reuses the outer transaction
	// instead of opening a new one.
	WithRequestTx(ctx context.Context, fn func(ctx context.Context) error) error

	AddConnection(ctx context.Context, opts ...Option) error

	CanMigrate() bool
	SaveMigration(ctx context.Context, migrationPatches ...*migration.Patch) error
	// Migrate finds missing migrations and records them in the database.
	Migrate(ctx context.Context, migrationsDirPath string, migrations ...any) error

	Close(ctx context.Context)
}