Search Results for

    Show / Hide Table of Contents

    Class NpgsqlDataSourceBuilder

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

    Inheritance
    Object
    NpgsqlDataSourceBuilder
    Implements
    INpgsqlTypeMapper
    Inherited Members
    Object.Equals(Object)
    Object.Equals(Object, Object)
    Object.GetHashCode()
    Object.GetType()
    Object.MemberwiseClone()
    Object.ReferenceEquals(Object, Object)
    Object.ToString()
    Namespace: Npgsql
    Assembly: Npgsql.dll
    Syntax
    public 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

    Methods

    | Improve this Doc View Source

    AddTypeResolverFactory(TypeHandlerResolverFactory)

    Adds a type resolver factory, which produces resolvers that can add or modify support for PostgreSQL types. Typically used by plugins.

    Declaration
    public void AddTypeResolverFactory(TypeHandlerResolverFactory resolverFactory)
    Parameters
    Type Name Description
    TypeHandlerResolverFactory resolverFactory

    The type resolver factory 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(Boolean)

    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
    Boolean 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
    Boolean
    | 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
    Boolean
    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
    Boolean
    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(Nullable<ILoggerFactory>)

    Sets the that will be used for logging.

    Declaration
    public NpgsqlDataSourceBuilder UseLoggerFactory(ILoggerFactory? loggerFactory)
    Parameters
    Type Name Description
    Nullable<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 NotSupportedException, which would also catch accidental cases of sync opening.

    | 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()

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

    Declaration
    void INpgsqlTypeMapper.Reset()

    Implements

    INpgsqlTypeMapper

    Extension Methods

    NpgsqlGeoJSONExtensions.UseGeoJson(INpgsqlTypeMapper, GeoJSONOptions, Boolean)
    NpgsqlJsonNetExtensions.UseJsonNet(INpgsqlTypeMapper, Type[], Type[], Nullable<JsonSerializerSettings>)
    NpgsqlNetTopologySuiteExtensions.UseNetTopologySuite(INpgsqlTypeMapper, Nullable<CoordinateSequenceFactory>, Nullable<PrecisionModel>, Ordinates, Boolean)
    NpgsqlNodaTimeExtensions.UseNodaTime(INpgsqlTypeMapper)
    • Improve this Doc
    • View Source
    In This Article
    Back to top © Copyright 2022 The Npgsql Development Team