postgres

README

NLG PostgreSQL Driver

PostgreSQL driver for the NetLife Guru Go database layer.

Use postgres to connect PostgreSQL databases to the shared github.com/netlifeguru/db repository API with mapper-backed result scanning.

---

About

postgres is the PostgreSQL driver package for the NetLife Guru Go database stack.

It provides real PostgreSQL database connections that implement the shared db.Conn interface from github.com/netlifeguru/db.

Application code normally imports this package to open PostgreSQL connections, while repository code can depend on the shared db package.

How It Fits Together

Layer	Package	Purpose
Mapper	github.com/netlifeguru/mapper	Row-to-struct and map scanning
DB	github.com/netlifeguru/db	Shared query and repository API
Driver	github.com/netlifeguru/db-postgres	Real PostgreSQL database connections

Features

• PostgreSQL Driver: Connects the shared NetLife Guru database layer to PostgreSQL
• Shared DB Interface: Provides connections compatible with db.Conn
• Repository Friendly: Lets repository code use common db helpers such as List, Get, Value, and Maps
• Mapper Integration: Uses github.com/netlifeguru/mapper for struct, map, and scalar result scanning
• SQL Model Support: Works with PostgreSQL model.psql files through the shared db package
• Dialect SQL Support: Supports PostgreSQL-specific SQL through db.DialectSQL
• Transaction Support: Supports transaction workflows through the shared database layer
• Explicit SQL: Designed for applications that prefer direct SQL and typed repository helpers
• Standard Go Friendly: Built around context-aware operations, interfaces, structs, and explicit error handling

Requirements

This package requires Go 1.25 or newer.

• Go: 1.25 or newer
• Shared dependencies: github.com/netlifeguru/db, github.com/netlifeguru/mapper
• Database: PostgreSQL-compatible server

Installation

Add the PostgreSQL driver to your project using go get:

go get github.com/netlifeguru/db-postgres

This also installs the shared db and mapper packages required by the driver.

Basic Usage

import (
	"context"

	"github.com/netlifeguru/db"
	"github.com/netlifeguru/db-postgres"
)

Once a PostgreSQL connection is created, repository code can work with the shared db.Conn interface:

func ListUsers(ctx context.Context, conn db.Conn) ([]User, error) {
	return db.List[User](ctx, conn, db.Raw(`
		SELECT *
		FROM users
		ORDER BY created_at DESC
	`))
}

Dialect SQL

PostgreSQL queries can be used directly or selected from db.DialectSQL in multi-driver applications.

queries := struct {
	GetUser db.DialectSQL `json:"GetUser"`
}{
	GetUser: db.DialectSQL{
		Postgres: `SELECT * FROM users WHERE id = $1`,
		Mysql:      `SELECT * FROM users WHERE id = ?`,
		Scylla:     `SELECT * FROM users WHERE id = ?`,
	},
}

The active PostgreSQL connection uses the PostgreSQL query variant.

Related Packages

• github.com/netlifeguru/db — shared database layer
• github.com/netlifeguru/mapper — row-to-struct mapper
• github.com/netlifeguru/db-mysql — MySQL driver
• github.com/netlifeguru/db-scylla — ScyllaDB driver

---

Documentation

Full package documentation, guides, and examples are available at:

https://netlife.guru/docs/go/db/getting-started/installation#postgresql

Shared database layer documentation:

https://netlife.guru/docs/go/db

API reference is also available on pkg.go.dev:

https://pkg.go.dev/github.com/netlifeguru/db-postgres

---

Notes

• This package is the PostgreSQL driver for the shared NetLife Guru database layer.
• Repository code can depend on github.com/netlifeguru/db while application setup imports this driver.
• Review package-specific concurrency behavior before using it in highly parallel workloads.
• Check performance characteristics when using this package in latency-sensitive paths.
• See the package documentation and examples for limitations and recommended usage patterns.

---

Versioning

This project follows Semantic Versioning.

See CHANGELOG.md for release history and breaking changes.

---

Contributing

Community contributions, feedback, and improvements are welcome.

Please read CONTRIBUTING.md before submitting pull requests or opening issues.

---

Code of Conduct

This project follows a Code of Conduct.

Please read CODE_OF_CONDUCT.md before contributing or participating in discussions.

---

Author

Created and maintained by NetLife Guru s.r.o.

• Documentation: https://netlife.guru/docs/go/postgres
• GitHub: https://github.com/netlifeguru
• Contact: info@netlife.guru

---

License

MIT License. See LICENSE.

Documentation

Index

• type Connect
  • func New() *Connect
  • func (c *Connect) AnalyzeSQL(sql string) (prepared string, placeholders int, err error)
  • func (c *Connect) Close()
  • func (c *Connect) Connection() (db.Config, *pgxpool.Pool)
  • func (c *Connect) CreatePool(cfg db.Config) error
  • func (c *Connect) DriverName() string
  • func (c *Connect) Exec(q db.Query) (db.Result, error)
  • func (c *Connect) ExecCtx(ctx context.Context, q db.Query) (db.Result, error)
  • func (c *Connect) Fork() db.Conn
  • func (c *Connect) LoadFile() string
  • func (c *Connect) Query(query db.Query, each func(row map[string]any) error) error
  • func (c *Connect) QueryCtx(ctx context.Context, query db.Query, each func(row map[string]any) error) error
  • func (c *Connect) QueryRows(ctx context.Context, q db.Query) (mapper.Rows, error)
  • func (c *Connect) SelectSQL(q db.DialectSQL) string
  • func (c *Connect) Settings(identifier string) error
  • func (c *Connect) Transaction(fn func(tx db.Conn) error) (retErr error)
  • func (c *Connect) TransactionCtx(ctx context.Context, fn func(tx db.Conn) error) (retErr error)
• type Pool
• type Result
  • func (r Result) LastInsertId() int64
  • func (r Result) RowsAffected() int64

Types

type Connect

type Connect struct {
	Host       string
	Identifier string
	TX         any

	Timeout time.Duration
	// contains filtered or unexported fields
}

func New

func New() *Connect

func (*Connect) AnalyzeSQL

func (c *Connect) AnalyzeSQL(sql string) (prepared string, placeholders int, err error)

func (*Connect) Close

func (c *Connect) Close()

func (*Connect) Connection

func (c *Connect) Connection() (db.Config, *pgxpool.Pool)

func (*Connect) CreatePool

func (c *Connect) CreatePool(cfg db.Config) error

func (*Connect) DriverName

func (c *Connect) DriverName() string

func (*Connect) Exec

func (c *Connect) Exec(q db.Query) (db.Result, error)

func (*Connect) ExecCtx

func (c *Connect) ExecCtx(ctx context.Context, q db.Query) (db.Result, error)

func (*Connect) Fork

func (c *Connect) Fork() db.Conn

func (*Connect) LoadFile

func (c *Connect) LoadFile() string

func (*Connect) Query

func (c *Connect) Query(query db.Query, each func(row map[string]any) error) error

func (*Connect) QueryCtx

func (c *Connect) QueryCtx(ctx context.Context, query db.Query, each func(row map[string]any) error) error

func (*Connect) QueryRows

func (c *Connect) QueryRows(ctx context.Context, q db.Query) (mapper.Rows, error)

func (*Connect) SelectSQL

func (c *Connect) SelectSQL(q db.DialectSQL) string

func (*Connect) Settings

func (c *Connect) Settings(identifier string) error

func (*Connect) Transaction

func (c *Connect) Transaction(fn func(tx db.Conn) error) (retErr error)

func (*Connect) TransactionCtx

func (c *Connect) TransactionCtx(ctx context.Context, fn func(tx db.Conn) error) (retErr error)

type Pool

type Pool struct {
	Connect    db.Config
	Connection *pgxpool.Pool
	ConfigKey  string
	PoolKey    string
	Refs       int
}

type Result

type Result struct {
	// contains filtered or unexported fields
}

func (Result) LastInsertId

func (r Result) LastInsertId() int64

func (Result) RowsAffected

func (r Result) RowsAffected() int64