Search Results for

    Show / Hide Table of Contents

    Class NpgsqlConnection

    This class represents a connection to a PostgreSQL server.

    Inheritance
    Object
    MarshalByRefObject
    Component
    DbConnection
    NpgsqlConnection
    Implements
    IDbConnection
    IAsyncDisposable
    ICloneable
    IComponent
    IDisposable
    Inherited Members
    DbConnection.ChangeDatabaseAsync(String, CancellationToken)
    DbConnection.OnStateChange(StateChangeEventArgs)
    DbConnection.OpenAsync()
    DbConnection.IDbConnection.BeginTransaction()
    DbConnection.IDbConnection.BeginTransaction(IsolationLevel)
    DbConnection.IDbConnection.CreateCommand()
    DbConnection.StateChange
    Component.Dispose()
    Component.GetService(Type)
    Component.ToString()
    Component.CanRaiseEvents
    Component.Container
    Component.DesignMode
    Component.Events
    Component.Site
    Component.Disposed
    MarshalByRefObject.GetLifetimeService()
    MarshalByRefObject.InitializeLifetimeService()
    MarshalByRefObject.MemberwiseClone(Boolean)
    Object.Equals(Object)
    Object.Equals(Object, Object)
    Object.GetHashCode()
    Object.GetType()
    Object.MemberwiseClone()
    Object.ReferenceEquals(Object, Object)
    Namespace: Npgsql
    Assembly: Npgsql.dll
    Syntax
    public sealed class NpgsqlConnection : DbConnection, IDbConnection, IAsyncDisposable, ICloneable, IComponent, IDisposable

    Constructors

    NpgsqlConnection()

    Initializes a new instance of the NpgsqlConnection class.

    Declaration
    public NpgsqlConnection()

    NpgsqlConnection(String)

    Initializes a new instance of NpgsqlConnection with the given connection string.

    Declaration
    public NpgsqlConnection(string connectionString)
    Parameters
    Type Name Description
    String connectionString

    The connection used to open the PostgreSQL database.

    Fields

    DefaultPort

    The default TCP/IP port for PostgreSQL.

    Declaration
    public const int DefaultPort = 27500
    Field Value
    Type Description
    Int32

    Properties

    CommandTimeout

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

    Declaration
    public int CommandTimeout { get; }
    Property Value
    Type Description
    Int32

    The time (in seconds) to wait for a command to complete. The default value is 20 seconds.

    ConnectionString

    Gets or sets the string used to connect to a PostgreSQL database. See the manual for details.

    Declaration
    public override string ConnectionString { get; set; }
    Property Value
    Type Description
    String

    The connection string that includes the server name, the database name, and other parameters needed to establish the initial connection. The default value is an empty string.

    Overrides
    DbConnection.ConnectionString

    ConnectionTimeout

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

    Declaration
    public override int ConnectionTimeout { get; }
    Property Value
    Type Description
    Int32

    The time (in seconds) to wait for a connection to open. The default value is 15 seconds.

    Overrides
    DbConnection.ConnectionTimeout

    Database

    Gets the name of the current database or the database to be used after a connection is opened.

    Declaration
    public override string Database { get; }
    Property Value
    Type Description
    String

    The name of the current database or the name of the database to be used after a connection is opened. The default value is the empty string.

    Overrides
    DbConnection.Database

    DataSource

    Gets the string identifying the database server (host and port)

    Declaration
    public override string DataSource { get; }
    Property Value
    Type Description
    String

    The name of the database server (host and port). If the connection uses a Unix-domain socket, the path to that socket is returned. The default value is the empty string.

    Overrides
    DbConnection.DataSource

    DbProviderFactory

    DB provider factory.

    Declaration
    protected override DbProviderFactory DbProviderFactory { get; }
    Property Value
    Type Description
    DbProviderFactory
    Overrides
    DbConnection.DbProviderFactory

    FullState

    Gets the current state of the connection.

    Declaration
    [Browsable(false)]
    public ConnectionState FullState { get; }
    Property Value
    Type Description
    ConnectionState

    A bitwise combination of the ConnectionState values. The default is Closed.

    GlobalTypeMapper

    The global type mapper, which contains defaults used by all new connections. Modify mappings on this mapper to affect your entire application.

    Declaration
    public static INpgsqlTypeMapper GlobalTypeMapper { get; }
    Property Value
    Type Description
    INpgsqlTypeMapper

    HasIntegerDateTimes

    Reports whether the backend uses the newer integer timestamp representation. Note that the old floating point representation is not supported. Meant for use by type plugins (e.g. NodaTime)

    Declaration
    [Browsable(false)]
    public bool HasIntegerDateTimes { get; }
    Property Value
    Type Description
    Boolean

    Host

    Backend server host name.

    Declaration
    [Browsable(true)]
    public string Host { get; }
    Property Value
    Type Description
    String

    IntegratedSecurity

    Whether to use Windows integrated security to log in.

    Declaration
    public bool IntegratedSecurity { get; }
    Property Value
    Type Description
    Boolean

    PhysicalOpenAsyncCallback

    Gets or sets the delegate used to setup a connection whenever a physical connection is opened asynchronously.

    Declaration
    public PhysicalOpenAsyncCallback PhysicalOpenAsyncCallback { get; set; }
    Property Value
    Type Description
    PhysicalOpenAsyncCallback

    PhysicalOpenCallback

    Gets or sets the delegate used to setup a connection whenever a physical connection is opened synchronously.

    Declaration
    public PhysicalOpenCallback PhysicalOpenCallback { get; set; }
    Property Value
    Type Description
    PhysicalOpenCallback

    Port

    Backend server port.

    Declaration
    [Browsable(true)]
    public int Port { get; }
    Property Value
    Type Description
    Int32

    PostgresParameters

    Holds all PostgreSQL parameters received for this connection. Is updated if the values change (e.g. as a result of a SET command).

    Declaration
    [Browsable(false)]
    public IReadOnlyDictionary<string, string> PostgresParameters { get; }
    Property Value
    Type Description
    IReadOnlyDictionary<String, String>

    PostgreSqlVersion

    The version of the PostgreSQL server we're connected to.

    This can only be called when the connection is open.

    In case of a development or pre-release version this field will contain the version of the next version to be released from this branch.

    Declaration
    [Browsable(false)]
    public Version PostgreSqlVersion { get; }
    Property Value
    Type Description
    Version

    ProcessID

    Process id of backend server. This can only be called when there is an active connection.

    Declaration
    [Browsable(false)]
    public int ProcessID { get; }
    Property Value
    Type Description
    Int32

    ProvideClientCertificatesCallback

    Selects the local Secure Sockets Layer (SSL) certificate used for authentication.

    Declaration
    public ProvideClientCertificatesCallback ProvideClientCertificatesCallback { get; set; }
    Property Value
    Type Description
    ProvideClientCertificatesCallback
    Remarks

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

    ProvidePasswordCallback

    Gets or sets the delegate used to generate a password for new database connections.

    Declaration
    public ProvidePasswordCallback ProvidePasswordCallback { get; set; }
    Property Value
    Type Description
    ProvidePasswordCallback
    Remarks

    This delegate is executed when a new database connection is opened that requires a password.

    The Password and Passfile connection string properties have precedence over this delegate: it will not be executed if a password is specified, or if the specified or default Passfile contains a valid entry.

    Due to connection pooling this delegate is only executed when a new physical connection is opened, not when reusing a connection that was previously opened from the pool.

    ServerVersion

    The PostgreSQL server version as returned by the server_version option. This can only be called when the connection is open.

    Declaration
    public override string ServerVersion { get; }
    Property Value
    Type Description
    String
    Overrides
    DbConnection.ServerVersion

    Settings

    The parsed connection string. Set only after the connection is opened.

    Declaration
    public NpgsqlConnectionStringBuilder Settings { get; }
    Property Value
    Type Description
    NpgsqlConnectionStringBuilder

    State

    Gets whether the current state of the connection is Open or Closed

    Declaration
    [Browsable(false)]
    public override ConnectionState State { get; }
    Property Value
    Type Description
    ConnectionState

    ConnectionState.Open, ConnectionState.Closed or ConnectionState.Connecting

    Overrides
    DbConnection.State

    Timezone

    The connection's timezone as reported by PostgreSQL, in the IANA/Olson database format.

    Declaration
    [Browsable(false)]
    public string Timezone { get; }
    Property Value
    Type Description
    String

    TypeMapper

    The connection-specific type mapper - all modifications affect this connection only, and are lost when it is closed.

    Declaration
    public INpgsqlTypeMapper TypeMapper { get; }
    Property Value
    Type Description
    INpgsqlTypeMapper

    UserCertificateValidationCallback

    Verifies the remote Secure Sockets Layer (SSL) certificate used for authentication.

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

    Declaration
    public RemoteCertificateValidationCallback UserCertificateValidationCallback { get; set; }
    Property Value
    Type Description
    RemoteCertificateValidationCallback
    Remarks

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

    UserName

    User name.

    Declaration
    public string UserName { get; }
    Property Value
    Type Description
    String

    Methods

    BeginBinaryExport(String)

    Begins a binary COPY TO STDOUT operation, a high-performance data export mechanism from a PostgreSQL table.

    Declaration
    public NpgsqlBinaryExporter BeginBinaryExport(string copyToCommand)
    Parameters
    Type Name Description
    String copyToCommand

    A COPY TO STDOUT SQL command

    Returns
    Type Description
    NpgsqlBinaryExporter

    A NpgsqlBinaryExporter which can be used to read rows and columns

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginBinaryExportAsync(String, CancellationToken)

    Begins a binary COPY TO STDOUT operation, a high-performance data export mechanism from a PostgreSQL table.

    Declaration
    public Task<NpgsqlBinaryExporter> BeginBinaryExportAsync(string copyToCommand, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    String copyToCommand

    A COPY TO STDOUT SQL command

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<NpgsqlBinaryExporter>

    A NpgsqlBinaryExporter which can be used to read rows and columns

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginBinaryImport(String)

    Begins a binary COPY FROM STDIN operation, a high-performance data import mechanism to a PostgreSQL table.

    Declaration
    public NpgsqlBinaryImporter BeginBinaryImport(string copyFromCommand)
    Parameters
    Type Name Description
    String copyFromCommand

    A COPY FROM STDIN SQL command

    Returns
    Type Description
    NpgsqlBinaryImporter

    A NpgsqlBinaryImporter which can be used to write rows and columns

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginBinaryImportAsync(String, CancellationToken)

    Begins a binary COPY FROM STDIN operation, a high-performance data import mechanism to a PostgreSQL table.

    Declaration
    public Task<NpgsqlBinaryImporter> BeginBinaryImportAsync(string copyFromCommand, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    String copyFromCommand

    A COPY FROM STDIN SQL command

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<NpgsqlBinaryImporter>

    A NpgsqlBinaryImporter which can be used to write rows and columns

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginDbTransaction(IsolationLevel)

    Begins a database transaction with the specified isolation level.

    Declaration
    protected override DbTransaction BeginDbTransaction(IsolationLevel isolationLevel)
    Parameters
    Type Name Description
    IsolationLevel isolationLevel

    The isolation level under which the transaction should run.

    Returns
    Type Description
    DbTransaction

    A DbTransaction object representing the new transaction.

    Overrides
    DbConnection.BeginDbTransaction(IsolationLevel)
    Remarks

    Nested transactions are not supported.

    BeginDbTransactionAsync(IsolationLevel, CancellationToken)

    Asynchronously begins a database transaction.

    Declaration
    protected override async ValueTask<DbTransaction> BeginDbTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken)
    Parameters
    Type Name Description
    IsolationLevel isolationLevel

    The isolation level under which the transaction should run.

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    ValueTask<DbTransaction>

    A task whose Result property is an object representing the new transaction.

    Overrides
    DbConnection.BeginDbTransactionAsync(IsolationLevel, CancellationToken)
    Remarks

    Nested transactions are not supported.

    BeginRawBinaryCopy(String)

    Begins a raw binary COPY operation (TO STDOUT or FROM STDIN), a high-performance data export/import mechanism to a PostgreSQL table. Note that unlike the other COPY API methods, BeginRawBinaryCopy(String) doesn't implement any encoding/decoding and is unsuitable for structured import/export operation. It is useful mainly for exporting a table as an opaque blob, for the purpose of importing it back later.

    Declaration
    public NpgsqlRawCopyStream BeginRawBinaryCopy(string copyCommand)
    Parameters
    Type Name Description
    String copyCommand

    A COPY TO STDOUT or COPY FROM STDIN SQL command

    Returns
    Type Description
    NpgsqlRawCopyStream

    A NpgsqlRawCopyStream that can be used to read or write raw binary data.

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginRawBinaryCopyAsync(String, CancellationToken)

    Begins a raw binary COPY operation (TO STDOUT or FROM STDIN), a high-performance data export/import mechanism to a PostgreSQL table. Note that unlike the other COPY API methods, BeginRawBinaryCopyAsync(String, CancellationToken) doesn't implement any encoding/decoding and is unsuitable for structured import/export operation. It is useful mainly for exporting a table as an opaque blob, for the purpose of importing it back later.

    Declaration
    public Task<NpgsqlRawCopyStream> BeginRawBinaryCopyAsync(string copyCommand, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    String copyCommand

    A COPY TO STDOUT or COPY FROM STDIN SQL command

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<NpgsqlRawCopyStream>

    A NpgsqlRawCopyStream that can be used to read or write raw binary data.

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginTextExport(String)

    Begins a textual COPY TO STDOUT operation, a data export mechanism from a PostgreSQL table. It is the user's responsibility to parse the textual input according to the format specified in copyToCommand.

    Declaration
    public TextReader BeginTextExport(string copyToCommand)
    Parameters
    Type Name Description
    String copyToCommand

    A COPY TO STDOUT SQL command

    Returns
    Type Description
    TextReader

    A TextReader that can be used to read textual data.

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginTextExportAsync(String, CancellationToken)

    Begins a textual COPY TO STDOUT operation, a data export mechanism from a PostgreSQL table. It is the user's responsibility to parse the textual input according to the format specified in copyToCommand.

    Declaration
    public Task<TextReader> BeginTextExportAsync(string copyToCommand, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    String copyToCommand

    A COPY TO STDOUT SQL command

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<TextReader>

    A TextReader that can be used to read textual data.

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginTextImport(String)

    Begins a textual COPY FROM STDIN operation, a data import mechanism to a PostgreSQL table. It is the user's responsibility to send the textual input according to the format specified in copyFromCommand.

    Declaration
    public TextWriter BeginTextImport(string copyFromCommand)
    Parameters
    Type Name Description
    String copyFromCommand

    A COPY FROM STDIN SQL command

    Returns
    Type Description
    TextWriter

    A TextWriter that can be used to send textual data.

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginTextImportAsync(String, CancellationToken)

    Begins a textual COPY FROM STDIN operation, a data import mechanism to a PostgreSQL table. It is the user's responsibility to send the textual input according to the format specified in copyFromCommand.

    Declaration
    public Task<TextWriter> BeginTextImportAsync(string copyFromCommand, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    String copyFromCommand

    A COPY FROM STDIN SQL command

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<TextWriter>

    A TextWriter that can be used to send textual data.

    Remarks

    See https://www.postgresql.org/docs/current/static/sql-copy.html.

    BeginTransaction()

    Begins a database transaction.

    Declaration
    public NpgsqlTransaction BeginTransaction()
    Returns
    Type Description
    NpgsqlTransaction

    A NpgsqlTransaction object representing the new transaction.

    Remarks

    Nested transactions are not supported. Transactions created by this method will have the ReadCommitted isolation level.

    BeginTransaction(IsolationLevel)

    Begins a database transaction with the specified isolation level.

    Declaration
    public NpgsqlTransaction BeginTransaction(IsolationLevel level)
    Parameters
    Type Name Description
    IsolationLevel level

    The isolation level under which the transaction should run.

    Returns
    Type Description
    NpgsqlTransaction

    A NpgsqlTransaction object representing the new transaction.

    Remarks

    Nested transactions are not supported.

    BeginTransactionAsync(IsolationLevel, CancellationToken)

    Asynchronously begins a database transaction.

    Declaration
    public ValueTask<NpgsqlTransaction> BeginTransactionAsync(IsolationLevel level, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    IsolationLevel level

    The isolation level under which the transaction should run.

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    ValueTask<NpgsqlTransaction>

    A task whose Result property is an object representing the new transaction.

    Remarks

    Nested transactions are not supported.

    BeginTransactionAsync(CancellationToken)

    Asynchronously begins a database transaction.

    Declaration
    public ValueTask<NpgsqlTransaction> BeginTransactionAsync(CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    ValueTask<NpgsqlTransaction>

    A task whose Result property is an object representing the new transaction.

    Remarks

    Nested transactions are not supported. Transactions created by this method will have the ReadCommitted isolation level.

    ChangeDatabase(String)

    This method changes the current database by disconnecting from the actual database and connecting to the specified.

    Declaration
    public override void ChangeDatabase(string dbName)
    Parameters
    Type Name Description
    String dbName

    The name of the database to use in place of the current database.

    Overrides
    DbConnection.ChangeDatabase(String)

    ClearAllPools()

    Clear all connection pools. All idle physical connections in all pools are immediately closed, and any busy connections which were opened before ClearAllPools() was called will be closed when returned to their pool.

    Declaration
    public static void ClearAllPools()

    ClearPool(NpgsqlConnection)

    Clears the connection pool. All idle physical connections in the pool of the given connection are immediately closed, and any busy connections which were opened before ClearPool(NpgsqlConnection) was called will be closed when returned to the pool.

    Declaration
    public static void ClearPool(NpgsqlConnection connection)
    Parameters
    Type Name Description
    NpgsqlConnection connection

    CloneWith(String)

    Clones this connection, replacing its connection string with the given one. This allows creating a new connection with the same security information (password, SSL callbacks) while changing other connection parameters (e.g. database or pooling)

    Declaration
    public NpgsqlConnection CloneWith(string connectionString)
    Parameters
    Type Name Description
    String connectionString
    Returns
    Type Description
    NpgsqlConnection

    Close()

    Releases the connection. If the connection is pooled, it will be returned to the pool and made available for re-use. If it is non-pooled, the physical connection will be closed.

    Declaration
    public override void Close()
    Overrides
    DbConnection.Close()

    CloseAsync()

    Releases the connection. If the connection is pooled, it will be returned to the pool and made available for re-use. If it is non-pooled, the physical connection will be closed.

    Declaration
    public override Task CloseAsync()
    Returns
    Type Description
    Task
    Overrides
    DbConnection.CloseAsync()

    CreateBatch()

    Creates and returns a NpgsqlBatch object associated with the NpgsqlConnection.

    Declaration
    public NpgsqlBatch CreateBatch()
    Returns
    Type Description
    NpgsqlBatch

    A NpgsqlBatch object.

    CreateCommand()

    Creates and returns a NpgsqlCommand object associated with the NpgsqlConnection.

    Declaration
    public NpgsqlCommand CreateCommand()
    Returns
    Type Description
    NpgsqlCommand

    A NpgsqlCommand object.

    CreateDbCommand()

    Creates and returns a DbCommand object associated with the DbConnection.

    Declaration
    protected override DbCommand CreateDbCommand()
    Returns
    Type Description
    DbCommand

    A DbCommand object.

    Overrides
    DbConnection.CreateDbCommand()

    Dispose(Boolean)

    Releases all resources used by the NpgsqlConnection.

    Declaration
    protected override void Dispose(bool disposing)
    Parameters
    Type Name Description
    Boolean disposing

    true when called from Dispose(Boolean); false when being called from the finalizer.

    Overrides
    Component.Dispose(Boolean)

    DisposeAsync()

    Releases all resources used by the NpgsqlConnection.

    Declaration
    public override ValueTask DisposeAsync()
    Returns
    Type Description
    ValueTask
    Overrides
    DbConnection.DisposeAsync()

    EnlistTransaction(Transaction)

    Enlist transaction.

    Declaration
    public override void EnlistTransaction(Transaction transaction)
    Parameters
    Type Name Description
    Transaction transaction
    Overrides
    DbConnection.EnlistTransaction(Transaction)

    GetSchema()

    Returns the supported collections

    Declaration
    public override DataTable GetSchema()
    Returns
    Type Description
    DataTable
    Overrides
    DbConnection.GetSchema()

    GetSchema(String)

    Returns the schema collection specified by the collection name.

    Declaration
    public override DataTable GetSchema(string collectionName)
    Parameters
    Type Name Description
    String collectionName

    The collection name.

    Returns
    Type Description
    DataTable

    The collection specified.

    Overrides
    DbConnection.GetSchema(String)

    GetSchema(String, String[])

    Returns the schema collection specified by the collection name filtered by the restrictions.

    Declaration
    public override DataTable GetSchema(string collectionName, string[] restrictions)
    Parameters
    Type Name Description
    String collectionName

    The collection name.

    String[] restrictions

    The restriction values to filter the results. A description of the restrictions is contained in the Restrictions collection.

    Returns
    Type Description
    DataTable

    The collection specified.

    Overrides
    DbConnection.GetSchema(String, String[])

    GetSchemaAsync(String, String[], CancellationToken)

    Asynchronously returns the schema collection specified by the collection name filtered by the restrictions.

    Declaration
    public Task<DataTable> GetSchemaAsync(string collectionName, string[] restrictions, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    String collectionName

    The collection name.

    String[] restrictions

    The restriction values to filter the results. A description of the restrictions is contained in the Restrictions collection.

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<DataTable>

    The collection specified.

    GetSchemaAsync(String, CancellationToken)

    Asynchronously returns the schema collection specified by the collection name.

    Declaration
    public Task<DataTable> GetSchemaAsync(string collectionName, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    String collectionName

    The collection name.

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<DataTable>

    The collection specified.

    GetSchemaAsync(CancellationToken)

    Asynchronously returns the supported collections.

    Declaration
    public Task<DataTable> GetSchemaAsync(CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<DataTable>

    The collection specified.

    MapComposite<T>(String, INpgsqlNameTranslator)

    Maps a CLR type to a PostgreSQL composite type for use with this connection.

    Declaration
    [Obsolete("Use NpgsqlConnection.TypeMapper.MapComposite() instead")]
    public void MapComposite<T>(string pgName = null, INpgsqlNameTranslator nameTranslator = null)
        where T : new()
    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 nameTranslatorwill 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

    Type Parameters
    Name Description
    T

    The .NET type to be mapped

    Remarks

    CLR fields and properties by string 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 members to manually specify a PostgreSQL enum label. If there is a discrepancy between the .NET and database labels while a composite is read or written, an exception will be raised.

    Can only be invoked on an open connection; if the connection is closed the mapping is lost.

    To avoid mapping the type for each connection, use the MapCompositeGlobally<T>(String, INpgsqlNameTranslator) method.

    MapCompositeGlobally<T>(String, INpgsqlNameTranslator)

    Maps a CLR type to a PostgreSQL composite type for use with all connections created from now on. Existing connections aren't affected.

    Declaration
    [Obsolete("Use NpgsqlConnection.GlobalTypeMapper.MapComposite() instead")]
    public static void MapCompositeGlobally<T>(string pgName = null, INpgsqlNameTranslator nameTranslator = null)
        where T : new()
    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 nameTranslatorwill 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

    Type Parameters
    Name Description
    T

    The .NET type to be mapped

    Remarks

    CLR fields and properties by string 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 members to manually specify a PostgreSQL enum label. If there is a discrepancy between the .NET and database labels while a composite is read or written, an exception will be raised.

    To map the type for a specific connection, use the MapEnum<TEnum>(String, INpgsqlNameTranslator) method.

    MapEnum<TEnum>(String, INpgsqlNameTranslator)

    Maps a CLR enum to a PostgreSQL enum type for use with this connection.

    Declaration
    [Obsolete("Use NpgsqlConnection.TypeMapper.MapEnum() instead")]
    public void 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 nameTranslatorwill 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

    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.

    Can only be invoked on an open connection; if the connection is closed the mapping is lost.

    To avoid mapping the type for each connection, use the MapEnumGlobally<TEnum>(String, INpgsqlNameTranslator) method.

    MapEnumGlobally<TEnum>(String, INpgsqlNameTranslator)

    Maps a CLR enum to a PostgreSQL enum type for use with all connections created from now on. Existing connections aren't affected.

    Declaration
    [Obsolete("Use NpgsqlConnection.GlobalTypeMapper.MapEnum() instead")]
    public static void MapEnumGlobally<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 nameTranslatorwill 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

    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.

    To map the type for a specific connection, use the MapEnum<TEnum>(String, INpgsqlNameTranslator) method.

    Open()

    Opens a database connection with the property settings specified by the ConnectionString.

    Declaration
    public override void Open()
    Overrides
    DbConnection.Open()

    OpenAsync(CancellationToken)

    This is the asynchronous version of Open().

    Declaration
    public override Task OpenAsync(CancellationToken cancellationToken)
    Parameters
    Type Name Description
    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task

    A task representing the asynchronous operation.

    Overrides
    DbConnection.OpenAsync(CancellationToken)
    Remarks

    Do not invoke other methods and properties of the NpgsqlConnection object until the returned Task is complete.

    ReloadTypes()

    Flushes the type cache for this connection's connection string and reloads the types for this connection only. Type changes will appear for other connections only after they are re-opened from the pool.

    Declaration
    public void ReloadTypes()

    UnmapCompositeGlobally<T>(String, INpgsqlNameTranslator)

    Removes a previous global enum mapping.

    Declaration
    [Obsolete("Use NpgsqlConnection.GlobalTypeMapper.UnmapComposite() instead")]
    public static void UnmapCompositeGlobally<T>(string pgName, INpgsqlNameTranslator nameTranslator = null)
        where T : new()
    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 nameTranslatorwill 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

    Type Parameters
    Name Description
    T

    UnmapEnumGlobally<TEnum>(String, INpgsqlNameTranslator)

    Removes a previous global enum mapping.

    Declaration
    [Obsolete("Use NpgsqlConnection.GlobalTypeMapper.UnmapEnum() instead")]
    public static void UnmapEnumGlobally<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 nameTranslatorwill 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

    Type Parameters
    Name Description
    TEnum

    UnprepareAll()

    Unprepares all prepared statements on this connection.

    Declaration
    public void UnprepareAll()

    Wait()

    Waits until an asynchronous PostgreSQL messages (e.g. a notification) arrives, and exits immediately. The asynchronous message is delivered via the normal events (Notification, Notice).

    Declaration
    public void Wait()

    Wait(Int32)

    Waits until an asynchronous PostgreSQL messages (e.g. a notification) arrives, and exits immediately. The asynchronous message is delivered via the normal events (Notification, Notice).

    Declaration
    public bool Wait(int timeout)
    Parameters
    Type Name Description
    Int32 timeout

    The time-out value, in milliseconds, passed to ReceiveTimeout. The default value is 0, which indicates an infinite time-out period. Specifying -1 also indicates an infinite time-out period.

    Returns
    Type Description
    Boolean

    true if an asynchronous message was received, false if timed out.

    Wait(TimeSpan)

    Waits until an asynchronous PostgreSQL messages (e.g. a notification) arrives, and exits immediately. The asynchronous message is delivered via the normal events (Notification, Notice).

    Declaration
    public bool Wait(TimeSpan timeout)
    Parameters
    Type Name Description
    TimeSpan timeout

    The time-out value is passed to ReceiveTimeout.

    Returns
    Type Description
    Boolean

    true if an asynchronous message was received, false if timed out.

    WaitAsync(Int32, CancellationToken)

    Waits asynchronously until an asynchronous PostgreSQL messages (e.g. a notification) arrives, and exits immediately. The asynchronous message is delivered via the normal events (Notification, Notice).

    Declaration
    public Task<bool> WaitAsync(int timeout, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    Int32 timeout

    The time-out value, in milliseconds. The default value is 0, which indicates an infinite time-out period. Specifying -1 also indicates an infinite time-out period.

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<Boolean>

    true if an asynchronous message was received, false if timed out.

    WaitAsync(CancellationToken)

    Waits asynchronously until an asynchronous PostgreSQL messages (e.g. a notification) arrives, and exits immediately. The asynchronous message is delivered via the normal events (Notification, Notice).

    Declaration
    public Task WaitAsync(CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task

    WaitAsync(TimeSpan, CancellationToken)

    Waits asynchronously until an asynchronous PostgreSQL messages (e.g. a notification) arrives, and exits immediately. The asynchronous message is delivered via the normal events (Notification, Notice).

    Declaration
    public Task<bool> WaitAsync(TimeSpan timeout, CancellationToken cancellationToken = default(CancellationToken))
    Parameters
    Type Name Description
    TimeSpan timeout

    The time-out value as TimeSpan

    CancellationToken cancellationToken

    An optional token to cancel the asynchronous operation. The default value is None.

    Returns
    Type Description
    Task<Boolean>

    true if an asynchronous message was received, false if timed out.

    Events

    Notice

    Fires when PostgreSQL notices are received from PostgreSQL.

    Declaration
    public event NoticeEventHandler Notice
    Event Type
    Type Description
    NoticeEventHandler
    Remarks

    PostgreSQL notices are non-critical messages generated by PostgreSQL, either as a result of a user query (e.g. as a warning or informational notice), or due to outside activity (e.g. if the database administrator initiates a "fast" database shutdown).

    Note that notices are very different from notifications (see the Notification event).

    Notification

    Fires when PostgreSQL notifications are received from PostgreSQL.

    Declaration
    public event NotificationEventHandler Notification
    Event Type
    Type Description
    NotificationEventHandler
    Remarks

    PostgreSQL notifications are sent when your connection has registered for notifications on a specific channel via the LISTEN command. NOTIFY can be used to generate such notifications, allowing for an inter-connection communication channel.

    Note that notifications are very different from notices (see the Notice event).

    Explicit Interface Implementations

    IComponent.Disposed

    Declaration
    event EventHandler IComponent.Disposed
    Returns
    Type Description
    EventHandler

    ICloneable.Clone()

    Creates a closed connection with the connection string and authentication details of this message.

    Declaration
    object ICloneable.Clone()
    Returns
    Type Description
    Object

    Implements

    System.Data.IDbConnection
    System.IAsyncDisposable
    System.ICloneable
    System.ComponentModel.IComponent
    System.IDisposable
    In This Article
    Back to top © Copyright 2022 The Npgsql Development Team