Documentation
¶
Overview ¶
Package postgresservice adapts PostgreSQL pools to the Service v3 lifecycle. Constructor results are owned by the adapter. Existing pools remain shared unless ownership is explicitly transferred. The adapter performs no retries, closes active owned pools once per ordered service lifecycle, and never closes shared pools. Startup validation failure attempts owned cleanup separately; custom Resource callbacks retain their own context and concurrency contracts.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidOptions identifies invalid adapter construction. ErrInvalidOptions = errors.New("invalid postgres service options") ErrUnavailable = errors.New("postgres service pool unavailable") )
Functions ¶
This section is empty.
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter owns the lifecycle state for one ordered PostgreSQL pool lifecycle. Construct it with New and do not copy it after use. Pool snapshots are synchronized; native resource operations must tolerate service probes and shutdown. Start must not be concurrent or repeated as a restart mechanism.
func New ¶
New validates exactly one Pool or Construct and constructs an inert adapter. Resource acquisition is deferred to Component.Start. Use one ordered service lifecycle; this adapter is not a restartable pool factory.
Example ¶
ExampleNew demonstrates ownership and explicit readiness with an in-memory Resource, not a connectivity probe against a PostgreSQL server.
package main
import (
"context"
"fmt"
"github.com/faustbrian/go-postgres/v3"
postgresservice "github.com/faustbrian/go-postgres/v3/adapters/service"
)
var _ postgresservice.Resource = (*postgres.Pool)(nil)
// ExampleNew demonstrates ownership and explicit readiness with an in-memory
// Resource, not a connectivity probe against a PostgreSQL server.
func main() {
pool := &resource{}
adapter, err := postgresservice.New(postgresservice.Options{
Name: "database",
Pool: pool,
TransferOwnership: true,
StartupPing: true,
})
if err != nil {
fmt.Println("adapter setup failed")
return
}
component := adapter.Component()
_ = component.Start(context.Background())
check := adapter.Readiness()
_ = check.Run(context.Background())
_ = component.Stop(context.Background())
fmt.Println(pool.pings, pool.closes)
}
Output: 2 1
func (*Adapter) Component ¶
Component returns the callbacks for one ordered startup/shutdown cycle. Construct and optional Ping run synchronously; Stop marks the adapter inactive and attempts owned Shutdown once, retaining any close error for later Stop calls.
func (*Adapter) Pool ¶
Pool returns a borrowed resource and whether startup succeeded without stopping. The bool is a lifecycle snapshot, not a lease preventing concurrent shutdown; the resource may remain non-nil when inactive. Do not close an adapter-owned resource independently.
func (*Adapter) Readiness ¶
func (adapter *Adapter) Readiness() service.ReadinessCheck
Readiness returns an opt-in dependency check for the active pool. It must be added to the service plan separately; it does not enable startup validation. Inactive resources return ErrUnavailable without Ping. Active resources retain their own context bounds and may race with shutdown after the state snapshot.
type Constructor ¶
Constructor acquires a pool whose ownership transfers after a successful return. On an error the adapter does not close a partially returned resource; the constructor must clean up its own failed acquisition.
type Options ¶
type Options struct {
// Name is the secret-safe component and readiness-check name.
Name string
// Construct acquires an adapter-owned pool during component startup.
Construct Constructor
// Pool supplies an existing pool. The caller retains ownership unless
// TransferOwnership is true.
Pool Resource
// TransferOwnership closes Pool during shutdown and failed startup.
TransferOwnership bool
// StartupPing validates the acquired pool before startup succeeds.
StartupPing bool
}
Options configure one PostgreSQL lifecycle adapter.
type OptionsError ¶
type OptionsError struct {
// Field names the rejected option.
Field string
// Reason describes the option refusal without echoing the supplied pool or name.
Reason string
}
OptionsError identifies one rejected option.
func (*OptionsError) Error ¶
func (err *OptionsError) Error() string
Error returns a secret-safe construction diagnostic.
func (*OptionsError) Unwrap ¶
func (err *OptionsError) Unwrap() error
Unwrap exposes the stable option classification.
type Resource ¶
type Resource interface {
// Ping checks connectivity using the service-supplied operation context.
Ping(context.Context) error
// Shutdown releases owned resources; implementations must honor their
// context cooperatively.
Shutdown(context.Context) error
}
Resource is the lifecycle surface required from a PostgreSQL pool.
type StartupError ¶
type StartupError struct {
// Validation is the original failed startup ping; inspect under your
// privacy policy.
Validation error
// Cleanup is an owned resource close failure; nil does not add a second cause.
Cleanup error
}
StartupError preserves validation and partial-cleanup failures.
func (*StartupError) Error ¶
func (err *StartupError) Error() string
Error returns a secret-safe startup diagnostic.
func (*StartupError) Unwrap ¶
func (err *StartupError) Unwrap() []error
Unwrap preserves both failures for errors.Is and errors.As.
Source Files