To connect to a database, the application provides a connection string which specifies parameters such as the host, the username, the password, etc. Connection strings have the form keyword1=value; keyword2=value; and are case-insensitive. Values containing special characters (e.g. semicolons) can be double-quoted. For more information, see the official doc page on connection strings.
Below are the connection string parameters which Npgsql understands, as well as some standard PostgreSQL environment variables.
Basic connection
Parameter
Description
Default
Host
Specifies the host name - and optionally port - on which PostgreSQL is running. Multiple hosts may be specified, see the docs for more info. If the value begins with a slash, it is used as the directory for the Unix-domain socket (specifying a Port is still required).
Required
Port
The TCP port of the PostgreSQL server.
5432
Database
The PostgreSQL database to connect to.
Same as Username
Username
The username to connect with. If not specified, the OS username will be used.
PGUSER
Password
The password to connect with. Not required if using GSS/SSPI.
PGPASSWORD
Passfile
Path to a PostgreSQL password file (PGPASSFILE), from which the password is taken.
Control whether channel binding is used when authenticating with SASL. Introduced in 8.0.
Prefer
Persist Security Info
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.
When enabled, parameter values are logged when commands are executed.
false
Pooling
Parameter
Description
Default
Pooling
Whether connection pooling should be used.
true
Minimum Pool Size
The minimum connection pool size.
0
Maximum Pool Size
The maximum connection pool size.
100 since 3.1, 20 previously
Connection Idle Lifetime
The time (in seconds) to wait before closing idle connections in the pool if the count of all connections exceeds Minimum Pool Size. Introduced in 3.1.
300
Connection Pruning Interval
How many seconds the pool waits before attempting to prune idle connections that are beyond idle lifetime (see Connection Idle Lifetime). Introduced in 3.1.
10
Connection Lifetime
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.
3600 (1 hour), in Npgsql 8.0 and before - 0 (disabled)
Timeouts and keepalive
Parameter
Description
Default
Timeout
The time to wait (in seconds) while trying to establish a connection before terminating the attempt and generating an error.
15
Command Timeout
The time to wait (in seconds) while trying to execute a command before terminating the attempt and generating an error. Set to zero for infinity.
30
Cancellation Timeout
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. -1 skips the wait, 0 means infinite wait. Introduced in 5.0.
2000
Keepalive
The number of seconds of connection inactivity before Npgsql sends a keepalive query.
0 (disabled)
Tcp Keepalive
Whether to use TCP keepalive with system defaults if overrides isn't specified.
false
Tcp Keepalive Time
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.
0 (disabled)
Tcp Keepalive Interval
The interval, in seconds, between when successive keep-alive packets are sent if no acknowledgement is received. Tcp KeepAlive Time must be non-zero as well.
value of Tcp Keepalive Time
Performance
Parameter
Description
Default
Max Auto Prepare
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 disables automatic preparation.
0
Auto Prepare Min Usages
The minimum number of usages an SQL statement is used before it's automatically prepared.
5
Read Buffer Size
Determines the size of the internal buffer Npgsql uses when reading. Increasing may improve performance if transferring large values from the database.
8192
Write Buffer Size
Determines the size of the internal buffer Npgsql uses when writing. Increasing may improve performance if transferring large values to the database.
8192
Socket Receive Buffer Size
Determines the size of socket receive buffer.
System-dependent
Socket Send Buffer Size
Determines the size of socket send buffer.
System-dependent
No Reset On Close
Improves performance in some cases by not resetting the connection state when it is returned to the pool, at the cost of leaking state. Use only if benchmarking shows a performance improvement
The optional application name parameter to be sent to the backend during connection initiation.
PGAPPNAME
Enlist
Whether to enlist in an ambient TransactionScope.
true
Search Path
Sets the schema search path.
Client Encoding
Gets or sets the client_encoding parameter.
PGCLIENTENCODING, UTF8
Encoding
Gets or sets the .NET encoding that will be used to encode/decode PostgreSQL string data.
UTF8
Timezone
Gets or sets the session timezone.
PGTZ
Array Nullability Mode
Configure the way arrays of value types are returned when requested as object instances. Possible values are: Never (arrays of value types are always returned as non-nullable arrays), Always (arrays of value types are always returned as nullable arrays) and PerInstance (the type of array that gets returned is determined at runtime).
Never
1The Options connection string parameter is essentially the string of command line options that get passed to the postgres program when the process is started.
It is most commonly used to set named run-time parameters via the -c option but other options can be used too (although not all of them make sense in that context).
Setting multiple options is possible by separating them with a space character. Space and backslash characters in option values need to be escaped by prefixing a backslash character.
Example: Options=-c default_transaction_isolation=serializable -c default_transaction_deferrable=on -c foo.bar=My\\ Famous\\\\Thing
Obsolete/removed
Parameter
Description
Default
Load Table Composites
Load table composite type definitions, and not just free-standing composite types. Obsoleted in 9.0, use NpgsqlDataSourceBuilder.ConfigureTypeLoading().
false
Server Compatibility Mode
A compatibility mode for special PostgreSQL server types. Currently "Redshift" is supported, as well as "NoTypeLoading", which will bypass the normal type loading mechanism from the PostgreSQL catalog tables and supports a hardcoded list of basic types. Obsoleted in 9.0, use NpgsqlDataSourceBuilder.ConfigureTypeLoading().
none
Internal Command Timeout
The time to wait (in seconds) while trying to execute an internal command before terminating the attempt and generating an error. -1 uses CommandTimeout, 0 means no timeout.
-1
EF Template Database
The database template to specify when creating a database in non-core Entity Framework. Removed in 8.0.
template1
EF Admin Database
The database admin to specify when creating and dropping a database in non-core Entity Framework. Removed in 8.0.
template1
Environment variables
In addition to the connection string parameters above, Npgsql also recognizes the standard PostgreSQL environment variables below. This helps Npgsql-based applications behave similar to other, non-.NET PostgreSQL client applications. The PostgreSQL doc page on environment variables recognized by libpq can be found here.
Environment variable
Description
PGUSER
Behaves the same as the user connection parameter.
PGPASSWORD
Behaves the same as the password connection parameter. Use of this environment variable is not recommended for security reasons, as some operating systems allow non-root users to see process environment variables via ps; instead consider using a password file (see Section 33.15).
PGPASSFILE
Behaves the same as the passfile connection parameter.
PGSSLCERT
Behaves the same as the sslcert connection parameter.
PGSSLKEY
Behaves the same as the sslkey connection parameter.
PGSSLROOTCERT
Behaves the same as the sslrootcert connection parameter.
PGCLIENTENCODING
Behaves the same as the client_encoding connection parameter.
PGTZ
Sets the default time zone. (Equivalent to SET timezone TO ....)
PGOPTIONS
Behaves the same as the options connection parameter.