Documentation
¶
Index ¶
Examples ¶
Constants ¶
const ( // QueryExecModeExec uses the extended protocol without a prepared-statement cache. QueryExecModeExec = "exec" // QueryExecModeCacheStatement enables pgx's prepared-statement cache. QueryExecModeCacheStatement = "cache_statement" // QueryExecModeCacheDescribe caches parameter and result type descriptions. QueryExecModeCacheDescribe = "cache_describe" // QueryExecModeDescribeExec describes a statement before every execution. QueryExecModeDescribeExec = "describe_exec" // QueryExecModeSimpleProtocol uses pgx's simple query protocol. QueryExecModeSimpleProtocol = "simple_protocol" )
Variables ¶
This section is empty.
Functions ¶
func HealthChecker ¶ added in v0.1.19
HealthChecker returns a health.Checker that verifies PostgreSQL connectivity by pinging the default connection pool. The returned Checker reports health.StatusUnhealthy when no pool has been initialised or when the ping fails, and health.StatusHealthy when reachable.
Example ¶
ExampleHealthChecker shows how to wire HealthChecker into a health.Check call for a /health HTTP endpoint. When the default pool has not been initialised, the Checker reports StatusUnhealthy.
package main
import (
"context"
"fmt"
"github.com/phcp-tech/common-library-golang/dbsqlc/postgres"
"github.com/phcp-tech/common-library-golang/health"
)
func main() {
results := health.Check(context.Background(), postgres.HealthChecker())
fmt.Println(results[0].Name)
fmt.Println(results[0].Status == health.StatusUnhealthy) // true — Default() is nil
}
Output: database true
func InitDefault ¶
InitDefault initializes the default singleton PostgreSQL connection pool.
Example ¶
ExampleInitDefault shows the singleton pattern for the default PostgreSQL pool. Call InitDefault once at application startup; subsequent calls are silently ignored (sync.Once).
In this example the singleton was already consumed by a prior test in this binary, so InitDefault is a no-op and returns nil. Default() returns nil because the first initialisation attempt failed (unreachable host).
package main
import (
"fmt"
"github.com/phcp-tech/common-library-golang/dbsqlc/postgres"
)
func main() {
err := postgres.InitDefault(&postgres.Config{
Host: "127.0.0.1",
Port: "19999",
Database: "mydb",
Username: "user",
Password: "pass",
MaxOpenConns: 10,
MaxIdleConns: 2,
ConnMaxLifetime: 60,
ConnMaxIdletime: 10,
})
fmt.Println(err != nil) // false — sync.Once no-op, returns nil
fmt.Println(postgres.Default() != nil) // false — first init failed, instance nil
}
Output: false false
func NewPostgres ¶
NewPostgres opens a *pgxpool.Pool connection to PostgreSQL and configures the connection pool. It returns the pgx native pool so sqlc-generated Queries (sql_package: "pgx/v5") can use it directly.
Example ¶
ExampleNewPostgres shows the typical usage of NewPostgres. NewPostgres performs an eager connectivity check (show search_path) so callers discover unreachable databases immediately at startup rather than on the first real query. Zero-value pool fields fall back to the dbsqlc package defaults (MaxOpenConns=100, MaxIdleConns=25, ConnMaxLifetime=60min, ConnMaxIdletime=10min).
package main
import (
"fmt"
"github.com/phcp-tech/common-library-golang/dbsqlc/postgres"
)
func main() {
// With an unreachable host the connectivity check fails and an error is returned.
_, err := postgres.NewPostgres(&postgres.Config{
Host: "127.0.0.1",
Port: "19999",
Database: "mydb",
Username: "user",
Password: "pass",
})
fmt.Println(err != nil) // true — connectivity check failed
}
Output: true
Example (CustomPool) ¶
ExampleNewPostgres_customPool shows how to override the default connection pool settings.
package main
import (
"fmt"
"github.com/phcp-tech/common-library-golang/dbsqlc/postgres"
)
func main() {
_, err := postgres.NewPostgres(&postgres.Config{
Host: "127.0.0.1",
Port: "19999",
Database: "mydb",
Username: "user",
Password: "pass",
SearchPath: "myschema",
MaxOpenConns: 50,
MaxIdleConns: 10,
ConnMaxLifetime: 30, // minutes
ConnMaxIdletime: 5, // minutes
})
fmt.Println(err != nil) // true — connectivity check failed
}
Output: true
Example (QueryExecMode) ¶
ExampleNewPostgres_queryExecMode shows how to explicitly select the pgx statement cache for a stable session-pool or direct PostgreSQL connection. Supabase transaction pooler connections on port 6543 must explicitly set QueryExecModeExec instead.
package main
import (
"fmt"
"github.com/phcp-tech/common-library-golang/dbsqlc/postgres"
)
func main() {
_, err := postgres.NewPostgres(&postgres.Config{
Host: "127.0.0.1",
Port: "19999",
Database: "mydb",
Username: "user",
Password: "pass",
QueryExecMode: postgres.QueryExecModeCacheStatement,
})
fmt.Println(err != nil) // true — connection is intentionally unreachable
}
Output: true
Types ¶
type Config ¶
type Config struct {
// Database connection parameters
Host string
Port string
Database string
SearchPath string // optional
Username string
Password string
// QueryExecMode selects a pgx query execution mode. The zero value preserves
// pgx's default; see the QueryExecMode constants for mode-specific constraints.
QueryExecMode string
// Connection pool parameters
MaxOpenConns int
MaxIdleConns int
ConnMaxLifetime int
ConnMaxIdletime int
}
Source Files
Directories