dialect

type AcquireHook func(ctx context.Context, conn DialectConn) error

type ConnectionOptions struct {
	MaxOpen                int
	MaxLifetime            time.Duration
	PreferSimpleProtocol   bool
	SkipDefaultTransaction bool
	InsertBatchSize        int
	PreparedStatements     bool
}

type DialectAdapter interface {
	// Name returns a short, stable identifier ("postgres") used in
	// logs.
	Name() string

	// NormalizeDSN converts URI or libpq form into the dialect's
	// expected DSN. Returns the normalized string and an error if the
	// input cannot be parsed.
	NormalizeDSN(raw string) (string, error)

	// OpenConnection constructs a gorm.Dialector + underlying *sql.DB
	// for the supplied DSN. The adapter is responsible for wiring
	// observability (e.g. otelpgx) and tuning (pool sizes, lifetimes).
	// Registered hooks (RegisterAcquireHook / RegisterReleaseHook) must
	// be attached to the connection that is opened.
	//
	// Returns a close function that the caller MUST invoke to release
	// adapter-owned resources (e.g. the pgxpool that *sql.DB.Close does
	// not reach). Calling the returned close function is the only way
	// to fully tear down the underlying driver pool.
	OpenConnection(
		ctx context.Context,
		dsn string,
		opts ConnectionOptions,
	) (gorm.Dialector, *sql.DB, func() error, error)

	// AdvisoryLock acquires a cooperative lock for serializing
	// migrations. Returns a release function (nil release means lock
	// acquisition is not supported by this dialect, in which case the
	// caller should warn and proceed).
	AdvisoryLock(ctx context.Context, db *gorm.DB, id int64) (release func(), err error)

	// IsRelationAlreadyExistsErr discriminates "table already exists"
	// errors that occur during concurrent migration startup races.
	IsRelationAlreadyExistsErr(err error) bool

	// QuoteIdentifier returns the supplied identifier quoted in the
	// dialect's native form. Used by providers when emitting DDL.
	QuoteIdentifier(name string) string

	// RegisterAcquireHook adds a callback invoked on every connection
	// acquire from the underlying pool. Hooks are called in
	// registration order. Returning an error rejects the acquire.
	//
	// Must be called BEFORE OpenConnection — hooks registered after
	// connection construction are not retroactively attached.
	RegisterAcquireHook(fn AcquireHook) error

	// RegisterReleaseHook adds a callback invoked on every connection
	// release. Hooks are called in registration order. Returning an
	// error causes the conn to be destroyed instead of returned to the
	// pool — useful for poisoned state detection.
	RegisterReleaseHook(fn ReleaseHook) error
}

type DialectConn interface {
	// Exec runs a parameterised statement on the connection without
	// returning rows. Used by hooks to issue session-binding SQL.
	Exec(ctx context.Context, query string, args ...any) error
}

type ReleaseHook func(ctx context.Context, conn DialectConn) error