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

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.

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

}

/// <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 at https://www.npgsql.org/doc/release-notes/7.0.html#managing-type-mappings-at-the-connection-level-is-no-longer-supported for more information.")]

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

/// <summary>

/// Connection-level type mapping is no longer supported. See the 7.0 release notes at https://www.npgsql.org/doc/release-notes/7.0.html#managing-type-mappings-at-the-connection-level-is-no-longer-supported for configuring type mapping on NpgsqlDataSource.

/// </summary>

[Obsolete("Connection-level type mapping is no longer supported. See the 7.0 release notes at https://www.npgsql.org/doc/release-notes/7.0.html#managing-type-mappings-at-the-connection-level-is-no-longer-supported 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;

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

}

internal static NpgsqlConnection FromDataSource(NpgsqlDataSource dataSource)

};

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

}

internal Task Open(bool async, CancellationToken cancellationToken)

}

#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

}

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

}

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

}

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

}

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

}

#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(level, NpgsqlTransactionOptions.None);

/// <summary>

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

/// </summary>

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

/// <param name="options">Npgsql-specific options under which the transaction should run, e.g. read-only or deferrable.</param>

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

/// <remarks>

/// Nested transactions are not supported.

/// Note that there's no single-argument <c>options</c>-only overload: combined with the existing <see cref="IsolationLevel"/>

/// overloads, that would make calls like <c>BeginTransaction(default)</c> ambiguous.

/// </remarks>

public NpgsqlTransaction BeginTransaction(IsolationLevel level, NpgsqlTransactionOptions options)

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

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

}

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

=> BeginTransactionAsync(level, NpgsqlTransactionOptions.None, cancellationToken);

/// <summary>

/// Asynchronously begins a database transaction with the specified isolation level and options.

/// </summary>

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

/// <param name="options">Npgsql-specific options under which the transaction should run, e.g. read-only or deferrable.</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 ValueTask<NpgsqlTransaction> BeginTransactionAsync(IsolationLevel level, NpgsqlTransactionOptions options, CancellationToken cancellationToken = default)

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

/// <summary>

/// Enlist transaction.

/// </summary>

public override void EnlistTransaction(Transaction? transaction)

}

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

}

async Task CloseAsync(bool async)

}

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

}

/// <summary>

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

/// </summary>

public override async ValueTask DisposeAsync()

}

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)

}

internal void OnNotification(NpgsqlNotificationEventArgs e)

}

#endregion Notifications and Notices

#region SSL

/// <summary>

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

/// </summary>

internal bool IsSslEncrypted

}

/// <summary>

/// Returns whether GSS encryption is being used for the connection.

/// </summary>

internal bool IsGssEncrypted

}

/// <summary>

/// Returns whether SCRAM-SHA256 is being user for the connection

/// </summary>

internal bool IsScram

}

/// <summary>

/// Returns whether SCRAM-SHA256-PLUS is being user for the connection

/// </summary>

internal bool IsScramPlus

}

/// <summary>

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

/// </summary>

/// <remarks>

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

/// </remarks>

[Obsolete("Use UseSslClientAuthenticationOptionsCallback")]

public ProvideClientCertificatesCallback? ProvideClientCertificatesCallback { get; set; }

/// <summary>

/// 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 <see cref="SslMode.VerifyFull" /> or <see cref="SslMode.VerifyCA" /> instead.

/// </summary>

/// <remarks>

/// <para>

/// Cannot be used in conjunction with <see cref="SslMode.Disable" />, <see cref="SslMode.VerifyCA" /> and

/// <see cref="SslMode.VerifyFull" />.

/// </para>

/// <para>

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

/// </para>

/// </remarks>

[Obsolete("Use UseSslClientAuthenticationOptionsCallback")]

public RemoteCertificateValidationCallback? UserCertificateValidationCallback { get; set; }

/// <summary>

/// When using SSL/TLS, this is a callback that allows customizing SslStream's authentication options.

/// </summary>

/// <remarks>

/// <para>

/// See <see href="https://learn.microsoft.com/en-us/dotnet/api/system.net.security.sslclientauthenticationoptions"/>.

/// </para>

/// </remarks>

public Action<SslClientAuthenticationOptions>? SslClientAuthenticationOptionsCallback { get; set; }

#endregion SSL

#region Backend version, capabilities, settings

// TODO: We should probably move DatabaseInfo from each connector to the pool (but remember unpooled)

/// <summary>

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

/// <remarks>

/// <p>

/// This can only be called when the connection is open.

/// </p>

/// <p>

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

/// </p>

/// </remarks>