Class NpgsqlDataSourceBuilder

Provides a simple API for configuring and creating an NpgsqlDataSource, from which database connections can be obtained.

Inheritance

object

NpgsqlDataSourceBuilder

Implements

INpgsqlTypeMapper

Namespace: Npgsql

Assembly: Npgsql.dll

Syntax

public sealed class NpgsqlDataSourceBuilder : INpgsqlTypeMapper

Constructors

| Improve this Doc View Source

NpgsqlDataSourceBuilder(string?)

Constructs a new NpgsqlDataSourceBuilder, optionally starting out from the given connectionString.

Declaration

public NpgsqlDataSourceBuilder(string? connectionString = null)

Parameters

Type	Name	Description
string?	connectionString

Properties

| Improve this Doc View Source

ConnectionString

Returns the connection string, as currently configured on the builder.

Declaration

public string ConnectionString { get; }

Property Value

Type	Description
string

| Improve this Doc View Source

ConnectionStringBuilder

A connection string builder that can be used to configured the connection string on the builder.

Declaration

public NpgsqlConnectionStringBuilder ConnectionStringBuilder { get; }

Property Value

Type	Description
NpgsqlConnectionStringBuilder

| Improve this Doc View Source

DefaultNameTranslator

The default name translator to convert CLR type names and member names. Defaults to NpgsqlSnakeCaseNameTranslator.

Declaration

public INpgsqlNameTranslator DefaultNameTranslator { get; set; }

Property Value

Type	Description
INpgsqlNameTranslator

| Improve this Doc View Source

Name

A diagnostics name used by Npgsql when generating tracing, logging and metrics.

Declaration

public string? Name { get; set; }

Property Value

Type	Description
string?

Methods

| Improve this Doc View Source

AddTypeInfoResolver(IPgTypeInfoResolver)

Adds a type info resolver which can add or modify support for PostgreSQL types. Typically used by plugins.

Declaration

public void AddTypeInfoResolver(IPgTypeInfoResolver resolver)

Parameters

Type	Name	Description
IPgTypeInfoResolver	resolver	The type resolver to be added.

| Improve this Doc View Source

Build()

Builds and returns an NpgsqlDataSource which is ready for use.

Declaration

public NpgsqlDataSource Build()

Returns

Type	Description
NpgsqlDataSource

| Improve this Doc View Source

BuildMultiHost()

Builds and returns a NpgsqlMultiHostDataSource which is ready for use for load-balancing and failover scenarios.

Declaration

public NpgsqlMultiHostDataSource BuildMultiHost()

Returns

Type	Description
NpgsqlMultiHostDataSource

| Improve this Doc View Source

EnableParameterLogging(bool)

Enables parameters to be included in logging. This includes potentially sensitive information from data sent to PostgreSQL. You should only enable this flag in development, or if you have the appropriate security measures in place based on the sensitivity of this data.

Declaration

public NpgsqlDataSourceBuilder EnableParameterLogging(bool parameterLoggingEnabled = true)

Parameters

Type	Name	Description
bool	parameterLoggingEnabled	If true, then sensitive data is logged.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

| Improve this Doc View Source

MapComposite(Type, string?, INpgsqlNameTranslator?)

Maps a CLR type to a composite type.

Declaration

public INpgsqlTypeMapper MapComposite(Type clrType, string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

Type	Name	Description
Type	clrType	The .NET type to be mapped.
string?	pgName	A PostgreSQL type name for the corresponding composite type in the database. If null, the name translator given in `nameTranslator` will be used.
INpgsqlNameTranslator	nameTranslator	A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

Type	Description
INpgsqlTypeMapper

Remarks

Maps CLR fields and properties by string to PostgreSQL names. The translation strategy can be controlled by the nameTranslator parameter, which defaults to DefaultNameTranslator. If there is a discrepancy between the .NET type and database type while a composite is read or written, an exception will be raised.

| Improve this Doc View Source

MapComposite<T>(string?, INpgsqlNameTranslator?)

Maps a CLR type to a PostgreSQL composite type.

Declaration

public INpgsqlTypeMapper MapComposite<T>(string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

Type	Name	Description
string?	pgName	A PostgreSQL type name for the corresponding composite type in the database. If null, the name translator given in `nameTranslator` will be used.
INpgsqlNameTranslator	nameTranslator	A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

Type	Description
INpgsqlTypeMapper

Type Parameters

Name	Description
T	The .NET type to be mapped

Remarks

CLR fields and properties by string to PostgreSQL names. The translation strategy can be controlled by the nameTranslator parameter, which defaults to NpgsqlSnakeCaseNameTranslator. You can also use the PgNameAttribute on your members to manually specify a PostgreSQL name. If there is a discrepancy between the .NET type and database type while a composite is read or written, an exception will be raised.

| Improve this Doc View Source

MapEnum<TEnum>(string?, INpgsqlNameTranslator?)

Maps a CLR enum to a PostgreSQL enum type.

Declaration

public INpgsqlTypeMapper MapEnum<TEnum>(string? pgName = null, INpgsqlNameTranslator? nameTranslator = null) where TEnum : struct, Enum

Parameters

Type	Name	Description
string?	pgName	A PostgreSQL type name for the corresponding enum type in the database. If null, the name translator given in `nameTranslator` will be used.
INpgsqlNameTranslator	nameTranslator	A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

Type	Description
INpgsqlTypeMapper

Type Parameters

Name	Description
TEnum	The .NET enum type to be mapped

Remarks

CLR enum labels are mapped by name to PostgreSQL enum labels. The translation strategy can be controlled by the nameTranslator parameter, which defaults to NpgsqlSnakeCaseNameTranslator. You can also use the PgNameAttribute on your enum fields to manually specify a PostgreSQL enum label. If there is a discrepancy between the .NET and database labels while an enum is read or written, an exception will be raised.

| Improve this Doc View Source

UnmapComposite(Type, string?, INpgsqlNameTranslator?)

Removes an existing composite mapping.

Declaration

public bool UnmapComposite(Type clrType, string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

Type	Name	Description
Type	clrType	The .NET type to be unmapped.
string?	pgName	A PostgreSQL type name for the corresponding composite type in the database. If null, the name translator given in `nameTranslator` will be used.
INpgsqlNameTranslator	nameTranslator	A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

Type	Description
bool

| Improve this Doc View Source

UnmapComposite<T>(string?, INpgsqlNameTranslator?)

Removes an existing composite mapping.

Declaration

public bool UnmapComposite<T>(string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

Type	Name	Description
string?	pgName	A PostgreSQL type name for the corresponding composite type in the database. If null, the name translator given in `nameTranslator` will be used.
INpgsqlNameTranslator	nameTranslator	A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to NpgsqlSnakeCaseNameTranslator

Returns

Type	Description
bool

Type Parameters

Name	Description
T

| Improve this Doc View Source

UnmapEnum<TEnum>(string?, INpgsqlNameTranslator?)

Removes an existing enum mapping.

Declaration

public bool UnmapEnum<TEnum>(string? pgName = null, INpgsqlNameTranslator? nameTranslator = null) where TEnum : struct, Enum

Parameters

Type	Name	Description
string?	pgName	A PostgreSQL type name for the corresponding enum type in the database. If null, the name translator given in `nameTranslator` will be used.
INpgsqlNameTranslator	nameTranslator	A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

Type	Description
bool

Type Parameters

Name	Description
TEnum

| Improve this Doc View Source

UseClientCertificate(X509Certificate?)

Specifies an SSL/TLS certificate which Npgsql will send to PostgreSQL for certificate-based authentication.

Declaration

public NpgsqlDataSourceBuilder UseClientCertificate(X509Certificate? clientCertificate)

Parameters

Type	Name	Description
X509Certificate?	clientCertificate	The client certificate to be sent to PostgreSQL when opening a connection.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

| Improve this Doc View Source

UseClientCertificates(X509CertificateCollection?)

Specifies a collection of SSL/TLS certificates which Npgsql will send to PostgreSQL for certificate-based authentication.

Declaration

public NpgsqlDataSourceBuilder UseClientCertificates(X509CertificateCollection? clientCertificates)

Parameters

Type	Name	Description
X509CertificateCollection?	clientCertificates	The client certificate collection to be sent to PostgreSQL when opening a connection.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

| Improve this Doc View Source

UseClientCertificatesCallback(Action<X509CertificateCollection>?)

Specifies a callback to modify the collection of SSL/TLS client certificates which Npgsql will send to PostgreSQL for certificate-based authentication. This is an advanced API, consider using UseClientCertificate(X509Certificate?) or UseClientCertificates(X509CertificateCollection?) instead.

Declaration

public NpgsqlDataSourceBuilder UseClientCertificatesCallback(Action<X509CertificateCollection>? clientCertificatesCallback)

Parameters

Type	Name	Description
Action<><X509CertificateCollection>?	clientCertificatesCallback	The callback to modify the client certificate collection.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

Remarks

The callback is invoked every time a physical connection is opened, and is therefore suitable for rotating short-lived client certificates. Simply make sure the certificate collection argument has the up-to-date certificate(s).

The callback's collection argument already includes any client certificates specified via the connection string or environment variables.

| Improve this Doc View Source

UseLoggerFactory(ILoggerFactory?)

Sets the that will be used for logging.

Declaration

public NpgsqlDataSourceBuilder UseLoggerFactory(ILoggerFactory? loggerFactory)

Parameters

Type	Name	Description
ILoggerFactory?	loggerFactory	The logger factory to be used.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

| Improve this Doc View Source

UsePeriodicPasswordProvider(Func<NpgsqlConnectionStringBuilder, CancellationToken, ValueTask<string>>?, TimeSpan, TimeSpan)

Configures a periodic password provider, which is automatically called by the data source at some regular interval. This is the recommended way to fetch a rotating access token.

Declaration

public NpgsqlDataSourceBuilder UsePeriodicPasswordProvider(Func<NpgsqlConnectionStringBuilder, CancellationToken, ValueTask<string>>? passwordProvider, TimeSpan successRefreshInterval, TimeSpan failureRefreshInterval)

Parameters

Type	Name	Description
Func<, , ><NpgsqlConnectionStringBuilder, CancellationToken, ValueTask<><string>>?	passwordProvider	A callback which returns the password to be sent to PostgreSQL.
TimeSpan	successRefreshInterval	How long to cache the password before re-invoking the callback.
TimeSpan	failureRefreshInterval	If a password refresh attempt fails, it will be re-attempted with this interval. This should typically be much lower than `successRefreshInterval`.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

Remarks

The provided callback is invoked in a timer, and not when opening connections. It therefore doesn't affect opening time.

The provided cancellation token is only triggered when the entire data source is disposed. If you'd like to apply a timeout to the token fetching, do so within the provided callback.

| Improve this Doc View Source

UsePhysicalConnectionInitializer(Action<NpgsqlConnection>?, Func<NpgsqlConnection, Task>?)

Register a connection initializer, which allows executing arbitrary commands when a physical database connection is first opened.

Declaration

public NpgsqlDataSourceBuilder UsePhysicalConnectionInitializer(Action<NpgsqlConnection>? connectionInitializer, Func<NpgsqlConnection, Task>? connectionInitializerAsync)

Parameters

Type	Name	Description
Action<><NpgsqlConnection>?	connectionInitializer	A synchronous connection initialization lambda, which will be called from Open() when a new physical connection is opened.
Func<, ><NpgsqlConnection, Task>?	connectionInitializerAsync	An asynchronous connection initialization lambda, which will be called from OpenAsync(CancellationToken) when a new physical connection is opened.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

Remarks

If an initializer is registered, both sync and async versions must be provided. If you do not use sync APIs in your code, simply throw , which would also catch accidental cases of sync opening.

| Improve this Doc View Source

UseRootCertificate(X509Certificate2?)

Sets the that will be used validate SSL certificate, received from the server.

Declaration

public NpgsqlDataSourceBuilder UseRootCertificate(X509Certificate2? rootCertificate)

Parameters

Type	Name	Description
X509Certificate2?	rootCertificate	The CA certificate.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

| Improve this Doc View Source

UseRootCertificateCallback(Func<X509Certificate2>?)

Specifies a callback that will be used to validate SSL certificate, received from the server.

Declaration

public NpgsqlDataSourceBuilder UseRootCertificateCallback(Func<X509Certificate2>? rootCertificateCallback)

Parameters

Type	Name	Description
Func<><X509Certificate2>?	rootCertificateCallback	The callback to get CA certificate.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

Remarks

This overload, which accepts a callback, is suitable for scenarios where the certificate rotates and might change during the lifetime of the application. When that's not the case, use the overload which directly accepts the certificate.

| Improve this Doc View Source

UseUserCertificateValidationCallback(RemoteCertificateValidationCallback)

When using SSL/TLS, this is a callback that allows customizing how the PostgreSQL-provided certificate is verified. This is an advanced API, consider using VerifyFull or VerifyCA instead.

Declaration

public NpgsqlDataSourceBuilder UseUserCertificateValidationCallback(RemoteCertificateValidationCallback userCertificateValidationCallback)

Parameters

Type	Name	Description
RemoteCertificateValidationCallback	userCertificateValidationCallback	The callback containing custom callback verification logic.

Returns

Type	Description
NpgsqlDataSourceBuilder	The same builder instance so that multiple calls can be chained.

Remarks

Cannot be used in conjunction with Disable, VerifyCA or VerifyFull.

See https://msdn.microsoft.com/en-us/library/system.net.security.remotecertificatevalidationcallback(v=vs.110).aspx.

Explicit Interface Implementations

| Improve this Doc View Source

INpgsqlTypeMapper.Reset()

Resets all mapping changes performed on this type mapper and reverts it to its original, starting state.

Declaration

void INpgsqlTypeMapper.Reset()

Implements

INpgsqlTypeMapper