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 ¶
- 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
- type Queryer
- type Tx
- type TxHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Conn ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Pool represents a database connection pool. It may be used concurrently from different goroutines.
func (*Pool) Close ¶
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 ¶
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 ¶
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 ¶
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 ¶
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
Source Files
Directories