From f67221476f2bfd4b0c4da2a0dbd8e3571d53e853 Mon Sep 17 00:00:00 2001 From: Alexey Palazhchenko Date: Thu, 27 Jul 2023 17:47:11 +0400 Subject: [PATCH] Use Go 1.20's link syntax for `ParseConfig` --- conn.go | 2 +- doc.go | 8 ++++---- pgconn/config.go | 2 +- pgconn/pgconn.go | 6 +++--- pgxpool/doc.go | 5 ++--- pgxpool/pool.go | 10 +++++----- 6 files changed, 16 insertions(+), 17 deletions(-) diff --git a/conn.go b/conn.go index 9722e1309..a79cab040 100644 --- a/conn.go +++ b/conn.go @@ -194,7 +194,7 @@ func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*Con return connConfig, nil } -// ParseConfig creates a ConnConfig from a connection string. ParseConfig handles all options that pgconn.ParseConfig +// ParseConfig creates a ConnConfig from a connection string. ParseConfig handles all options that [pgconn.ParseConfig] // does. In addition, it accepts the following options: // // - default_query_exec_mode. diff --git a/doc.go b/doc.go index 0db8cbb14..7486f42c5 100644 --- a/doc.go +++ b/doc.go @@ -7,17 +7,17 @@ details. Establishing a Connection -The primary way of establishing a connection is with `pgx.Connect`. +The primary way of establishing a connection is with [pgx.Connect]: conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL")) The database connection string can be in URL or DSN format. Both PostgreSQL settings and pgx settings can be specified -here. In addition, a config struct can be created by `ParseConfig` and modified before establishing the connection with -`ConnectConfig` to configure settings such as tracing that cannot be configured with a connection string. +here. In addition, a config struct can be created by [ParseConfig] and modified before establishing the connection with +[ConnectConfig] to configure settings such as tracing that cannot be configured with a connection string. Connection Pool -`*pgx.Conn` represents a single connection to the database and is not concurrency safe. Use package +[*pgx.Conn] represents a single connection to the database and is not concurrency safe. Use package github.com/jackc/pgx/v5/pgxpool for a concurrency safe connection pool. Query Interface diff --git a/pgconn/config.go b/pgconn/config.go index 24bf837ce..1c2c647d9 100644 --- a/pgconn/config.go +++ b/pgconn/config.go @@ -26,7 +26,7 @@ type AfterConnectFunc func(ctx context.Context, pgconn *PgConn) error type ValidateConnectFunc func(ctx context.Context, pgconn *PgConn) error type GetSSLPasswordFunc func(ctx context.Context) string -// Config is the settings used to establish a connection to a PostgreSQL server. It must be created by ParseConfig. A +// Config is the settings used to establish a connection to a PostgreSQL server. It must be created by [ParseConfig]. A // manually initialized Config will cause ConnectConfig to panic. type Config struct { Host string // host (e.g. localhost) or absolute path to unix domain socket directory (e.g. /private/tmp) diff --git a/pgconn/pgconn.go b/pgconn/pgconn.go index 49ff0118a..8f602e409 100644 --- a/pgconn/pgconn.go +++ b/pgconn/pgconn.go @@ -97,7 +97,7 @@ type PgConn struct { } // Connect establishes a connection to a PostgreSQL server using the environment and connString (in URL or DSN format) -// to provide configuration. See documentation for ParseConfig for details. ctx can be used to cancel a connect attempt. +// to provide configuration. See documentation for [ParseConfig] for details. ctx can be used to cancel a connect attempt. func Connect(ctx context.Context, connString string) (*PgConn, error) { config, err := ParseConfig(connString) if err != nil { @@ -108,7 +108,7 @@ func Connect(ctx context.Context, connString string) (*PgConn, error) { } // Connect establishes a connection to a PostgreSQL server using the environment and connString (in URL or DSN format) -// and ParseConfigOptions to provide additional configuration. See documentation for ParseConfig for details. ctx can be +// and ParseConfigOptions to provide additional configuration. See documentation for [ParseConfig] for details. ctx can be // used to cancel a connect attempt. func ConnectWithOptions(ctx context.Context, connString string, parseConfigOptions ParseConfigOptions) (*PgConn, error) { config, err := ParseConfigWithOptions(connString, parseConfigOptions) @@ -120,7 +120,7 @@ func ConnectWithOptions(ctx context.Context, connString string, parseConfigOptio } // Connect establishes a connection to a PostgreSQL server using config. config must have been constructed with -// ParseConfig. ctx can be used to cancel a connect attempt. +// [ParseConfig]. ctx can be used to cancel a connect attempt. // // If config.Fallbacks are present they will sequentially be tried in case of error establishing network connection. An // authentication error will terminate the chain of attempts (like libpq: diff --git a/pgxpool/doc.go b/pgxpool/doc.go index 38e49795d..06cc63d5f 100644 --- a/pgxpool/doc.go +++ b/pgxpool/doc.go @@ -4,13 +4,12 @@ pgxpool implements a nearly identical interface to pgx connections. Creating a Pool -The primary way of creating a pool is with `pgxpool.New`. +The primary way of creating a pool is with [pgxpool.New]: pool, err := pgxpool.New(context.Background(), os.Getenv("DATABASE_URL")) The database connection string can be in URL or DSN format. PostgreSQL settings, pgx settings, and pool settings can be -specified here. In addition, a config struct can be created by `ParseConfig` and modified before establishing the -connection with `ConnectConfig`. +specified here. In addition, a config struct can be created by [ParseConfig]. config, err := pgxpool.ParseConfig(os.Getenv("DATABASE_URL")) if err != nil { diff --git a/pgxpool/pool.go b/pgxpool/pool.go index 4a5754850..9f74805e1 100644 --- a/pgxpool/pool.go +++ b/pgxpool/pool.go @@ -99,8 +99,8 @@ type Pool struct { closeChan chan struct{} } -// Config is the configuration struct for creating a pool. It must be created by ParseConfig and then it can be -// modified. A manually initialized ConnConfig will cause ConnectConfig to panic. +// Config is the configuration struct for creating a pool. It must be created by [ParseConfig] and then it can be +// modified. type Config struct { ConnConfig *pgx.ConnConfig @@ -160,7 +160,7 @@ func (c *Config) Copy() *Config { // ConnString returns the connection string as parsed by pgxpool.ParseConfig into pgxpool.Config. func (c *Config) ConnString() string { return c.ConnConfig.ConnString() } -// New creates a new Pool. See ParseConfig for information on connString format. +// New creates a new Pool. See [ParseConfig] for information on connString format. func New(ctx context.Context, connString string) (*Pool, error) { config, err := ParseConfig(connString) if err != nil { @@ -170,7 +170,7 @@ func New(ctx context.Context, connString string) (*Pool, error) { return NewWithConfig(ctx, config) } -// NewWithConfig creates a new Pool. config must have been created by ParseConfig. +// NewWithConfig creates a new Pool. config must have been created by [ParseConfig]. func NewWithConfig(ctx context.Context, config *Config) (*Pool, error) { // Default values are set in ParseConfig. Enforce initial creation by ParseConfig rather than setting defaults from // zero values. @@ -267,7 +267,7 @@ func NewWithConfig(ctx context.Context, config *Config) (*Pool, error) { return p, nil } -// ParseConfig builds a Config from connString. It parses connString with the same behavior as pgx.ParseConfig with the +// ParseConfig builds a Config from connString. It parses connString with the same behavior as [pgx.ParseConfig] with the // addition of the following variables: // // - pool_max_conns: integer greater than 0