From a9667168607e684819ae338bd19007e28cb27f74 Mon Sep 17 00:00:00 2001 From: Jack Christensen Date: Sat, 11 May 2024 14:33:35 -0500 Subject: [PATCH] Replace DSN with keyword/value in comments and documentation The term DSN is not used in the PostgreSQL documentation. I'm not sure why it was originally used. Use the correct PostgreSQL terminology. --- doc.go | 11 ++++++----- pgconn/config.go | 22 +++++++++++----------- pgconn/config_test.go | 24 ++++++++++++------------ pgconn/doc.go | 4 ++-- pgconn/errors.go | 8 ++++---- pgconn/errors_test.go | 4 ++-- pgconn/pgconn.go | 11 ++++++----- pgxpool/doc.go | 2 +- pgxpool/pool.go | 2 +- stdlib/sql.go | 2 +- 10 files changed, 46 insertions(+), 44 deletions(-) diff --git a/doc.go b/doc.go index 911571b1..bc0391dd 100644 --- a/doc.go +++ b/doc.go @@ -11,9 +11,10 @@ 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. +The database connection string can be in URL or key/value 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. Connection Pool @@ -23,8 +24,8 @@ github.com/jackc/pgx/v5/pgxpool for a concurrency safe connection pool. Query Interface pgx implements Query in the familiar database/sql style. However, pgx provides generic functions such as CollectRows and -ForEachRow that are a simpler and safer way of processing rows than manually calling defer rows.Close(), rows.Next(), rows.Scan, and -rows.Err(). +ForEachRow that are a simpler and safer way of processing rows than manually calling defer rows.Close(), rows.Next(), +rows.Scan, and rows.Err(). CollectRows can be used collect all returned rows into a slice. diff --git a/pgconn/config.go b/pgconn/config.go index ce0044d4..7d1c6fba 100644 --- a/pgconn/config.go +++ b/pgconn/config.go @@ -160,11 +160,11 @@ func NetworkAddress(host string, port uint16) (network, address string) { // ParseConfig builds a *Config from connString with similar behavior to the PostgreSQL standard C library libpq. It // uses the same defaults as libpq (e.g. port=5432) and understands most PG* environment variables. ParseConfig closely -// matches the parsing behavior of libpq. connString may either be in URL format or keyword = value format (DSN style). -// See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING for details. connString also may be -// empty to only read from the environment. If a password is not supplied it will attempt to read the .pgpass file. +// matches the parsing behavior of libpq. connString may either be in URL format or keyword = value format. See +// https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING for details. connString also may be empty +// to only read from the environment. If a password is not supplied it will attempt to read the .pgpass file. // -// # Example DSN +// # Example Keyword/Value // user=jack password=secret host=pg.example.com port=5432 dbname=mydb sslmode=verify-ca // // # Example URL @@ -183,7 +183,7 @@ func NetworkAddress(host string, port uint16) (network, address string) { // postgres://jack:secret@foo.example.com:5432,bar.example.com:5432/mydb // // ParseConfig currently recognizes the following environment variable and their parameter key word equivalents passed -// via database URL or DSN: +// via database URL or keyword/value: // // PGHOST // PGPORT @@ -247,16 +247,16 @@ func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*Con connStringSettings := make(map[string]string) if connString != "" { var err error - // connString may be a database URL or a DSN + // connString may be a database URL or in PostgreSQL keyword/value format if strings.HasPrefix(connString, "postgres://") || strings.HasPrefix(connString, "postgresql://") { connStringSettings, err = parseURLSettings(connString) if err != nil { return nil, &ParseConfigError{ConnString: connString, msg: "failed to parse as URL", err: err} } } else { - connStringSettings, err = parseDSNSettings(connString) + connStringSettings, err = parseKeywordValueSettings(connString) if err != nil { - return nil, &ParseConfigError{ConnString: connString, msg: "failed to parse as DSN", err: err} + return nil, &ParseConfigError{ConnString: connString, msg: "failed to parse as keyword/value", err: err} } } } @@ -534,7 +534,7 @@ func isIPOnly(host string) bool { var asciiSpace = [256]uint8{'\t': 1, '\n': 1, '\v': 1, '\f': 1, '\r': 1, ' ': 1} -func parseDSNSettings(s string) (map[string]string, error) { +func parseKeywordValueSettings(s string) (map[string]string, error) { settings := make(map[string]string) nameMap := map[string]string{ @@ -545,7 +545,7 @@ func parseDSNSettings(s string) (map[string]string, error) { var key, val string eqIdx := strings.IndexRune(s, '=') if eqIdx < 0 { - return nil, errors.New("invalid dsn") + return nil, errors.New("invalid keyword/value") } key = strings.Trim(s[:eqIdx], " \t\n\r\v\f") @@ -597,7 +597,7 @@ func parseDSNSettings(s string) (map[string]string, error) { } if key == "" { - return nil, errors.New("invalid dsn") + return nil, errors.New("invalid keyword/value") } settings[key] = val diff --git a/pgconn/config_test.go b/pgconn/config_test.go index 99cc6e1a..7f92bd53 100644 --- a/pgconn/config_test.go +++ b/pgconn/config_test.go @@ -336,7 +336,7 @@ func TestParseConfig(t *testing.T) { }, }, { - name: "DSN everything", + name: "Key/value everything", connString: "user=jack password=secret host=localhost port=5432 dbname=mydb sslmode=disable application_name=pgxtest search_path=myschema connect_timeout=5", config: &pgconn.Config{ User: "jack", @@ -353,7 +353,7 @@ func TestParseConfig(t *testing.T) { }, }, { - name: "DSN with escaped single quote", + name: "Key/value with escaped single quote", connString: "user=jack\\'s password=secret host=localhost port=5432 dbname=mydb sslmode=disable", config: &pgconn.Config{ User: "jack's", @@ -366,7 +366,7 @@ func TestParseConfig(t *testing.T) { }, }, { - name: "DSN with escaped backslash", + name: "Key/value with escaped backslash", connString: "user=jack password=sooper\\\\secret host=localhost port=5432 dbname=mydb sslmode=disable", config: &pgconn.Config{ User: "jack", @@ -379,7 +379,7 @@ func TestParseConfig(t *testing.T) { }, }, { - name: "DSN with single quoted values", + name: "Key/value with single quoted values", connString: "user='jack' host='localhost' dbname='mydb' sslmode='disable'", config: &pgconn.Config{ User: "jack", @@ -391,7 +391,7 @@ func TestParseConfig(t *testing.T) { }, }, { - name: "DSN with single quoted value with escaped single quote", + name: "Key/value with single quoted value with escaped single quote", connString: "user='jack\\'s' host='localhost' dbname='mydb' sslmode='disable'", config: &pgconn.Config{ User: "jack's", @@ -403,7 +403,7 @@ func TestParseConfig(t *testing.T) { }, }, { - name: "DSN with empty single quoted value", + name: "Key/value with empty single quoted value", connString: "user='jack' password='' host='localhost' dbname='mydb' sslmode='disable'", config: &pgconn.Config{ User: "jack", @@ -415,7 +415,7 @@ func TestParseConfig(t *testing.T) { }, }, { - name: "DSN with space between key and value", + name: "Key/value with space between key and value", connString: "user = 'jack' password = '' host = 'localhost' dbname = 'mydb' sslmode='disable'", config: &pgconn.Config{ User: "jack", @@ -491,7 +491,7 @@ func TestParseConfig(t *testing.T) { }, }, { - name: "DSN multiple hosts one port", + name: "Key/value multiple hosts one port", connString: "user=jack password=secret host=foo,bar,baz port=5432 dbname=mydb sslmode=disable", config: &pgconn.Config{ User: "jack", @@ -516,7 +516,7 @@ func TestParseConfig(t *testing.T) { }, }, { - name: "DSN multiple hosts multiple ports", + name: "Key/value multiple hosts multiple ports", connString: "user=jack password=secret host=foo,bar,baz port=1,2,3 dbname=mydb sslmode=disable", config: &pgconn.Config{ User: "jack", @@ -772,18 +772,18 @@ func TestParseConfig(t *testing.T) { } // https://github.com/jackc/pgconn/issues/47 -func TestParseConfigDSNWithTrailingEmptyEqualDoesNotPanic(t *testing.T) { +func TestParseConfigKVWithTrailingEmptyEqualDoesNotPanic(t *testing.T) { _, err := pgconn.ParseConfig("host= user= password= port= database=") require.NoError(t, err) } -func TestParseConfigDSNLeadingEqual(t *testing.T) { +func TestParseConfigKVLeadingEqual(t *testing.T) { _, err := pgconn.ParseConfig("= user=jack") require.Error(t, err) } // https://github.com/jackc/pgconn/issues/49 -func TestParseConfigDSNTrailingBackslash(t *testing.T) { +func TestParseConfigKVTrailingBackslash(t *testing.T) { _, err := pgconn.ParseConfig(`x=x\`) require.Error(t, err) assert.Contains(t, err.Error(), "invalid backslash") diff --git a/pgconn/doc.go b/pgconn/doc.go index 8cf8688a..70137501 100644 --- a/pgconn/doc.go +++ b/pgconn/doc.go @@ -5,8 +5,8 @@ nearly the same level is the C library libpq. Establishing a Connection -Use Connect to establish a connection. It accepts a connection string in URL or DSN and will read the environment for -libpq style environment variables. +Use Connect to establish a connection. It accepts a connection string in URL or keyword/value format and will read the +environment for libpq style environment variables. Executing a Query diff --git a/pgconn/errors.go b/pgconn/errors.go index 8df77aba..ec4a6d47 100644 --- a/pgconn/errors.go +++ b/pgconn/errors.go @@ -211,10 +211,10 @@ func redactPW(connString string) string { return redactURL(u) } } - quotedDSN := regexp.MustCompile(`password='[^']*'`) - connString = quotedDSN.ReplaceAllLiteralString(connString, "password=xxxxx") - plainDSN := regexp.MustCompile(`password=[^ ]*`) - connString = plainDSN.ReplaceAllLiteralString(connString, "password=xxxxx") + quotedKV := regexp.MustCompile(`password='[^']*'`) + connString = quotedKV.ReplaceAllLiteralString(connString, "password=xxxxx") + plainKV := regexp.MustCompile(`password=[^ ]*`) + connString = plainKV.ReplaceAllLiteralString(connString, "password=xxxxx") brokenURL := regexp.MustCompile(`:[^:@]+?@`) connString = brokenURL.ReplaceAllLiteralString(connString, ":xxxxxx@") return connString diff --git a/pgconn/errors_test.go b/pgconn/errors_test.go index 171445cc..bbbfeb3c 100644 --- a/pgconn/errors_test.go +++ b/pgconn/errors_test.go @@ -19,12 +19,12 @@ func TestConfigError(t *testing.T) { expectedMsg: "cannot parse `postgresql://foo:xxxxx@host`: msg", }, { - name: "dsn with password unquoted", + name: "keyword/value with password unquoted", err: pgconn.NewParseConfigError("host=host password=password user=user", "msg", nil), expectedMsg: "cannot parse `host=host password=xxxxx user=user`: msg", }, { - name: "dsn with password quoted", + name: "keyword/value with password quoted", err: pgconn.NewParseConfigError("host=host password='pass word' user=user", "msg", nil), expectedMsg: "cannot parse `host=host password=xxxxx user=user`: msg", }, diff --git a/pgconn/pgconn.go b/pgconn/pgconn.go index 66747cbd..7efb522a 100644 --- a/pgconn/pgconn.go +++ b/pgconn/pgconn.go @@ -105,8 +105,9 @@ type PgConn struct { cleanupDone chan 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. +// Connect establishes a connection to a PostgreSQL server using the environment and connString (in URL or keyword/value +// format) 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 { @@ -116,9 +117,9 @@ func Connect(ctx context.Context, connString string) (*PgConn, error) { return ConnectConfig(ctx, config) } -// 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 -// used to cancel a connect attempt. +// Connect establishes a connection to a PostgreSQL server using the environment and connString (in URL or keyword/value +// format) 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) if err != nil { diff --git a/pgxpool/doc.go b/pgxpool/doc.go index 06cc63d5..099443bc 100644 --- a/pgxpool/doc.go +++ b/pgxpool/doc.go @@ -8,7 +8,7 @@ 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 +The database connection string can be in URL or keyword/value format. PostgreSQL settings, pgx settings, and pool settings can be specified here. In addition, a config struct can be created by [ParseConfig]. config, err := pgxpool.ParseConfig(os.Getenv("DATABASE_URL")) diff --git a/pgxpool/pool.go b/pgxpool/pool.go index 9f74805e..6998e7e8 100644 --- a/pgxpool/pool.go +++ b/pgxpool/pool.go @@ -279,7 +279,7 @@ func NewWithConfig(ctx context.Context, config *Config) (*Pool, error) { // // See Config for definitions of these arguments. // -// # Example DSN +// # Example Keyword/Value // user=jack password=secret host=pg.example.com port=5432 dbname=mydb sslmode=verify-ca pool_max_conns=10 // // # Example URL diff --git a/stdlib/sql.go b/stdlib/sql.go index 3d65e23a..29cd3fbb 100644 --- a/stdlib/sql.go +++ b/stdlib/sql.go @@ -7,7 +7,7 @@ // return err // } // -// Or from a DSN string. +// Or from a keyword/value string. // // db, err := sql.Open("pgx", "user=postgres password=secret host=localhost port=5432 database=pgx_test sslmode=disable") // if err != nil {