using System;

using System.Collections.Generic;

using System.ComponentModel;

using System.Data;

using System.Data.Common;

using System.Diagnostics;

using System.Diagnostics.CodeAnalysis;

using System.IO;

using System.Net.Security;

using System.Net.Sockets;

using System.Runtime.CompilerServices;

using System.Security.Cryptography.X509Certificates;

using System.Threading;

using System.Threading.Tasks;

using System.Transactions;

using Microsoft.Extensions.Logging;

using Npgsql.Internal;

using Npgsql.TypeMapping;

using Npgsql.Util;

using IsolationLevel = System.Data.IsolationLevel;

namespace Npgsql;

/// <summary>

/// This class represents a connection to a PostgreSQL server.

/// </summary>

// ReSharper disable once RedundantNameQualifier

[System.ComponentModel.DesignerCategory("")]

public sealed class NpgsqlConnection : DbConnection, ICloneable, IComponent

{

#region Fields

// Set this when disposed is called.

bool _disposed;

/// <summary>

/// The connection string, without the password after open (unless Persist Security Info=true)

/// </summary>

string _userFacingConnectionString = string.Empty;

/// <summary>

/// The original connection string provided by the user, including the password.

/// </summary>

string _connectionString = string.Empty;

ConnectionState _fullState;

/// <summary>

/// The physical connection to the database. This is <see langword="null"/> when the connection is closed,

/// and also when it is open in multiplexing mode and unbound (e.g. not in a transaction).

/// </summary>

internal NpgsqlConnector? Connector { get; set; }

/// <summary>

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

/// </summary>

internal NpgsqlConnectionStringBuilder Settings { get; private set; } = DefaultSettings;

static readonly NpgsqlConnectionStringBuilder DefaultSettings = new();

NpgsqlDataSource? _dataSource;

internal NpgsqlDataSource NpgsqlDataSource

{

get

{

Debug.Assert(_dataSource is not null);

return _dataSource;

}

}

/// <summary>

/// Flag used to make sure we never double-close a connection, returning it twice to the pool.

/// </summary>

int _closing;

internal Transaction? EnlistedTransaction { get; set; }

/// <summary>

/// The global type mapper, which contains defaults used by all new connections.

/// Modify mappings on this mapper to affect your entire application.

/// </summary>

[Obsolete("Global-level type mapping has been replaced with data source mapping, see the 7.0 release notes.")]

public static INpgsqlTypeMapper GlobalTypeMapper => TypeMapping.GlobalTypeMapper.Instance;

/// <summary>

/// Connection-level type mapping is no longer supported. See the 7.0 release notes for configuring type mapping on NpgsqlDataSource.

/// </summary>

[Obsolete("Connection-level type mapping is no longer supported. See the 7.0 release notes for configuring type mapping on NpgsqlDataSource.", true)]

public INpgsqlTypeMapper TypeMapper

=> throw new NotSupportedException();

static Func<string, NpgsqlConnection>? _cloningInstantiator;

/// <summary>

/// The default TCP/IP port for PostgreSQL.

/// </summary>

public const int DefaultPort = 5432;

/// <summary>

/// Maximum value for connection timeout.

/// </summary>

internal const int TimeoutLimit = 1024;

/// <summary>

/// Tracks when this connection was bound to a physical connector (e.g. at open-time, when a transaction

/// was started...).

/// </summary>

internal ConnectorBindingScope ConnectorBindingScope { get; set; }

ILogger _connectionLogger = default!; // Initialized in Open, shouldn't be used otherwise

static readonly StateChangeEventArgs ClosedToOpenEventArgs = new(ConnectionState.Closed, ConnectionState.Open);

static readonly StateChangeEventArgs OpenToClosedEventArgs = new(ConnectionState.Open, ConnectionState.Closed);

#endregion Fields

#region Constructors / Init / Open

/// <summary>

/// Initializes a new instance of the <see cref="NpgsqlConnection"/> class.

/// </summary>

public NpgsqlConnection()

=> GC.SuppressFinalize(this);

/// <summary>

/// Initializes a new instance of <see cref="NpgsqlConnection"/> with the given connection string.

/// </summary>

/// <param name="connectionString">The connection used to open the PostgreSQL database.</param>

public NpgsqlConnection(string? connectionString) : this()

=> ConnectionString = connectionString;

internal NpgsqlConnection(NpgsqlDataSource dataSource, NpgsqlConnector connector) : this()

{

_dataSource = dataSource;

Settings = dataSource.Settings;

_userFacingConnectionString = dataSource.ConnectionString;

Connector = connector;

connector.Connection = this;

ConnectorBindingScope = ConnectorBindingScope.Connection;

FullState = ConnectionState.Open;

}

internal static NpgsqlConnection FromDataSource(NpgsqlDataSource dataSource)

=> new()

{

_dataSource = dataSource,

Settings = dataSource.Settings,

_userFacingConnectionString = dataSource.ConnectionString,

};

/// <summary>

/// Opens a database connection with the property settings specified by the <see cref="ConnectionString"/>.

/// </summary>

public override void Open() => Open(false, CancellationToken.None).GetAwaiter().GetResult();

/// <summary>

/// This is the asynchronous version of <see cref="Open()"/>.

/// </summary>

/// <remarks>

/// Do not invoke other methods and properties of the <see cref="NpgsqlConnection"/> object until the returned Task is complete.

/// </remarks>

/// <param name="cancellationToken">

/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.

/// </param>

/// <returns>A task representing the asynchronous operation.</returns>

public override Task OpenAsync(CancellationToken cancellationToken) => Open(async: true, cancellationToken);

void SetupDataSource()

{

// Fast path: a pool already corresponds to this exact version of the connection string.

if (PoolManager.Pools.TryGetValue(_connectionString, out _dataSource))

{

Settings = _dataSource.Settings; // Great, we already have a pool

return;

}

// Connection string hasn't been seen before. Check for empty and parse (slow one-time path).

if (_connectionString == string.Empty)

{

Settings = DefaultSettings;

_dataSource = null;

return;

}

var settings = new NpgsqlConnectionStringBuilder(_connectionString);

settings.PostProcessAndValidate();

Settings = settings;

// The connection string may be equivalent to one that has already been seen though (e.g. different

// ordering). Have NpgsqlConnectionStringBuilder produce a canonical string representation

// and recheck.

// Note that we remove TargetSessionAttributes to make all connection strings that are otherwise identical point to the same pool.

var canonical = settings.ConnectionStringForMultipleHosts;

if (PoolManager.Pools.TryGetValue(canonical, out _dataSource))

{

// If this is a multi-host data source and the user specified a TargetSessionAttributes, create a wrapper in front of the

// MultiHostDataSource with that TargetSessionAttributes.

if (_dataSource is NpgsqlMultiHostDataSource multiHostDataSource && settings.TargetSessionAttributesParsed.HasValue)

_dataSource = multiHostDataSource.WithTargetSession(settings.TargetSessionAttributesParsed.Value);

// The pool was found, but only under the canonical key - we're using a different version

// for the first time. Map it via our own key for next time.

_dataSource = PoolManager.Pools.GetOrAdd(_connectionString, _dataSource);

return;

}

// Really unseen, need to create a new pool

// The canonical pool is the 'base' pool so we need to set that up first. If someone beats us to it use what they put.

// The connection string pool can either be added here or above, if it's added above we should just use that.

var dataSourceBuilder = new NpgsqlDataSourceBuilder(canonical);

dataSourceBuilder.UseLoggerFactory(NpgsqlLoggingConfiguration.GlobalLoggerFactory);

dataSourceBuilder.EnableParameterLogging(NpgsqlLoggingConfiguration.GlobalIsParameterLoggingEnabled);

var newDataSource = dataSourceBuilder.Build();

// See Clone() on the following line:

_cloningInstantiator = s => new NpgsqlConnection(s);

_dataSource = PoolManager.Pools.GetOrAdd(canonical, newDataSource);

if (_dataSource == newDataSource)

{

Debug.Assert(_dataSource is not MultiHostDataSourceWrapper);

// If the pool we created was the one that ended up being stored we need to increment the appropriate counter.

// Avoids a race condition where multiple threads will create a pool but only one will be stored.

if (_dataSource is NpgsqlMultiHostDataSource multiHostConnectorPool)

foreach (var hostPool in multiHostConnectorPool.Pools)

NpgsqlEventSource.Log.DataSourceCreated(hostPool);

else

{

NpgsqlEventSource.Log.DataSourceCreated(newDataSource);

}

}

else

newDataSource.Dispose();

// If this is a multi-host data source and the user specified a TargetSessionAttributes, create a wrapper in front of the

// MultiHostDataSource with that TargetSessionAttributes.

if (_dataSource is NpgsqlMultiHostDataSource multiHostDataSource2 && settings.TargetSessionAttributesParsed.HasValue)

_dataSource = multiHostDataSource2.WithTargetSession(settings.TargetSessionAttributesParsed.Value);

_dataSource = PoolManager.Pools.GetOrAdd(_connectionString, _dataSource);

}

internal Task Open(bool async, CancellationToken cancellationToken)

{

CheckClosed();

Debug.Assert(Connector == null);

if (_dataSource is null)

{

Debug.Assert(string.IsNullOrEmpty(_connectionString));

ThrowHelper.ThrowInvalidOperationException("The ConnectionString property has not been initialized.");

}

_userFacingConnectionString = _dataSource.ConnectionString;

_connectionLogger = _dataSource.LoggingConfiguration.ConnectionLogger;

if (_connectionLogger.IsEnabled(LogLevel.Trace))

LogMessages.OpeningConnection(_connectionLogger, Settings.Host!, Settings.Port, Settings.Database!, _userFacingConnectionString);

if (Settings.Multiplexing)

{

if (Settings.Enlist && Transaction.Current != null)

{

// TODO: Keep in mind that the TransactionScope can be disposed

ThrowHelper.ThrowNotSupportedException();

}

// We're opening in multiplexing mode, without a transaction. We don't actually do anything.

// If we've never connected with this connection string, open a physical connector in order to generate

// any exception (bad user/password, IP address...). This reproduces the standard error behavior.

if (!_dataSource.IsBootstrapped)

{

FullState = ConnectionState.Connecting;

return PerformMultiplexingStartupCheck(async, cancellationToken);

}

if (_connectionLogger.IsEnabled(LogLevel.Debug))

LogMessages.OpenedMultiplexingConnection(_connectionLogger, Settings.Host!, Settings.Port, Settings.Database!, _userFacingConnectionString);

FullState = ConnectionState.Open;

return Task.CompletedTask;

}

return OpenAsync(async, cancellationToken);

async Task OpenAsync(bool async, CancellationToken cancellationToken)

{

Debug.Assert(!Settings.Multiplexing);

FullState = ConnectionState.Connecting;

NpgsqlConnector? connector = null;

try

{

var connectionTimeout = TimeSpan.FromSeconds(ConnectionTimeout);

var timeout = new NpgsqlTimeout(connectionTimeout);

var enlistToTransaction = Settings.Enlist ? Transaction.Current : null;

// First, check to see if we there's an ambient transaction, and we have a connection enlisted

// to this transaction which has been closed. If so, return that as an optimization rather than

// opening a new one and triggering escalation to a distributed transaction.

// Otherwise just get a new connector and enlist below.

if (enlistToTransaction is not null && _dataSource.TryRentEnlistedPending(enlistToTransaction, this, out connector))

{

EnlistedTransaction = enlistToTransaction;

enlistToTransaction = null;

}

else

connector = await _dataSource.Get(this, timeout, async, cancellationToken).ConfigureAwait(false);

Debug.Assert(connector.Connection is null,

$"Connection for opened connector '{Connector?.Id.ToString() ?? "???"}' is bound to another connection");

ConnectorBindingScope = ConnectorBindingScope.Connection;

connector.Connection = this;

Connector = connector;

if (enlistToTransaction is not null)

EnlistTransaction(enlistToTransaction);

LogMessages.OpenedConnection(_connectionLogger, Host!, Port, Database, _userFacingConnectionString, connector.Id);

FullState = ConnectionState.Open;

}

catch

{

FullState = ConnectionState.Closed;

ConnectorBindingScope = ConnectorBindingScope.None;

Connector = null;

EnlistedTransaction = null;

if (connector is not null)

{

connector.Connection = null;

connector.Return();

}

throw;

}

}

async Task PerformMultiplexingStartupCheck(bool async, CancellationToken cancellationToken)

{

try

{

var timeout = new NpgsqlTimeout(TimeSpan.FromSeconds(ConnectionTimeout));

_ = await StartBindingScope(ConnectorBindingScope.Connection, timeout, async, cancellationToken).ConfigureAwait(false);

EndBindingScope(ConnectorBindingScope.Connection);

LogMessages.OpenedMultiplexingConnection(_connectionLogger, Settings.Host!, Settings.Port, Settings.Database!, _userFacingConnectionString);

FullState = ConnectionState.Open;

}

catch

{

FullState = ConnectionState.Closed;

throw;

}

}

}

#endregion Open / Init

#region Connection string management

/// <summary>

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

/// </summary>

/// <value>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.

/// </value>

[AllowNull]

public override string ConnectionString

{

get => _userFacingConnectionString;

set

{

CheckClosed();

_userFacingConnectionString = _connectionString = value ?? string.Empty;

SetupDataSource();

}

}

/// <summary>

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

/// </summary>

/// <remarks>

/// <p>

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

/// </p>

/// <p>

/// The <see cref="NpgsqlConnectionStringBuilder.Password"/> and <see cref="NpgsqlConnectionStringBuilder.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.

/// </p>

/// <p>

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

/// </p>

/// </remarks>

[Obsolete("Use NpgsqlDataSourceBuilder.UsePeriodicPasswordProvider or inject passwords directly into NpgsqlDataSource.Password")]

public ProvidePasswordCallback? ProvidePasswordCallback { get; set; }

#endregion Connection string management

#region Configuration settings

/// <summary>

/// Backend server host name.

/// </summary>

[Browsable(true)]

public string? Host => Connector?.Host;

/// <summary>

/// Backend server port.

/// </summary>

[Browsable(true)]

public int Port => Connector?.Port ?? 0;

/// <summary>

/// Gets the time (in seconds) to wait while trying to establish a connection

/// before terminating the attempt and generating an error.

/// </summary>

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

public override int ConnectionTimeout => Settings.Timeout;

/// <summary>

/// Gets the time (in seconds) to wait while trying to execute a command

/// before terminating the attempt and generating an error.

/// </summary>

/// <value>The time (in seconds) to wait for a command to complete. The default value is 30 seconds.</value>

public int CommandTimeout => Settings.CommandTimeout;

///<summary>

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

/// </summary>

/// <value>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.</value>

public override string Database => Settings.Database ?? Settings.Username ?? "";

/// <summary>

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

/// </summary>

/// <value>

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

/// </value>

public override string DataSource => Connector?.Settings.DataSourceCached ?? _dataSource?.Settings.DataSourceCached ?? string.Empty;

/// <summary>

/// User name.

/// </summary>

public string? UserName => Settings.Username;

#endregion Configuration settings

#region State management

/// <summary>

/// Gets the current state of the connection.

/// </summary>

/// <value>A bitwise combination of the <see cref="System.Data.ConnectionState"/> values. The default is <b>Closed</b>.</value>

[Browsable(false)]

public ConnectionState FullState

{

// Note: we allow accessing the state after dispose, #164

get

{

if (_fullState != ConnectionState.Open)

return _fullState;

if (Connector is null)

return ConnectionState.Open; // When unbound, we only know we're open

switch (Connector.State)

{

case ConnectorState.Ready:

return ConnectionState.Open;

case ConnectorState.Executing:

return ConnectionState.Open | ConnectionState.Executing;

case ConnectorState.Fetching:

case ConnectorState.Copy:

case ConnectorState.Replication:

case ConnectorState.Waiting:

return ConnectionState.Open | ConnectionState.Fetching;

case ConnectorState.Connecting:

return ConnectionState.Connecting;

case ConnectorState.Broken:

return ConnectionState.Broken;

case ConnectorState.Closed:

ThrowHelper.ThrowInvalidOperationException("Internal Npgsql bug: connection is in state Open but connector is in state Closed");

return ConnectionState.Broken;

default:

ThrowHelper.ThrowInvalidOperationException($"Internal Npgsql bug: unexpected value {{0}} of enum {nameof(ConnectorState)}. Please file a bug.", Connector.State);

return ConnectionState.Broken;

}

}

internal set

{

if (value is < 0 or > ConnectionState.Broken)

ThrowHelper.ThrowArgumentOutOfRangeException(nameof(value), "Unknown connection state", value);

var originalOpen = _fullState.HasFlag(ConnectionState.Open);

_fullState = value;

var currentOpen = _fullState.HasFlag(ConnectionState.Open);

if (currentOpen != originalOpen)

{

OnStateChange(currentOpen

? ClosedToOpenEventArgs

: OpenToClosedEventArgs);

}

}

}

/// <summary>

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

/// </summary>

/// <value>ConnectionState.Open, ConnectionState.Closed or ConnectionState.Connecting</value>

[Browsable(false)]

public override ConnectionState State

{

get

{

var fullState = FullState;

if (fullState.HasFlag(ConnectionState.Connecting))

return ConnectionState.Connecting;

if (fullState.HasFlag(ConnectionState.Open))

return ConnectionState.Open;

return ConnectionState.Closed;

}

}

#endregion State management

#region Command / Batch creation

/// <summary>

/// A cached command handed out by <see cref="CreateCommand" />, which is returned when disposed. Useful for reducing allocations.

/// </summary>

internal NpgsqlCommand? CachedCommand { get; set; }

/// <summary>

/// Creates and returns a <see cref="System.Data.Common.DbCommand"/>

/// object associated with the <see cref="System.Data.Common.DbConnection"/>.

/// </summary>

/// <returns>A <see cref="System.Data.Common.DbCommand"/> object.</returns>

protected override DbCommand CreateDbCommand() => CreateCommand();

/// <summary>

/// Creates and returns a <see cref="NpgsqlCommand"/> object associated with the <see cref="NpgsqlConnection"/>.

/// </summary>

/// <returns>A <see cref="NpgsqlCommand"/> object.</returns>

public new NpgsqlCommand CreateCommand()

{

CheckDisposed();

var cachedCommand = CachedCommand;

if (cachedCommand is not null)

{

CachedCommand = null;

cachedCommand.State = CommandState.Idle;

return cachedCommand;

}

return NpgsqlCommand.CreateCachedCommand(this);

}

/// <summary>

/// A cached batch handed out by <see cref="CreateBatch" />, which is returned when disposed. Useful for reducing allocations.

/// </summary>

internal NpgsqlBatch? CachedBatch { get; set; }

/// <inheritdoc/>

public override bool CanCreateBatch => true;

/// <inheritdoc/>

protected override DbBatch CreateDbBatch() => CreateBatch();

/// <inheritdoc cref="DbConnection.CreateBatch"/>

public new NpgsqlBatch CreateBatch()

{

CheckDisposed();

var cachedBatch = CachedBatch;

if (cachedBatch is not null)

{

CachedBatch = null;

return cachedBatch;

}

return NpgsqlBatch.CreateCachedBatch(this);

}

#endregion Command / Batch creation

#region Transactions

/// <summary>

/// Begins a database transaction with the specified isolation level.

/// </summary>

/// <param name="isolationLevel">The isolation level under which the transaction should run.</param>

/// <returns>A <see cref="System.Data.Common.DbTransaction"/> object representing the new transaction.</returns>

/// <remarks>Nested transactions are not supported.</remarks>

protected override DbTransaction BeginDbTransaction(IsolationLevel isolationLevel) => BeginTransaction(isolationLevel);

/// <summary>

/// Begins a database transaction.

/// </summary>

/// <returns>A <see cref="NpgsqlTransaction"/> object representing the new transaction.</returns>

/// <remarks>

/// Nested transactions are not supported.

/// Transactions created by this method will have the <see cref="IsolationLevel.ReadCommitted"/> isolation level.

/// </remarks>

public new NpgsqlTransaction BeginTransaction()

=> BeginTransaction(IsolationLevel.Unspecified);

/// <summary>

/// Begins a database transaction with the specified isolation level.

/// </summary>

/// <param name="level">The isolation level under which the transaction should run.</param>

/// <returns>A <see cref="NpgsqlTransaction"/> object representing the new transaction.</returns>

/// <remarks>Nested transactions are not supported.</remarks>

public new NpgsqlTransaction BeginTransaction(IsolationLevel level)

=> BeginTransaction(async: false, level, CancellationToken.None).GetAwaiter().GetResult();

async ValueTask<NpgsqlTransaction> BeginTransaction(bool async, IsolationLevel level, CancellationToken cancellationToken)

{

if (level == IsolationLevel.Chaos)

ThrowHelper.ThrowNotSupportedException($"Unsupported IsolationLevel: {nameof(IsolationLevel.Chaos)}");

CheckReady();

if (Connector is { InTransaction: true })

ThrowHelper.ThrowInvalidOperationException("A transaction is already in progress; nested/concurrent transactions aren't supported.");

// There was a committed/rolled back transaction, but it was not disposed

var connector = ConnectorBindingScope == ConnectorBindingScope.Transaction

? Connector

: await StartBindingScope(ConnectorBindingScope.Transaction, NpgsqlTimeout.Infinite, async, cancellationToken).ConfigureAwait(false);

Debug.Assert(connector != null);

try

{

// Note that beginning a transaction doesn't actually send anything to the backend (only prepends).

// But we start a user action to check the cancellation token and generate exceptions

using var _ = connector.StartUserAction(cancellationToken);

connector.Transaction ??= new NpgsqlTransaction(connector);

connector.Transaction.Init(level);

return connector.Transaction;

}

catch

{

EndBindingScope(ConnectorBindingScope.Transaction);

throw;

}

}

/// <summary>

/// Asynchronously begins a database transaction.

/// </summary>

/// <param name="isolationLevel">The isolation level under which the transaction should run.</param>

/// <param name="cancellationToken">

/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.

/// </param>

/// <returns>A task whose <see cref="ValueTask{T}.Result"/> property is an object representing the new transaction.</returns>

/// <remarks>

/// Nested transactions are not supported.

/// </remarks>

protected override async ValueTask<DbTransaction> BeginDbTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken)

=> await BeginTransactionAsync(isolationLevel, cancellationToken).ConfigureAwait(false);

/// <summary>

/// Asynchronously begins a database transaction.

/// </summary>

/// <param name="cancellationToken">

/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.

/// </param>

/// <returns>A task whose Result property is an object representing the new transaction.</returns>

/// <remarks>

/// Nested transactions are not supported.

/// Transactions created by this method will have the <see cref="IsolationLevel.ReadCommitted"/> isolation level.

/// </remarks>

public new ValueTask<NpgsqlTransaction> BeginTransactionAsync(CancellationToken cancellationToken = default)

=> BeginTransactionAsync(IsolationLevel.Unspecified, cancellationToken);

/// <summary>

/// Asynchronously begins a database transaction.

/// </summary>

/// <param name="level">The isolation level under which the transaction should run.</param>

/// <param name="cancellationToken">

/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.

/// </param>

/// <returns>A task whose <see cref="ValueTask{T}.Result"/> property is an object representing the new transaction.</returns>

/// <remarks>

/// Nested transactions are not supported.

/// </remarks>

public new ValueTask<NpgsqlTransaction> BeginTransactionAsync(IsolationLevel level, CancellationToken cancellationToken = default)

=> BeginTransaction(async: true, level, cancellationToken);

/// <summary>

/// Enlist transaction.

/// </summary>

public override void EnlistTransaction(Transaction? transaction)

{

if (Settings.Multiplexing)

throw new NotSupportedException("Ambient transactions aren't yet implemented for multiplexing");

if (EnlistedTransaction != null)

{

if (EnlistedTransaction.Equals(transaction))

return;

try

{

if (EnlistedTransaction.TransactionInformation.Status == System.Transactions.TransactionStatus.Active)

throw new InvalidOperationException($"Already enlisted to transaction (localid={EnlistedTransaction.TransactionInformation.LocalIdentifier})");

}

catch (ObjectDisposedException)

{

// The MSDTC 2nd phase is asynchronous, so we may end up checking the TransactionInformation on

// a disposed transaction. To be extra safe we catch that, and understand that the transaction

// has ended - no problem for reenlisting.

}

}

CheckReady();

var connector = StartBindingScope(ConnectorBindingScope.Transaction);

EnlistedTransaction = transaction;

if (transaction == null)

{

EndBindingScope(ConnectorBindingScope.Transaction);

return;

}

// Until #1378 is implemented, we have no recovery, and so no need to enlist as a durable resource manager

// (or as promotable single phase).

// Note that even when #1378 is implemented in some way, we should check for mono and go volatile in any case -

// distributed transactions aren't supported.

var volatileResourceManager = new VolatileResourceManager(this, transaction);

transaction.EnlistVolatile(volatileResourceManager, EnlistmentOptions.None);

volatileResourceManager.Init();

EnlistedTransaction = transaction;

LogMessages.EnlistedVolatileResourceManager(

Connector!.LoggingConfiguration.TransactionLogger,

transaction.TransactionInformation.LocalIdentifier,

connector.Id);

}

#endregion

#region Close

/// <summary>

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

/// </summary>

public override void Close() => Close(async: false).GetAwaiter().GetResult();

/// <summary>

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

/// </summary>

public override Task CloseAsync()

=> Close(async: true);

internal bool TakeCloseLock() => Interlocked.Exchange(ref _closing, 1) == 0;

internal void ReleaseCloseLock() => Volatile.Write(ref _closing, 0);

internal Task Close(bool async)

{

// Even though NpgsqlConnection isn't thread safe we'll make sure this part is.

// Because we really don't want double returns to the pool.

if (!TakeCloseLock())

return Task.CompletedTask;

switch (FullState)

{

case ConnectionState.Open:

case ConnectionState.Open | ConnectionState.Executing:

case ConnectionState.Open | ConnectionState.Fetching:

break;

case ConnectionState.Broken:

FullState = ConnectionState.Closed;

goto case ConnectionState.Closed;

case ConnectionState.Closed:

ReleaseCloseLock();

return Task.CompletedTask;

case ConnectionState.Connecting:

ReleaseCloseLock();

throw new InvalidOperationException("Can't close, connection is in state " + FullState);

default:

ReleaseCloseLock();

throw new ArgumentOutOfRangeException("Unknown connection state: " + FullState);

}

// TODO: The following shouldn't exist - we need to flow down the regular path to close any

// open reader / COPY. See test CloseDuringRead with multiplexing.

if (Settings.Multiplexing && ConnectorBindingScope == ConnectorBindingScope.None)

{

// TODO: Consider falling through to the regular reset logic. This adds some unneeded conditions

// and assignment but actual perf impact should be negligible (measure).

Debug.Assert(Connector == null);

ReleaseCloseLock();

FullState = ConnectionState.Closed;

LogMessages.ClosedMultiplexingConnection(_connectionLogger, Settings.Host!, Settings.Port, Settings.Database!, _userFacingConnectionString);

return Task.CompletedTask;

}

return CloseAsync(async);

}

async Task CloseAsync(bool async)

{

Debug.Assert(Connector != null);

Debug.Assert(ConnectorBindingScope != ConnectorBindingScope.None);

try

{

var connector = Connector;

LogMessages.ClosingConnection(_connectionLogger, Settings.Host!, Settings.Port, Settings.Database!, _userFacingConnectionString, connector.Id);

if (connector.CurrentReader != null || connector.CurrentCopyOperation != null)

{

// This method could re-enter connection.Close() due to an underlying connection failure.

await connector.CloseOngoingOperations(async).ConfigureAwait(false);

if (ConnectorBindingScope == ConnectorBindingScope.None)

{

Debug.Assert(Settings.Multiplexing);

Debug.Assert(Connector is null);

FullState = ConnectionState.Closed;

LogMessages.ClosedMultiplexingConnection(_connectionLogger, Settings.Host!, Settings.Port, Settings.Database!, _userFacingConnectionString);

return;

}

}

Debug.Assert(connector.IsReady || connector.IsBroken, $"Connector is not ready or broken during close, it's {connector.State}");

Debug.Assert(connector.CurrentReader == null);

Debug.Assert(connector.CurrentCopyOperation == null);

if (EnlistedTransaction != null)

{

// A System.Transactions transaction is still in progress

connector.Connection = null;

// Close the connection and disconnect it from the resource manager but leave the

// connector in an enlisted pending list in the data source. If another connection is opened within

// the same transaction scope, we will reuse this connector to avoid escalating to a distributed

// transaction

_dataSource?.AddPendingEnlistedConnector(connector, EnlistedTransaction);

EnlistedTransaction = null;

}

else

{

if (Settings.Pooling)

{

// Clear the buffer, roll back any pending transaction and prepend a reset message if needed

// Also returns the connector to the pool, if there is an open transaction and multiplexing is on

// Note that we're doing this only for pooled connections

await connector.Reset(async).ConfigureAwait(false);

}

else

{

// We're already doing the same in the NpgsqlConnector.Reset for pooled connections

// TODO: move reset logic to ConnectorSource.Return

connector.Transaction?.UnbindIfNecessary();

}

if (Settings.Multiplexing)

{

// We've already closed ongoing operations rolled back any transaction and the connector is already in the pool,

// so we must be unbound. Nothing to do.

Debug.Assert(ConnectorBindingScope == ConnectorBindingScope.None,

$"When closing a multiplexed connection, the connection was supposed to be unbound, but {nameof(ConnectorBindingScope)} was {ConnectorBindingScope}");

}

else

{

connector.Connection = null;

connector.Return();

}

}

LogMessages.ClosedConnection(_connectionLogger, Settings.Host!, Settings.Port, Settings.Database!, _userFacingConnectionString, connector.Id);

Connector = null;

ConnectorBindingScope = ConnectorBindingScope.None;

FullState = ConnectionState.Closed;

}

finally

{

ReleaseCloseLock();

}

}

/// <summary>

/// Releases all resources used by the <see cref="NpgsqlConnection"/>.

/// </summary>

/// <param name="disposing"><see langword="true"/> when called from <see cref="Dispose"/>;

/// <see langword="false"/> when being called from the finalizer.</param>

protected override void Dispose(bool disposing)

{

if (_disposed)

return;

if (disposing)

Close();

_disposed = true;

}

/// <summary>

/// Releases all resources used by the <see cref="NpgsqlConnection"/>.

/// </summary>

public override async ValueTask DisposeAsync()

{

if (_disposed)

return;

await CloseAsync().ConfigureAwait(false);

_disposed = true;

}

internal void MakeDisposed()

=> _disposed = true;

#endregion

#region Notifications and Notices

/// <summary>

/// Fires when PostgreSQL notices are received from PostgreSQL.

/// </summary>

/// <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 <see cref="Notification"/> event).

/// </remarks>

public event NoticeEventHandler? Notice;

/// <summary>

/// Fires when PostgreSQL notifications are received from PostgreSQL.

/// </summary>

/// <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 <see cref="Notice"/> event).

/// </remarks>

public event NotificationEventHandler? Notification;

internal void OnNotice(PostgresNotice e)

{

try

{

Notice?.Invoke(this, new NpgsqlNoticeEventArgs(e));

}

catch (Exception ex)

{

// Block all exceptions bubbling up from the user's event handler

LogMessages.CaughtUserExceptionInNoticeEventHandler(_connectionLogger, ex);

}

}

internal void OnNotification(NpgsqlNotificationEventArgs e)

{

try

{

Notification?.Invoke(this, e);

}

catch (Exception ex)

{

// Block all exceptions bubbling up from the user's event handler

LogMessages.CaughtUserExceptionInNotificationEventHandler(_connectionLogger, ex);

}

}

#endregion Notifications and Notices

#region SSL

/// <summary>

/// Returns whether SSL is being used for the connection.