Thanks to visit codestin.com
Credit goes to github.com

Skip to content

doc: add godoc links #2531

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jackc merged 1 commit into from
Apr 9, 2026
Merged

doc: add godoc links #2531

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 14 additions & 13 deletions batch.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import (
"github.com/jackc/pgx/v5/pgconn"
)

// QueuedQuery is a query that has been queued for execution via a Batch.
// QueuedQuery is a query that has been queued for execution via a [Batch].
type QueuedQuery struct {
SQL string
Arguments []any
Expand Down Expand Up @@ -46,7 +46,7 @@ func (qq *QueuedQuery) QueryRow(fn func(row Row) error) {
//
// Note: for simple batch insert uses where it is not required to handle
// each potential error individually, it's sufficient to not set any callbacks,
// and just handle the return value of BatchResults.Close.
// and just handle the return value of [BatchResults.Close].
func (qq *QueuedQuery) Exec(fn func(ct pgconn.CommandTag) error) {
qq.Fn = func(br BatchResults) error {
ct, err := br.Exec()
Expand All @@ -65,12 +65,13 @@ type Batch struct {
}

// Queue queues a query to batch b. query can be an SQL query or the name of a prepared statement. The only pgx option
// argument that is supported is QueryRewriter. Queries are executed using the connection's DefaultQueryExecMode.
// argument that is supported is [QueryRewriter]. Queries are executed using the connection's DefaultQueryExecMode
// (see [ConnConfig.DefaultQueryExecMode]).
//
// While query can contain multiple statements if the connection's DefaultQueryExecMode is QueryModeSimple, this should
// be avoided. QueuedQuery.Fn must not be set as it will only be called for the first query. That is, QueuedQuery.Query,
// QueuedQuery.QueryRow, and QueuedQuery.Exec must not be called. In addition, any error messages or tracing that
// include the current query may reference the wrong query.
// While query can contain multiple statements if the connection's DefaultQueryExecMode is [QueryExecModeSimpleProtocol],
// this should be avoided. QueuedQuery.Fn must not be set as it will only be called for the first query. That is,
// [QueuedQuery.Query], [QueuedQuery.QueryRow], and [QueuedQuery.Exec] must not be called. In addition, any error
// messages or tracing that include the current query may reference the wrong query.
func (b *Batch) Queue(query string, arguments ...any) *QueuedQuery {
qq := &QueuedQuery{
SQL: query,
Expand All @@ -86,20 +87,20 @@ func (b *Batch) Len() int {
}

type BatchResults interface {
// Exec reads the results from the next query in the batch as if the query has been sent with Conn.Exec. Prefer
// Exec reads the results from the next query in the batch as if the query has been sent with [Conn.Exec]. Prefer
// calling Exec on the QueuedQuery, or just calling Close.
Exec() (pgconn.CommandTag, error)

// Query reads the results from the next query in the batch as if the query has been sent with Conn.Query. Prefer
// calling Query on the QueuedQuery.
// Query reads the results from the next query in the batch as if the query has been sent with [Conn.Query]. Prefer
// calling [QueuedQuery.Query].
Query() (Rows, error)

// QueryRow reads the results from the next query in the batch as if the query has been sent with Conn.QueryRow.
// Prefer calling QueryRow on the QueuedQuery.
// QueryRow reads the results from the next query in the batch as if the query has been sent with [Conn.QueryRow].
// Prefer calling [QueuedQuery.QueryRow].
QueryRow() Row

// Close closes the batch operation. All unread results are read and any callback functions registered with
// QueuedQuery.Query, QueuedQuery.QueryRow, or QueuedQuery.Exec will be called. If a callback function returns an
// [QueuedQuery.Query], [QueuedQuery.QueryRow], or [QueuedQuery.Exec] will be called. If a callback function returns an
// error or the batch encounters an error subsequent callback functions will not be called.
//
// For simple batch inserts inside a transaction or similar queries, it's sufficient to not set any callbacks,
Expand Down
26 changes: 13 additions & 13 deletions conn.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ import (
"github.com/jackc/pgx/v5/pgtype"
)

// ConnConfig contains all the options used to establish a connection. It must be created by ParseConfig and
// then it can be modified. A manually initialized ConnConfig will cause ConnectConfig to panic.
// ConnConfig contains all the options used to establish a connection. It must be created by [ParseConfig] and
// then it can be modified. A manually initialized ConnConfig will cause [ConnectConfig] to panic.
type ConnConfig struct {
pgconn.Config

Expand All @@ -37,8 +37,8 @@ type ConnConfig struct {

// DefaultQueryExecMode controls the default mode for executing queries. By default pgx uses the extended protocol
// and automatically prepares and caches prepared statements. However, this may be incompatible with proxies such as
// PGBouncer. In this case it may be preferable to use QueryExecModeExec or QueryExecModeSimpleProtocol. The same
// functionality can be controlled on a per query basis by passing a QueryExecMode as the first query argument.
// PGBouncer. In this case it may be preferable to use [QueryExecModeExec] or [QueryExecModeSimpleProtocol]. The same
// functionality can be controlled on a per query basis by passing a [QueryExecMode] as the first query argument.
DefaultQueryExecMode QueryExecMode

createdByParseConfig bool // Used to enforce created by ParseConfig rule.
Expand Down Expand Up @@ -131,7 +131,7 @@ var (
)

// Connect establishes a connection with a PostgreSQL server with a connection string. See
// pgconn.Connect for details.
// [pgconn.Connect] for details.
func Connect(ctx context.Context, connString string) (*Conn, error) {
connConfig, err := ParseConfig(connString)
if err != nil {
Expand All @@ -141,7 +141,7 @@ func Connect(ctx context.Context, connString string) (*Conn, error) {
}

// ConnectWithOptions behaves exactly like Connect with the addition of options. At the present options is only used to
// provide a GetSSLPassword function.
// provide a [pgconn.GetSSLPasswordFunc] function.
func ConnectWithOptions(ctx context.Context, connString string, options ParseConfigOptions) (*Conn, error) {
connConfig, err := ParseConfigWithOptions(connString, options)
if err != nil {
Expand All @@ -151,7 +151,7 @@ func ConnectWithOptions(ctx context.Context, connString string, options ParseCon
}

// ConnectConfig establishes a connection with a PostgreSQL server with a configuration struct.
// connConfig must have been created by ParseConfig.
// connConfig must have been created by [ParseConfig].
func ConnectConfig(ctx context.Context, connConfig *ConnConfig) (*Conn, error) {
// In general this improves safety. In particular avoid the config.Config.OnNotification mutation from affecting other
// connections with the same config. See https://github.com/jackc/pgx/issues/618.
Expand All @@ -160,8 +160,8 @@ func ConnectConfig(ctx context.Context, connConfig *ConnConfig) (*Conn, error) {
return connect(ctx, connConfig)
}

// ParseConfigWithOptions behaves exactly as ParseConfig does with the addition of options. At the present options is
// only used to provide a GetSSLPassword function.
// ParseConfigWithOptions behaves exactly as [ParseConfig] does with the addition of options. At the present options is
// only used to provide a [pgconn.GetSSLPasswordFunc] function.
func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*ConnConfig, error) {
config, err := pgconn.ParseConfigWithOptions(connString, options.ParseConfigOptions)
if err != nil {
Expand Down Expand Up @@ -308,8 +308,8 @@ func (c *Conn) Close(ctx context.Context) error {
}

// Prepare creates a prepared statement with name and sql. sql can contain placeholders for bound parameters. These
// placeholders are referenced positionally as $1, $2, etc. name can be used instead of sql with Query, QueryRow, and
// Exec to execute the statement. It can also be used with Batch.Queue.
// placeholders are referenced positionally as $1, $2, etc. name can be used instead of sql with [Conn.Query],
// [Conn.QueryRow], and [Conn.Exec] to execute the statement. It can also be used with [Batch.Queue].
//
// The underlying PostgreSQL identifier for the prepared statement will be name if name != sql or a digest of sql if
// name == sql.
Expand Down Expand Up @@ -933,7 +933,7 @@ func (c *Conn) QueryRow(ctx context.Context, sql string, args ...any) Row {
}

// SendBatch sends all queued queries to the server at once. All queries are run in an implicit transaction unless
// explicit transaction control statements are executed. The returned BatchResults must be closed before the connection
// explicit transaction control statements are executed. The returned [BatchResults] must be closed before the connection
// is used again.
//
// Depending on the QueryExecMode, all queries may be prepared before any are executed. This means that creating a table
Expand Down Expand Up @@ -1277,7 +1277,7 @@ func (c *Conn) sanitizeForSimpleQuery(sql string, args ...any) (string, error) {
return sanitize.SanitizeSQL(sql, valueArgs...)
}

// LoadType inspects the database for typeName and produces a pgtype.Type suitable for registration. typeName must be
// LoadType inspects the database for typeName and produces a [pgtype.Type] suitable for registration. typeName must be
// the name of a type where the underlying type(s) is already understood by pgx. It is for derived types. In particular,
// typeName must be one of the following:
// - An array type name of a type that is already registered. e.g. "_foo" when "foo" is registered.
Expand Down
16 changes: 8 additions & 8 deletions copy_from.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ import (
"github.com/jackc/pgx/v5/pgconn"
)

// CopyFromRows returns a CopyFromSource interface over the provided rows slice
// making it usable by *Conn.CopyFrom.
// CopyFromRows returns a [CopyFromSource] interface over the provided rows slice
// making it usable by [Conn.CopyFrom].
func CopyFromRows(rows [][]any) CopyFromSource {
return &copyFromRows{rows: rows, idx: -1}
}
Expand All @@ -34,8 +34,8 @@ func (ctr *copyFromRows) Err() error {
return nil
}

// CopyFromSlice returns a CopyFromSource interface over a dynamic func
// making it usable by *Conn.CopyFrom.
// CopyFromSlice returns a [CopyFromSource] interface over a dynamic func
// making it usable by [Conn.CopyFrom].
func CopyFromSlice(length int, next func(int) ([]any, error)) CopyFromSource {
return &copyFromSlice{next: next, idx: -1, len: length}
}
Expand Down Expand Up @@ -64,7 +64,7 @@ func (cts *copyFromSlice) Err() error {
return cts.err
}

// CopyFromFunc returns a CopyFromSource interface that relies on nxtf for values.
// CopyFromFunc returns a [CopyFromSource] interface that relies on nxtf for values.
// nxtf returns rows until it either signals an 'end of data' by returning row=nil and err=nil,
// or it returns an error. If nxtf returns an error, the copy is aborted.
func CopyFromFunc(nxtf func() (row []any, err error)) CopyFromSource {
Expand All @@ -91,7 +91,7 @@ func (g *copyFromFunc) Err() error {
return g.err
}

// CopyFromSource is the interface used by *Conn.CopyFrom as the source for copy data.
// CopyFromSource is the interface used by [Conn.CopyFrom] as the source for copy data.
type CopyFromSource interface {
// Next returns true if there is another row and makes the next row data
// available to Values(). When there are no more rows available or an error
Expand Down Expand Up @@ -260,8 +260,8 @@ func (ct *copyFrom) buildCopyBuf(buf []byte, sd *pgconn.StatementDescription) (b
// CopyFrom requires all values use the binary format. A pgtype.Type that supports the binary format must be registered
// for the type of each column. Almost all types implemented by pgx support the binary format.
//
// Even though enum types appear to be strings they still must be registered to use with CopyFrom. This can be done with
// Conn.LoadType and pgtype.Map.RegisterType.
// Even though enum types appear to be strings they still must be registered to use with [Conn.CopyFrom]. This can be done with
// [Conn.LoadType] and [pgtype.Map.RegisterType].
func (c *Conn) CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error) {
ct := &copyFrom{
conn: c,
Expand Down
Loading