# Class NpgsqlConnectionStringBuilder

Namespace
  Npgsql

Assembly
  Npgsql.dll

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

    [UnconditionalSuppressMessage("ReflectionAnalysis", "IL2112:ReflectionToRequiresUnreferencedCode", Justification = "Suppressing the same warnings as suppressed in the base DbConnectionStringBuilder. See https://github.com/dotnet/runtime/issues/97057")]
    [UnconditionalSuppressMessage("ReflectionAnalysis", "IL2113:ReflectionToRequiresUnreferencedCode", Justification = "Suppressing the same warnings as suppressed in the base DbConnectionStringBuilder. See https://github.com/dotnet/runtime/issues/97057")]
    public sealed class NpgsqlConnectionStringBuilder : DbConnectionStringBuilder, IDictionary, ICollection, ICustomTypeDescriptor, IDictionary<string, object?>, ICollection<KeyValuePair<string, object?>>, IEnumerable<KeyValuePair<string, object?>>, IEnumerable

Inheritance
  object
  DbConnectionStringBuilder
  NpgsqlConnectionStringBuilder

Implements
  IDictionary
  ICollection
  ICustomTypeDescriptor
  IDictionary<string, object>
  ICollection<KeyValuePair<string, object>>
  IEnumerable<KeyValuePair<string, object>>
  IEnumerable

Inherited Members
  DbConnectionStringBuilder.Add(string, object)
  DbConnectionStringBuilder.AppendKeyValuePair(StringBuilder, string, string)
  DbConnectionStringBuilder.AppendKeyValuePair(StringBuilder, string, string, bool)
  DbConnectionStringBuilder.EquivalentTo(DbConnectionStringBuilder)
  DbConnectionStringBuilder.ShouldSerialize(string)
  DbConnectionStringBuilder.ToString()
  DbConnectionStringBuilder.ConnectionString
  DbConnectionStringBuilder.Count
  DbConnectionStringBuilder.IsFixedSize
  DbConnectionStringBuilder.IsReadOnly
  object.Equals(object, object)
  object.GetType()
  object.ReferenceEquals(object, object)

## Constructors

### NpgsqlConnectionStringBuilder()

Initializes a new instance of the NpgsqlConnectionStringBuilder class.

    public NpgsqlConnectionStringBuilder()

### NpgsqlConnectionStringBuilder(bool)

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

    public NpgsqlConnectionStringBuilder(bool useOdbcRules)

#### Parameters

`useOdbcRules` bool

  true to use {} to delimit fields; false to use quotation marks.

### NpgsqlConnectionStringBuilder(string?)

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

    public NpgsqlConnectionStringBuilder(string? connectionString)

#### Parameters

`connectionString` string

## Properties

### ApplicationName

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

    public string? ApplicationName { get; set; }

#### Property Value

string

### ArrayNullabilityMode

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

    public ArrayNullabilityMode ArrayNullabilityMode { get; set; }

#### Property Value

ArrayNullabilityMode

### AutoPrepareMinUsages

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

    public int AutoPrepareMinUsages { get; set; }

#### Property Value

int

### 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.

    public int CancellationTimeout { get; set; }

#### Property Value

int

### ChannelBinding

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

    public ChannelBinding ChannelBinding { get; set; }

#### Property Value

ChannelBinding

### CheckCertificateRevocation

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

    public bool CheckCertificateRevocation { get; set; }

#### Property Value

bool

### ClientEncoding

Gets or sets the client_encoding parameter.

    public string? ClientEncoding { get; set; }

#### Property Value

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.

    public int CommandTimeout { get; set; }

#### Property Value

int

### ConnectionIdleLifetime

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

    public int ConnectionIdleLifetime { get; set; }

#### Property Value

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. It can also be useful to prevent runaway memory growth of connections at the PostgreSQL server side, because in some cases very long lived connections slowly consume more and more memory over time. Defaults to 3600 seconds (1 hour).

    public int ConnectionLifetime { get; set; }

#### Property Value

int

  The time (in seconds) to wait, or 0 to to make connections last indefinitely.

### ConnectionPruningInterval

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

    public int ConnectionPruningInterval { get; set; }

#### Property Value

int

  The interval (in seconds). The default value is 10.

### Database

The PostgreSQL database to connect to.

    public string? Database { get; set; }

#### Property Value

string

### EnableFdwAcs

Gets or sets the postgres_scaleout_fdw target server.

    public string EnableFdwAcs { get; set; }

#### Property Value

string

### Encoding

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

    public string Encoding { get; set; }

#### Property Value

string

### Enlist

Whether to enlist in an ambient TransactionScope.

    public bool Enlist { get; set; }

#### Property Value

bool

### GssEncryptionMode

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

    public GssEncryptionMode GssEncryptionMode { get; set; }

#### Property Value

GssEncryptionMode

### Host

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

    public string? Host { get; set; }

#### Property Value

string

### HostRecheckSeconds

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

    public int HostRecheckSeconds { get; set; }

#### Property Value

int

### IncludeErrorDetail

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

    public bool IncludeErrorDetail { get; set; }

#### Property Value

bool

### IncludeFailedBatchedCommand

When enabled, failed statements are included on BatchCommand.

    public bool IncludeFailedBatchedCommand { get; set; }

#### Property Value

bool

### IncludeRealm

The Kerberos realm to be used for authentication.

    public bool IncludeRealm { get; set; }

#### Property Value

bool

### InternalCommandTimeout

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

    [Obsolete("The InternalCommandTimeout parameter is no longer needed and does nothing.")]
    public int InternalCommandTimeout { get; set; }

#### Property Value

int

### this[string]

Gets or sets the value associated with the specified key.

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

#### Parameters

`keyword` string

  The key of the item to get or set.

#### Property Value

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.

    public int KeepAlive { get; set; }

#### Property Value

int

### KerberosServiceName

The Kerberos service name to be used for authentication.

    public string KerberosServiceName { get; set; }

#### Property Value

string

### Keys

Gets an ICollection containing the keys of the NpgsqlConnectionStringBuilder.

    public ICollection<string> Keys { get; }

#### Property Value

ICollection<string>

### LoadBalanceHosts

Enables balancing between multiple hosts by round-robin.

    public bool LoadBalanceHosts { get; set; }

#### Property Value

bool

### LoadTableComposites

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

    [Obsolete("Specifying type loading options through the connection string is obsolete, use the DataSource builder instead. See the 9.0 release notes for more information.")]
    public bool LoadTableComposites { get; set; }

#### Property Value

bool

### LogParameters

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

    public bool LogParameters { get; set; }

#### Property Value

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.

    public int MaxAutoPrepare { get; set; }

#### Property Value

int

### MaxPoolSize

The maximum connection pool size.

    public int MaxPoolSize { get; set; }

#### Property Value

int

### MinPoolSize

The minimum connection pool size.

    public int MinPoolSize { get; set; }

#### Property Value

int

### Multiplexing

Enables multiplexing, which allows more efficient use of connections.

    public bool Multiplexing { get; set; }

#### Property Value

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.

    public bool NoResetOnClose { get; set; }

#### Property Value

bool

### Options

Set PostgreSQL configuration parameter default values for the connection.

    public string? Options { get; set; }

#### Property Value

string

### Passfile

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

    public string? Passfile { get; set; }

#### Property Value

string

### Password

The password to connect with.

    public string? Password { get; set; }

#### Property Value

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.

    public bool PersistSecurityInfo { get; set; }

#### Property Value

bool

### Pooling

Whether connection pooling should be used.

    public bool Pooling { get; set; }

#### Property Value

bool

### Port

The TCP/IP port of the PostgreSQL server.

    public int Port { get; set; }

#### Property Value

int

### ReadBufferSize

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

    public int ReadBufferSize { get; set; }

#### Property Value

int

### RequireAuth

Controls the available authentication methods.

    public string? RequireAuth { get; set; }

#### Property Value

string

### RootCertificate

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

    public string? RootCertificate { get; set; }

#### Property Value

string

### SearchPath

Gets or sets the schema search path.

    public string? SearchPath { get; set; }

#### Property Value

string

### ServerCompatibilityMode

A compatibility mode for special PostgreSQL server types.

    [Obsolete("Specifying type loading options through the connection string is obsolete, use the DataSource builder instead. See the 9.0 release notes for more information.")]
    public ServerCompatibilityMode ServerCompatibilityMode { get; set; }

#### Property Value

ServerCompatibilityMode

### SocketReceiveBufferSize

Determines the size of socket read buffer.

    public int SocketReceiveBufferSize { get; set; }

#### Property Value

int

### SocketSendBufferSize

Determines the size of socket send buffer.

    public int SocketSendBufferSize { get; set; }

#### Property Value

int

### SslCertificate

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

    public string? SslCertificate { get; set; }

#### Property Value

string

### SslKey

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

    public string? SslKey { get; set; }

#### Property Value

string

### SslMode

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

    public SslMode SslMode { get; set; }

#### Property Value

SslMode

### SslNegotiation

Controls how SSL encryption is negotiated with the server, if SSL is used.

    public SslNegotiation SslNegotiation { get; set; }

#### Property Value

SslNegotiation

### SslPassword

Password for a key for a client certificate.

    public string? SslPassword { get; set; }

#### Property Value

string

### TargetSessionAttributes

Determines the preferred PostgreSQL target server type.

    public string? TargetSessionAttributes { get; set; }

#### Property Value

string

### TcpKeepAlive

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

    public bool TcpKeepAlive { get; set; }

#### Property Value

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.

    public int TcpKeepAliveInterval { get; set; }

#### Property Value

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.

    public int TcpKeepAliveTime { get; set; }

#### Property Value

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.

    public int Timeout { get; set; }

#### Property Value

int

### Timezone

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

    public string? Timezone { get; set; }

#### Property Value

string

### TrustServerCertificate

Whether to trust the server certificate without validating it.

    [Obsolete("The TrustServerCertificate parameter is no longer needed and does nothing.")]
    public bool TrustServerCertificate { get; set; }

#### Property Value

bool

### Username

The username to connect with.

    public string? Username { get; set; }

#### Property Value

string

### Values

Gets an ICollection containing the values in the NpgsqlConnectionStringBuilder.

    public ICollection<object?> Values { get; }

#### Property Value

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.

    public int WriteBufferSize { get; set; }

#### Property Value

int

### WriteCoalescingBufferThresholdBytes

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

    public int WriteCoalescingBufferThresholdBytes { get; set; }

#### Property Value

int

## Methods

### Add(KeyValuePair<string, object?>)

Adds an item to the NpgsqlConnectionStringBuilder.

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

#### Parameters

`item` KeyValuePair<string, object>

  The key-value pair to be added.

### Clear()

Clears the contents of the NpgsqlConnectionStringBuilder instance.

    public override void Clear()

### Contains(KeyValuePair<string, object?>)

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

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

#### Parameters

`item` KeyValuePair<string, object>

  The item to locate in the NpgsqlConnectionStringBuilder.

#### Returns

bool

  true if the NpgsqlConnectionStringBuilder contains the entry; otherwise false.

### ContainsKey(string)

Determines whether the NpgsqlConnectionStringBuilder contains a specific key.

    public override bool ContainsKey(string keyword)

#### Parameters

`keyword` string

  The key to locate in the NpgsqlConnectionStringBuilder.

#### Returns

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.

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

#### Parameters

`array` KeyValuePair<string, object>[]

  The one-dimensional Array that is the destination of the elements copied from NpgsqlConnectionStringBuilder. The Array must have zero-based indexing.

`arrayIndex` int

  The zero-based index in array at which copying begins.

### Equals(object?)

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

    public override bool Equals(object? obj)

#### Parameters

`obj` object

#### Returns

bool

### GetEnumerator()

Returns an enumerator that iterates through the NpgsqlConnectionStringBuilder.

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

#### Returns

IEnumerator<KeyValuePair<string, object>>

### GetHashCode()

Hash function.

    public override int GetHashCode()

#### Returns

int

### GetProperties(Hashtable)

Fills a supplied Hashtable with information about all the properties of this DbConnectionStringBuilder.

    [RequiresUnreferencedCode("PropertyDescriptor's PropertyType cannot be statically discovered.")]
    protected override void GetProperties(Hashtable propertyDescriptors)

#### Parameters

`propertyDescriptors` Hashtable

  The Hashtable to be filled with information about this DbConnectionStringBuilder.

### Remove(KeyValuePair<string, object?>)

Removes the entry from the DbConnectionStringBuilder instance.

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

#### Parameters

`item` KeyValuePair<string, object>

  The key/value pair to be removed from the connection string in this DbConnectionStringBuilder.

#### Returns

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.

    public override bool Remove(string keyword)

#### Parameters

`keyword` string

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

#### Returns

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.

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

#### Parameters

`keyword` string

  The key of the item to retrieve.

`value` object

  The value corresponding to the key.

#### Returns

bool

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