Class NpgsqlConnectionStringBuilder

Provides a simple way to create and manage the contents of connection strings used by the NpgsqlConnection class.

Inheritance

object

NpgsqlConnectionStringBuilder

Implements

IDictionary<, ><string, object?>

Namespace: Npgsql

Assembly: Npgsql.dll

Syntax

public sealed class NpgsqlConnectionStringBuilder : DbConnectionStringBuilder, IDictionary<string, object?>

Constructors

NpgsqlConnectionStringBuilder()

Initializes a new instance of the NpgsqlConnectionStringBuilder class.

Declaration

public NpgsqlConnectionStringBuilder()

NpgsqlConnectionStringBuilder(bool)

Initializes a new instance of the NpgsqlConnectionStringBuilder class, optionally using ODBC rules for quoting values.

Declaration

public NpgsqlConnectionStringBuilder(bool useOdbcRules)

Parameters

Type	Name	Description
bool	useOdbcRules	true to use {} to delimit fields; false to use quotation marks.

NpgsqlConnectionStringBuilder(string?)

Initializes a new instance of the NpgsqlConnectionStringBuilder class and sets its .

Declaration

public NpgsqlConnectionStringBuilder(string? connectionString)

Parameters

Type	Name	Description
string?	connectionString

Properties

ApplicationName

The optional application name parameter to be sent to the backend during connection initiation.

Declaration

public string? ApplicationName { get; set; }

Property Value

Type	Description
string?

ArrayNullabilityMode

Configure the way arrays of value types are returned when requested as object instances.

Declaration

public ArrayNullabilityMode ArrayNullabilityMode { get; set; }

Property Value

Type	Description
ArrayNullabilityMode

AutoPrepareMinUsages

The minimum number of usages an SQL statement is used before it's automatically prepared. Defaults to 5.

Declaration

public int AutoPrepareMinUsages { get; set; }

Property Value

Type	Description
int

BackendTimeouts

Obsolete, see https://www.npgsql.org/doc/release-notes/3.1.html

Declaration

public bool BackendTimeouts { get; set; }

Property Value

Type	Description
bool

CancellationTimeout

The time to wait (in milliseconds) while trying to read a response for a cancellation request for a timed out or cancelled query, before terminating the attempt and generating an error. Zero for infinity, -1 to skip the wait. Defaults to 2000 milliseconds.

Declaration

public int CancellationTimeout { get; set; }

Property Value

Type	Description
int

CheckCertificateRevocation

Whether to check the certificate revocation list during authentication. False by default.

Declaration

public bool CheckCertificateRevocation { get; set; }

Property Value

Type	Description
bool

ClientCertificate

Location of a client certificate to be sent to the server.

Declaration

public string? ClientCertificate { get; set; }

Property Value

Type	Description
string?

ClientCertificateKey

Key for a client certificate to be sent to the server.

Declaration

public string? ClientCertificateKey { get; set; }

Property Value

Type	Description
string?

ClientEncoding

Gets or sets the client_encoding parameter.

Declaration

public string? ClientEncoding { get; set; }

Property Value

Type	Description
string?

CommandTimeout

The time to wait (in seconds) while trying to execute a command before terminating the attempt and generating an error. Defaults to 30 seconds.

Declaration

public int CommandTimeout { get; set; }

Property Value

Type	Description
int

ConnectionIdleLifetime

The time to wait before closing idle connections in the pool if the count of all connections exceeds MinPoolSize.

Declaration

public int ConnectionIdleLifetime { get; set; }

Property Value

Type	Description
int	The time (in seconds) to wait. The default value is 300.

ConnectionLifetime

The total maximum lifetime of connections (in seconds). Connections which have exceeded this value will be destroyed instead of returned from the pool. This is useful in clustered configurations to force load balancing between a running server and a server just brought online.

Declaration

public int ConnectionLifetime { get; set; }

Property Value

Type	Description
int	The time (in seconds) to wait, or 0 to to make connections last indefinitely (the default).

ConnectionPruningInterval

How many seconds the pool waits before attempting to prune idle connections that are beyond idle lifetime (ConnectionIdleLifetime.

Declaration

public int ConnectionPruningInterval { get; set; }

Property Value

Type	Description
int	The interval (in seconds). The default value is 10.

ContinuousProcessing

Obsolete, see https://www.npgsql.org/doc/release-notes/3.1.html

Declaration

public bool ContinuousProcessing { get; set; }

Property Value

Type	Description
bool

ConvertInfinityDateTime

Obsolete, see https://www.npgsql.org/doc/release-notes/6.0.html

Declaration

public bool ConvertInfinityDateTime { get; set; }

Property Value

Type	Description
bool

Database

The PostgreSQL database to connect to.

Declaration

public string? Database { get; set; }

Property Value

Type	Description
string?

Encoding

Gets or sets the .NET encoding that will be used to encode/decode PostgreSQL string data.

Declaration

public string Encoding { get; set; }

Property Value

Type	Description
string

Enlist

Whether to enlist in an ambient TransactionScope.

Declaration

public bool Enlist { get; set; }

Property Value

Type	Description
bool

EntityAdminDatabase

The database admin to specify when creating and dropping a database in Entity Framework. This is needed because Npgsql needs to connect to a database in order to send the create/drop database command. If not specified, defaults to "template1". Check NpgsqlServices.UsingPostgresDBConnection for more information.

Declaration

public string? EntityAdminDatabase { get; set; }

Property Value

Type	Description
string?

EntityTemplateDatabase

The database template to specify when creating a database in Entity Framework. If not specified, PostgreSQL defaults to "template1".

Declaration

public string? EntityTemplateDatabase { get; set; }

Property Value

Type	Description
string?

Remarks

https://www.postgresql.org/docs/current/static/manage-ag-templatedbs.html

Host

The hostname or IP address of the PostgreSQL server to connect to.

Declaration

public string? Host { get; set; }

Property Value

Type	Description
string?

HostRecheckSeconds

Controls for how long the host's cached state will be considered as valid.

Declaration

public int HostRecheckSeconds { get; set; }

Property Value

Type	Description
int

IncludeErrorDetail

When enabled, PostgreSQL error details are included on Detail and Detail. These can contain sensitive data.

Declaration

public bool IncludeErrorDetail { get; set; }

Property Value

Type	Description
bool

IncludeErrorDetails

When enabled, PostgreSQL error details are included on Detail and Detail. These can contain sensitive data.

Declaration

public bool IncludeErrorDetails { get; set; }

Property Value

Type	Description
bool

IncludeRealm

The Kerberos realm to be used for authentication.

Declaration

public bool IncludeRealm { get; set; }

Property Value

Type	Description
bool

IntegratedSecurity

Whether to use Windows integrated security to log in.

Declaration

public bool IntegratedSecurity { get; set; }

Property Value

Type	Description
bool

InternalCommandTimeout

The time to wait (in seconds) while trying to execute a an internal command before terminating the attempt and generating an error.

Declaration

public int InternalCommandTimeout { get; set; }

Property Value

Type	Description
int

this[string]

Gets or sets the value associated with the specified key.

Declaration

public override object this[string keyword] { get; set; }

Parameters

Type	Name	Description
string	keyword	The key of the item to get or set.

Property Value

Type	Description
object	The value associated with the specified key.

KeepAlive

The number of seconds of connection inactivity before Npgsql sends a keepalive query. Set to 0 (the default) to disable.

Declaration

public int KeepAlive { get; set; }

Property Value

Type	Description
int

KerberosServiceName

The Kerberos service name to be used for authentication.

Declaration

public string KerberosServiceName { get; set; }

Property Value

Type	Description
string

Keys

Gets an containing the keys of the NpgsqlConnectionStringBuilder.

Declaration

public ICollection<string> Keys { get; }

Property Value

Type	Description
ICollection<><string>

LoadBalanceHosts

Enables balancing between multiple hosts by round-robin.

Declaration

public bool LoadBalanceHosts { get; set; }

Property Value

Type	Description
bool

LoadTableComposites

Load table composite type definitions, and not just free-standing composite types.

Declaration

public bool LoadTableComposites { get; set; }

Property Value

Type	Description
bool

LogParameters

When enabled, parameter values are logged when commands are executed. Defaults to false.

Declaration

public bool LogParameters { get; set; }

Property Value

Type	Description
bool

MaxAutoPrepare

The maximum number SQL statements that can be automatically prepared at any given point. Beyond this number the least-recently-used statement will be recycled. Zero (the default) disables automatic preparation.

Declaration

public int MaxAutoPrepare { get; set; }

Property Value

Type	Description
int

MaxPoolSize

The maximum connection pool size.

Declaration

public int MaxPoolSize { get; set; }

Property Value

Type	Description
int

MinPoolSize

The minimum connection pool size.

Declaration

public int MinPoolSize { get; set; }

Property Value

Type	Description
int

Multiplexing

Enables multiplexing, which allows more efficient use of connections.

Declaration

public bool Multiplexing { get; set; }

Property Value

Type	Description
bool

NoResetOnClose

If set to true, a pool connection's state won't be reset when it is closed (improves performance). Do not specify this unless you know what you're doing.

Declaration

public bool NoResetOnClose { get; set; }

Property Value

Type	Description
bool

Options

Set PostgreSQL configuration parameter default values for the connection.

Declaration

public string? Options { get; set; }

Property Value

Type	Description
string?

Passfile

Path to a PostgreSQL password file (PGPASSFILE), from which the password would be taken.

Declaration

public string? Passfile { get; set; }

Property Value

Type	Description
string?

Password

The password to connect with. Not required if using IntegratedSecurity.

Declaration

public string? Password { get; set; }

Property Value

Type	Description
string?

PersistSecurityInfo

Gets or sets a Boolean value that indicates if security-sensitive information, such as the password, is not returned as part of the connection if the connection is open or has ever been in an open state.

Declaration

public bool PersistSecurityInfo { get; set; }

Property Value

Type	Description
bool

Pooling

Whether connection pooling should be used.

Declaration

public bool Pooling { get; set; }

Property Value

Type	Description
bool

Port

The TCP/IP port of the PostgreSQL server.

Declaration

public int Port { get; set; }

Property Value

Type	Description
int

PreloadReader

Obsolete, see https://www.npgsql.org/doc/release-notes/3.0.html

Declaration

public bool PreloadReader { get; set; }

Property Value

Type	Description
bool

ReadBufferSize

Determines the size of the internal buffer Npgsql uses when reading. Increasing may improve performance if transferring large values from the database.

Declaration

public int ReadBufferSize { get; set; }

Property Value

Type	Description
int

RootCertificate

Location of a CA certificate used to validate the server certificate.

Declaration

public string? RootCertificate { get; set; }

Property Value

Type	Description
string?

SearchPath

Gets or sets the schema search path.

Declaration

public string? SearchPath { get; set; }

Property Value

Type	Description
string?

ServerCompatibilityMode

A compatibility mode for special PostgreSQL server types.

Declaration

public ServerCompatibilityMode ServerCompatibilityMode { get; set; }

Property Value

Type	Description
ServerCompatibilityMode

SocketReceiveBufferSize

Determines the size of socket read buffer.

Declaration

public int SocketReceiveBufferSize { get; set; }

Property Value

Type	Description
int

SocketSendBufferSize

Determines the size of socket send buffer.

Declaration

public int SocketSendBufferSize { get; set; }

Property Value

Type	Description
int

SslCertificate

Location of a client certificate to be sent to the server.

Declaration

public string? SslCertificate { get; set; }

Property Value

Type	Description
string?

SslKey

Location of a client key for a client certificate to be sent to the server.

Declaration

public string? SslKey { get; set; }

Property Value

Type	Description
string?

SslMode

Controls whether SSL is required, disabled or preferred, depending on server support.

Declaration

public SslMode SslMode { get; set; }

Property Value

Type	Description
SslMode

SslPassword

Password for a key for a client certificate.

Declaration

public string? SslPassword { get; set; }

Property Value

Type	Description
string?

TargetSessionAttributes

Determines the preferred PostgreSQL target server type.

Declaration

public string? TargetSessionAttributes { get; set; }

Property Value

Type	Description
string?

TcpKeepAlive

Whether to use TCP keepalive with system defaults if overrides isn't specified.

Declaration

public bool TcpKeepAlive { get; set; }

Property Value

Type	Description
bool

TcpKeepAliveInterval

The interval, in seconds, between when successive keep-alive packets are sent if no acknowledgement is received. Defaults to the value of TcpKeepAliveTime. TcpKeepAliveTime must be non-zero as well.

Declaration

public int TcpKeepAliveInterval { get; set; }

Property Value

Type	Description
int

TcpKeepAliveTime

The number of seconds of connection inactivity before a TCP keepalive query is sent. Use of this option is discouraged, use KeepAlive instead if possible. Set to 0 (the default) to disable.

Declaration

public int TcpKeepAliveTime { get; set; }

Property Value

Type	Description
int

Timeout

The time to wait (in seconds) while trying to establish a connection before terminating the attempt and generating an error. Defaults to 15 seconds.

Declaration

public int Timeout { get; set; }

Property Value

Type	Description
int

Timezone

Gets or sets the PostgreSQL session timezone, in Olson/IANA database format.

Declaration

public string? Timezone { get; set; }

Property Value

Type	Description
string?

TrustServerCertificate

Whether to trust the server certificate without validating it.

Declaration

public bool TrustServerCertificate { get; set; }

Property Value

Type	Description
bool

UseExtendedTypes

Obsolete, see https://www.npgsql.org/doc/release-notes/3.0.html

Declaration

public bool UseExtendedTypes { get; set; }

Property Value

Type	Description
bool

UsePerfCounters

Writes connection performance information to performance counters.

Declaration

public bool UsePerfCounters { get; set; }

Property Value

Type	Description
bool

Username

The username to connect with. Not required if using IntegratedSecurity.

Declaration

public string? Username { get; set; }

Property Value

Type	Description
string?

UseSslStream

Obsolete, see https://www.npgsql.org/doc/release-notes/4.1.html

Declaration

public bool UseSslStream { get; set; }

Property Value

Type	Description
bool

Values

Gets an containing the values in the NpgsqlConnectionStringBuilder.

Declaration

public ICollection<object?> Values { get; }

Property Value

Type	Description
ICollection<><object?>

WriteBufferSize

Determines the size of the internal buffer Npgsql uses when writing. Increasing may improve performance if transferring large values to the database.

Declaration

public int WriteBufferSize { get; set; }

Property Value

Type	Description
int

WriteCoalescingBufferThresholdBytes

When multiplexing is enabled, determines the maximum number of outgoing bytes to buffer before flushing to the network.

Declaration

public int WriteCoalescingBufferThresholdBytes { get; set; }

Property Value

Type	Description
int

Methods

Add(KeyValuePair<string, object?>)

Adds an item to the NpgsqlConnectionStringBuilder.

Declaration

public void Add(KeyValuePair<string, object?> item)

Parameters

Type	Name	Description
KeyValuePair<, ><string, object?>	item	The key-value pair to be added.

Clear()

Clears the contents of the NpgsqlConnectionStringBuilder instance.

Declaration

public override void Clear()

Contains(KeyValuePair<string, object?>)

Determines whether the NpgsqlConnectionStringBuilder contains a specific key-value pair.

Declaration

public bool Contains(KeyValuePair<string, object?> item)

Parameters

Type	Name	Description
KeyValuePair<, ><string, object?>	item	The item to locate in the NpgsqlConnectionStringBuilder.

Returns

Type	Description
bool	true if the NpgsqlConnectionStringBuilder contains the entry; otherwise false.

ContainsKey(string)

Determines whether the NpgsqlConnectionStringBuilder contains a specific key.

Declaration

public override bool ContainsKey(string keyword)

Parameters

Type	Name	Description
string	keyword	The key to locate in the NpgsqlConnectionStringBuilder.

Returns

Type	Description
bool	true if the NpgsqlConnectionStringBuilder contains an entry with the specified key; otherwise false.

CopyTo(KeyValuePair<string, object?>[], int)

Copies the elements of the NpgsqlConnectionStringBuilder to an Array, starting at a particular Array index.

Declaration

public void CopyTo(KeyValuePair<string, object?>[] array, int arrayIndex)

Parameters

Type	Name	Description
KeyValuePair<, ><string, object?>[]	array	The one-dimensional Array that is the destination of the elements copied from NpgsqlConnectionStringBuilder. The Array must have zero-based indexing.
int	arrayIndex	The zero-based index in array at which copying begins.

Equals(object?)

Determines whether the specified object is equal to the current object.

Declaration

public override bool Equals(object? obj)

Parameters

Type	Name	Description
object?	obj

Returns

Type	Description
bool

GetEnumerator()

Returns an enumerator that iterates through the NpgsqlConnectionStringBuilder.

Declaration

public IEnumerator<KeyValuePair<string, object?>> GetEnumerator()

Returns

Type	Description
IEnumerator<><KeyValuePair<, ><string, object?>>

GetHashCode()

Hash function.

Declaration

public override int GetHashCode()

Returns

Type	Description
int

GetProperties(Hashtable)

Declaration

protected override void GetProperties(Hashtable propertyDescriptors)

Parameters

Type	Name	Description
Hashtable	propertyDescriptors

Remove(KeyValuePair<string, object?>)

Removes the entry from the DbConnectionStringBuilder instance.

Declaration

public bool Remove(KeyValuePair<string, object?> item)

Parameters

Type	Name	Description
KeyValuePair<, ><string, object?>	item	The key/value pair to be removed from the connection string in this DbConnectionStringBuilder.

Returns

Type	Description
bool	true if the key existed within the connection string and was removed; false if the key did not exist.

Remove(string)

Removes the entry with the specified key from the DbConnectionStringBuilder instance.

Declaration

public override bool Remove(string keyword)

Parameters

Type	Name	Description
string	keyword	The key of the key/value pair to be removed from the connection string in this DbConnectionStringBuilder.

Returns

Type	Description
bool	true if the key existed within the connection string and was removed; false if the key did not exist.

TryGetValue(string, out object?)

Retrieves a value corresponding to the supplied key from this NpgsqlConnectionStringBuilder.

Declaration

public override bool TryGetValue(string keyword, out object? value)

Parameters

Type	Name	Description
string	keyword	The key of the item to retrieve.
object?	value	The value corresponding to the key.

Returns

Type	Description
bool	true if keyword was found within the connection string, false otherwise.

Implements

IDictionary<, >