Ask Bjørn Hansen
283d3936f6
Add support for PostgreSQL connection URIs via DATABASE_URI env var. When set, it takes precedence over config files and PoolOptions are ignored (pool settings can be specified in URI query string).
147 lines
3.5 KiB
Markdown
147 lines
3.5 KiB
Markdown
# pgdb - Native PostgreSQL Connection Pool
|
|
|
|
Primary package for PostgreSQL connections using native pgx pool (`*pgxpool.Pool`). Provides better performance and PostgreSQL-specific features compared to `database/sql`.
|
|
|
|
## Usage
|
|
|
|
### Basic Example
|
|
|
|
```go
|
|
import (
|
|
"context"
|
|
"go.ntppool.org/common/database/pgdb"
|
|
)
|
|
|
|
func main() {
|
|
ctx := context.Background()
|
|
|
|
// Open pool with default options
|
|
pool, err := pgdb.OpenPool(ctx, pgdb.DefaultPoolOptions())
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
defer pool.Close()
|
|
|
|
// Use the pool for queries
|
|
row := pool.QueryRow(ctx, "SELECT version()")
|
|
var version string
|
|
row.Scan(&version)
|
|
}
|
|
```
|
|
|
|
### With Custom Config File
|
|
|
|
```go
|
|
pool, err := pgdb.OpenPoolWithConfigFile(ctx, "/path/to/database.yaml")
|
|
```
|
|
|
|
### With Custom Pool Settings
|
|
|
|
```go
|
|
opts := pgdb.DefaultPoolOptions()
|
|
opts.MaxConns = 50
|
|
opts.MinConns = 5
|
|
opts.MaxConnLifetime = 2 * time.Hour
|
|
|
|
pool, err := pgdb.OpenPool(ctx, opts)
|
|
```
|
|
|
|
## Configuration Format
|
|
|
|
### Recommended: Nested Format (database.yaml)
|
|
|
|
```yaml
|
|
postgres:
|
|
host: localhost
|
|
port: 5432
|
|
user: myuser
|
|
pass: mypassword
|
|
name: mydb
|
|
sslmode: prefer
|
|
```
|
|
|
|
### Legacy: Flat Format (backward compatible)
|
|
|
|
```yaml
|
|
host: localhost
|
|
port: 5432
|
|
user: myuser
|
|
pass: mypassword
|
|
name: mydb
|
|
sslmode: prefer
|
|
```
|
|
|
|
## Configuration Options
|
|
|
|
### PoolOptions
|
|
|
|
- `ConfigFiles` - List of config file paths to search (default: `database.yaml`, `/vault/secrets/database.yaml`)
|
|
- `MinConns` - Minimum connections (default: 0)
|
|
- `MaxConns` - Maximum connections (default: 25)
|
|
- `MaxConnLifetime` - Connection lifetime (default: 1 hour)
|
|
- `MaxConnIdleTime` - Idle timeout (default: 30 minutes)
|
|
- `HealthCheckPeriod` - Health check interval (default: 1 minute)
|
|
|
|
### PostgreSQL Config Fields
|
|
|
|
- `host` - Database host (required)
|
|
- `user` - Database user (required)
|
|
- `pass` - Database password
|
|
- `name` - Database name (required)
|
|
- `port` - Port number (default: 5432)
|
|
- `sslmode` - SSL mode: `disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full` (default: `prefer`)
|
|
|
|
## Environment Variables
|
|
|
|
- `DATABASE_URI` - PostgreSQL connection URI (takes precedence over config files)
|
|
- `DATABASE_CONFIG_FILE` - Override config file location
|
|
|
|
### URI Format
|
|
|
|
Standard PostgreSQL URI format:
|
|
```
|
|
postgresql://user:password@host:port/database?sslmode=require&pool_max_conns=10
|
|
```
|
|
|
|
Pool settings can be included in the URI query string:
|
|
- `pool_max_conns`, `pool_min_conns`
|
|
- `pool_max_conn_lifetime`, `pool_max_conn_idle_time`
|
|
- `pool_health_check_period`
|
|
|
|
When using `DATABASE_URI`, `PoolOptions` are ignored and all settings come from the URI.
|
|
|
|
Example with CloudNativePG:
|
|
```yaml
|
|
# Mount the secret's 'uri' key as DATABASE_URI
|
|
env:
|
|
- name: DATABASE_URI
|
|
valueFrom:
|
|
secretKeyRef:
|
|
name: mydb-app
|
|
key: uri
|
|
```
|
|
|
|
## When to Use
|
|
|
|
**Use `pgdb.OpenPool()`** (this package) when:
|
|
- You need native PostgreSQL features (LISTEN/NOTIFY, COPY, etc.)
|
|
- You want better performance
|
|
- You're writing new PostgreSQL code
|
|
|
|
**Use `database.OpenDB()`** (sql.DB) when:
|
|
- You need database-agnostic code
|
|
- You're using SQLC or other tools that expect `database/sql`
|
|
- You need to support both MySQL and PostgreSQL
|
|
|
|
## Security
|
|
|
|
This package avoids password exposure by:
|
|
1. Never constructing DSN strings with passwords
|
|
2. Setting passwords separately in pgx config objects
|
|
3. Validating all configuration before connection
|
|
|
|
## See Also
|
|
|
|
- `database/` - Generic sql.DB support for MySQL and PostgreSQL
|
|
- pgx documentation: https://github.com/jackc/pgx
|