postgres

Documentation

Overview

Package postgres provides an adapter for a PostgreSQL database in order to expose the interfaces which are required in the github.com/momeni/clean-arch/pkg/core/repo package. The actual implementation uses github.com/jackc/pgx/v5 for the connections and gorm.io/gorm for the models mapping and ORM.

Index

• Constants
• Variables
• func NoOpConnHandler(context.Context, repo.Conn) error
• type Conn
  • func (c *Conn) Exec(ctx context.Context, sql string, args ...any) (int64, error)
  • func (c *Conn) GORM(ctx context.Context) *gorm.DB
  • func (c *Conn) IsConn()
  • func (c *Conn) Query(ctx context.Context, sql string, args ...any) (repo.Rows, error)
  • func (c *Conn) Tx(ctx context.Context, f TxHandler) (err error)
• type ConnHandler
• type Pool
  • func NewPool(ctx context.Context, url string) (*Pool, error)
  • func (p *Pool) Close() error
  • func (p *Pool) Conn(ctx context.Context, f ConnHandler) error
• type Queryer
• type Tx
  • func (tx *Tx) Exec(ctx context.Context, sql string, args ...any) (int64, error)
  • func (tx *Tx) GORM(ctx context.Context) *gorm.DB
  • func (tx *Tx) IsTx()
  • func (tx *Tx) Query(ctx context.Context, sql string, args ...any) (repo.Rows, error)
• type TxHandler

Constants

const (
	Major = stlmig1.Major // latest supported schema major version
	Minor = stlmig1.Minor // latest schema minor version in Major series
	Patch = stlmig1.Patch // latest schema patch version in Minor series
)

These constants represent the major, minor, and patch components of the current database schema semantic version. Since each schema major version is backed by one stlmigN package for its migration settlement and intitialization operations, the latest version can be taken from that package (for the largest supported N major version) too.

The v1.1.0 is the latest supported database schema version.

Variables

var Version = model.SemVer{Major, Minor, Patch}

Version is the latest supported database schema semantic version.

Functions

func NoOpConnHandler

func NoOpConnHandler(context.Context, repo.Conn) error

NoOpConnHandler is a connection handler which performs no operation. It is used in order to test a connection establishment during the creation of a new connection pool.

Types

type Conn

type Conn struct {
	*gorm.DB
}

Conn represents a database connection. It is unsafe to be used concurrently. A connection may be used in order to execute one or more SQL statements or start transactions one at a time. For statement execution methods, see the Queryer interface. Conn embeds the *gorm.DB, hence, may be used like GORM from within the repository packages (which can depend on frameworks).

func (*Conn) Exec

func (c *Conn) Exec(ctx context.Context, sql string, args ...any) (int64, error)

Exec runs SQL statements with given args given ctx context. Number of affected rows and possible errors will be returned. If args is provided, sql will be prepared and args will be passed separately to the DBMS in order to prevent SQL injection. In this case, sql must contain exactly one statement. In absence of args, sql may contain multiple semi-colon separated statements too.

Parameters in sql should be numbered like $1, $2, etc. as they are supported by the PostgreSQL wire protocol natively. This implementation additionally supports the ? and @name parameter placeholders using the GORM framework.

func (*Conn) GORM

func (c *Conn) GORM(ctx context.Context) *gorm.DB

GORM returns the embedded *gorm.DB instance, configuring it to operate on the given ctx context (in a gorm.Session).

func (*Conn) IsConn

func (c *Conn) IsConn()

IsConn method prevents a non-Conn object to mistakenly implement the Conn interface.

func (*Conn) Query

func (c *Conn) Query(ctx context.Context, sql string, args ...any) (repo.Rows, error)

Query runs SQL statement with given args given ctx context. The result set is returned as the Rows interface, while errors are returned as the second return value (if any). If args is provided, sql will be prepared and args will be passed separately to the DBMS in order to prevent SQL injection. Nevertheless, sql must contain exactly one statement.

Parameters in sql should be numbered like $1, $2, etc. as they are supported by the PostgreSQL wire protocol natively. This implementation additionally supports the ? and @name parameter placeholders using the GORM framework.

The Query or Exec may not be called again until the Rows is closed since only one ongoing statement may be used on each connection. If you need to run multiple queries concurrently, either use multiple connections or rewrite the query using the CURSOR concept: https://www.postgresql.org/docs/current/plpgsql-cursors.html

func (*Conn) Tx

func (c *Conn) Tx(ctx context.Context, f TxHandler) (err error)

Tx begins a new transaction in this connection, calls the f handler with the ctx (which was used for beginning the transactions) and the fresh transaction, and commits the transaction ultimately. In case of errors, the transaction will be rolled back and the error will be returned too.

type ConnHandler

type ConnHandler = repo.ConnHandler

ConnHandler is a handler function which takes a context and a database connection which should be used solely from the current goroutine (or by proper synchronization). When it returns, the connection may be released and reused by other routines.

type Pool

type Pool struct {
	*gorm.DB
}

Pool represents a database connection pool. It may be used concurrently from different goroutines.

func NewPool

func NewPool(ctx context.Context, url string) (*Pool, error)

NewPool instantiates a connection pool using a url connection string.

func (*Pool) Close

func (p *Pool) Close() error

Close closes all connections of this connection pool and returns any occurred error.

func (*Pool) Conn

func (p *Pool) Conn(ctx context.Context, f ConnHandler) error

Conn acquires a database connection, passes it into the f handler function, and when it returns will release the connection so it may be used by other callers. This method may be blocked (as while as the ctx allows it) until a connection is obtained. That connection will not be used by any other handler concurrently. Returned errors from the f will be returned by this method after possible wrapping. The ctx which is used for acquisition of a connection is also passed to the f function.

type Queryer

type Queryer interface {
	*Conn | *Tx
	repo.Queryer

	// GORM returns the embedded *gorm.DB instance, configuring it
	// to operate on the given ctx context (in a gorm.Session).
	GORM(ctx context.Context) *gorm.DB
}

Queryer interface includes methods for running SQL statements. There are two main types of statements. One category may affect multiple rows, but do not return a result set, like DDL commands or an UPDATE without a RETURNING clause. These statements are executed with the Exec method. Another category of statements (which may or may not modify the database contents) provide a result set, like SELECT or an UPDATE with a RETURNING clause. These queries may be executed with the Query method. This interface is embedded by both of Conn and Tx since they may be used for execution of commands, of course, with distinct isolation levels.

Queryer is used as a generic type constraint and may be satisfied by *Conn or *Tx. The common interface between these two types includes the repo.Queryer in addition to the GORM(ctx) method which allows its clients to access the embedded *gorm.DB instance from generic functions.

type Tx

type Tx struct {
	*gorm.DB
}

Tx represents a database transaction. It is unsafe to be used concurrently. A transaction may be used in order to execute one or more SQL statements one at a time. For statement execution methods, see the Queryer interface. All statements which are in a single transaction observe the ACID properties. The exact amount of isolation between transactions depends on their types. By default, a READ-COMMITTED transaction is expected from a PostgreSQL DBMS server. For details, read https://www.postgresql.org/docs/current/transaction-iso.html#XACT-READ-COMMITTED Tx embeds the *gorm.DB, hence, may be used like GORM from within the repository packages (which can depend on frameworks).

func (*Tx) Exec

func (tx *Tx) Exec(ctx context.Context, sql string, args ...any) (int64, error)

Exec runs SQL statements with given args given ctx context. Number of affected rows and possible errors will be returned. If args is provided, sql will be prepared and args will be passed separately to the DBMS in order to prevent SQL injection. In this case, sql must contain exactly one statement. In absence of args, sql may contain multiple semi-colon separated statements too.

Parameters in sql should be numbered like $1, $2, etc. as they are supported by the PostgreSQL wire protocol natively. This implementation additionally supports the ? and @name parameter placeholders using the GORM framework.

func (*Tx) GORM

func (tx *Tx) GORM(ctx context.Context) *gorm.DB

GORM returns the embedded *gorm.DB instance, configuring it to operate on the given ctx context (in a gorm.Session).

func (*Tx) IsTx

func (tx *Tx) IsTx()

IsTx method prevents a non-Tx object (such as a Conn) to mistakenly implement the Tx interface.

func (*Tx) Query

func (tx *Tx) Query(ctx context.Context, sql string, args ...any) (repo.Rows, error)

Query runs SQL statement with given args given ctx context. The result set is returned as the Rows interface, while errors are returned as the second return value (if any). If args is provided, sql will be prepared and args will be passed separately to the DBMS in order to prevent SQL injection. Nevertheless, sql must contain exactly one statement.

Parameters in sql should be numbered like $1, $2, etc. as they are supported by the PostgreSQL wire protocol natively. This implementation additionally supports the ? and @name parameter placeholders using the GORM framework.

The Query or Exec may not be called again until the Rows is closed since only one ongoing statement may be used on each connection. If you need to run multiple queries concurrently, either use multiple connections or rewrite the query using the CURSOR concept: https://www.postgresql.org/docs/current/plpgsql-cursors.html

type TxHandler

type TxHandler = repo.TxHandler

TxHandler is a handler function which takes a context and an ongoing transaction. If an error is returned, caller will rollback the transaction and in absence of errors, it will be committed.