Class MySqlConnection

Represents a connection to a MySQL database. This class cannot be inherited.

Inheritance

System.Object

System.MarshalByRefObject

System.ComponentModel.Component

System.Data.Common.DbConnection

MySqlConnection

Implements

System.ComponentModel.IComponent

System.Data.IDbConnection

System.IDisposable

System.IAsyncDisposable

System.ICloneable

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data.dll

Version: 9.1.0

Syntax

public sealed class MySqlConnection : DbConnection, IComponent, IDbConnection, IDisposable, IAsyncDisposable, ICloneable

Remarks

A MySqlConnection object represents a session to a MySQL data source. When you create an instance of MySqlConnection, all properties are set to their initial values.

If the MySqlConnection goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling Close() or Dispose().

Constructors

MySqlConnection()

Initializes a new instance of the MySqlConnection class.

Declaration

public MySqlConnection()

Remarks

You can read more about it here.

MySqlConnection(String)

Initializes a new instance of the MySqlConnection class when given a string containing the connection string.

Declaration

public MySqlConnection(string connectionString)

Parameters

Type	Name	Description
System.String	connectionString	The connection properties used to open the MySQL database.

Remarks

You can read more about it here.

Properties

ConnectionString

Gets or sets the string used to connect to a MySQL database.

Declaration

[Browsable(true)]
public override string ConnectionString { get; set; }

Property Value

Type	Description
System.String

Overrides

System.Data.Common.DbConnection.ConnectionString

Remarks

You can read more about it here.

ConnectionTimeout

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

Declaration

[Browsable(true)]
public override int ConnectionTimeout { get; }

Property Value

Type	Description
System.Int32

Overrides

System.Data.Common.DbConnection.ConnectionTimeout

Remarks

A value of 0 indicates no limit, and should be avoided in a call to ConnectionString because an attempt to connect will wait indefinitely.

Exceptions

Type	Condition
System.ArgumentException	The value set is less than 0.

Database

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

Declaration

[Browsable(true)]
public override string Database { get; }

Property Value

Type	Description
System.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 an empty string.

Overrides

System.Data.Common.DbConnection.Database

Remarks

The Database property does not update dynamically. If you change the current database using a SQL statement, then this property may reflect the wrong value. If you change the current database using the ChangeDatabase(String) method, this property is updated to reflect the new database.

DataSource

Gets the name of the MySQL server to which to connect.

Declaration

[Browsable(true)]
public override string DataSource { get; }

Property Value

Type	Description
System.String

Overrides

System.Data.Common.DbConnection.DataSource

DbProviderFactory

Gets the instance of the MySqlClientFactory

Declaration

protected override DbProviderFactory DbProviderFactory { get; }

Property Value

Type	Description
System.Data.Common.DbProviderFactory

Overrides

System.Data.Common.DbConnection.DbProviderFactory

IsDisposed

Declaration

[Browsable(true)]
public bool IsDisposed { get; }

Property Value

Type	Description
System.Boolean

IsPasswordExpired

Gets a boolean value that indicates whether the password associated to the connection is expired.

Declaration

public bool IsPasswordExpired { get; }

Property Value

Type	Description
System.Boolean

ServerThread

Returns the ID of the server thread this connection is executing on.

Declaration

[Browsable(false)]
public int ServerThread { get; }

Property Value

Type	Description
System.Int32

ServerVersion

Gets a string containing the version of the MySQL server to which the client is connected.

Declaration

[Browsable(false)]
public override string ServerVersion { get; }

Property Value

Type	Description
System.String	The version of the instance of MySQL.

Overrides

System.Data.Common.DbConnection.ServerVersion

Exceptions

Type	Condition
System.InvalidOperationException	The connection is closed.

State

Gets the current state of the connection.

Declaration

[Browsable(false)]
public override ConnectionState State { get; }

Property Value

Type	Description
System.Data.ConnectionState	A bitwise combination of the System.Data.ConnectionState values. The default is System.Data.ConnectionState.Closed.

Overrides

System.Data.Common.DbConnection.State

Remarks

The allowed state changes are:

From System.Data.ConnectionState.Closed to System.Data.ConnectionState.Open, using the System.Data.ConnectionState.Open method of the connection object.
From Open to Closed, using either the Close method or the Dispose method of the connection object.

UseCompression

Indicates if this connection should use compression when communicating with the server.

Declaration

[Browsable(false)]
public bool UseCompression { get; }

Property Value

Type	Description
System.Boolean

Methods

BeginDbTransaction(IsolationLevel)

Starts a database transaction.

Declaration

protected override DbTransaction BeginDbTransaction(IsolationLevel isolationLevel)

Parameters

Type	Name	Description
System.Data.IsolationLevel	isolationLevel	Specifies the System.Data.IsolationLevel for the transaction.

Returns

Type	Description
System.Data.Common.DbTransaction	A MySqlTransaction representing the new transaction.

Overrides

System.Data.Common.DbConnection.BeginDbTransaction(System.Data.IsolationLevel)

Exceptions

Type	Condition
System.InvalidOperationException	Parallel transactions are not supported.

BeginDbTransactionAsync(IsolationLevel, CancellationToken)

Asynchronous version of BeginDbTransaction(IsolationLevel).

Declaration

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

Parameters

Type	Name	Description
System.Data.IsolationLevel	isolationLevel	Specifies the System.Data.IsolationLevel for the transaction.
System.Threading.CancellationToken	cancellationToken	A token to cancel the asynchronous operation.

Returns

Type	Description
System.Threading.Tasks.ValueTask<System.Data.Common.DbTransaction>	A System.Threading.Tasks.ValueTask<TResult> representing the new transaction.

Overrides

System.Data.Common.DbConnection.BeginDbTransactionAsync(System.Data.IsolationLevel, System.Threading.CancellationToken)

Exceptions

Type	Condition
System.InvalidOperationException	Parallel transactions are not supported.

BeginTransaction()

Begins a database transaction.

Declaration

public MySqlTransaction BeginTransaction()

Returns

Type	Description
MySqlTransaction	A MySqlTransaction representing the new transaction.

Exceptions

Type	Condition
System.InvalidOperationException	Parallel transactions are not supported.

BeginTransaction(IsolationLevel, String)

Starts a database transaction.

Declaration

public MySqlTransaction BeginTransaction(IsolationLevel isolationLevel, string scope = "")

Parameters

Type	Name	Description
System.Data.IsolationLevel	isolationLevel	Specifies the System.Data.IsolationLevel for the transaction.
System.String	scope	The scope of the transaction.

Returns

Type	Description
MySqlTransaction	A MySqlTransaction representing the new transaction.

Exceptions

Type	Condition
System.InvalidOperationException	Parallel transactions are not supported.

BeginTransactionAsync()

Asynchronous version of BeginTransaction().

Declaration

public ValueTask<MySqlTransaction> BeginTransactionAsync()

Returns

Type	Description
System.Threading.Tasks.ValueTask<MySqlTransaction>	A MySqlTransaction representing the new transaction.

Exceptions

Type	Condition
System.InvalidOperationException	Parallel transactions are not supported.

BeginTransactionAsync(IsolationLevel)

Asynchronous version of BeginDbTransaction(IsolationLevel).

Declaration

public ValueTask<MySqlTransaction> BeginTransactionAsync(IsolationLevel isolationLevel)

Parameters

Type	Name	Description
System.Data.IsolationLevel	isolationLevel	Specifies the System.Data.IsolationLevel for the transaction.

Returns

Type	Description
System.Threading.Tasks.ValueTask<MySqlTransaction>	A System.Threading.Tasks.ValueTask<TResult> representing the new transaction.

Exceptions

Type	Condition
System.InvalidOperationException	Parallel transactions are not supported.

BeginTransactionAsync(IsolationLevel, CancellationToken)

Asynchronous version of BeginDbTransaction(IsolationLevel).

Declaration

public ValueTask<MySqlTransaction> BeginTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
System.Data.IsolationLevel	isolationLevel	Specifies the System.Data.IsolationLevel for the transaction.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
System.Threading.Tasks.ValueTask<MySqlTransaction>	A System.Threading.Tasks.ValueTask<TResult> representing the new transaction.

Exceptions

Type	Condition
System.InvalidOperationException	Parallel transactions are not supported.

BeginTransactionAsync(CancellationToken)

Asynchronous version of BeginTransaction().

Declaration

public ValueTask<MySqlTransaction> BeginTransactionAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	A token to cancel the asynchronous operation.

Returns

Type	Description
System.Threading.Tasks.ValueTask<MySqlTransaction>	A MySqlTransaction representing the new transaction.

Exceptions

Type	Condition
System.InvalidOperationException	Parallel transactions are not supported.

CancelQuery(Int32)

Cancels the query after the specified time interval.

Declaration

public void CancelQuery(int timeout)

Parameters

Type	Name	Description
System.Int32	timeout	The length of time (in seconds) to wait for the cancellation of the command execution.

CancelQueryAsync(Int32, CancellationToken)

Asynchronous version of the CancelQuery(Int32) method.

Declaration

public Task CancelQueryAsync(int timeout, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.Int32	timeout	The length of time (in seconds) to wait for the cancellation of the command execution.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
System.Threading.Tasks.Task

ChangeDatabase(String)

Changes the current database for an open MySqlConnection.

Declaration

public override void ChangeDatabase(string databaseName)

Parameters

Type	Name	Description
System.String	databaseName	The name of the database to use.

Overrides

System.Data.Common.DbConnection.ChangeDatabase(System.String)

Remarks

The value supplied in the databaseName parameter must be a valid database name. The databaseName parameter cannot contain a null value, an empty string, or a string with only blank characters.

When you are using connection pooling against MySQL, and you close the connection, it is returned to the connection pool. The next time the connection is retrieved from the pool, the reset connection request executes before the user performs any operations.

Exceptions

Type	Condition
System.ArgumentException	The database name is not valid.
System.InvalidOperationException	The connection is not open.
MySqlException	Cannot change the database.

ChangeDatabaseAsync(String, CancellationToken)

Asynchronous version of the ChangeDatabase(String) method.

Declaration

public override Task ChangeDatabaseAsync(string databaseName, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
System.String	databaseName	The name of the database to use.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
System.Threading.Tasks.Task	A task representing the asynchronous operation.

Overrides

System.Data.Common.DbConnection.ChangeDatabaseAsync(System.String, System.Threading.CancellationToken)

ClearAllPools()

Clears all connection pools.

Declaration

public static void ClearAllPools()

Remarks

ClearAllPools essentially performs a ClearPool(MySqlConnection) on all current connection pools.

ClearAllPoolsAsync(CancellationToken)

Asynchronous version of the ClearAllPools() method.

Declaration

public Task ClearAllPoolsAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
System.Threading.Tasks.Task

ClearPool(MySqlConnection)

Empties the connection pool associated with the specified connection.

Declaration

public static void ClearPool(MySqlConnection connection)

Parameters

Type	Name	Description
MySqlConnection	connection	The MySqlConnection associated with the pool to be cleared.

Remarks

ClearPool(MySqlConnection) clears the connection pool that is associated with the connection. If additional connections associated with connection are in use at the time of the call, they are marked appropriately and are discarded (instead of being returned to the pool) when Close() is called on them.

ClearPoolAsync(MySqlConnection, CancellationToken)

Asynchronous version of the ClearPool(MySqlConnection) method.

Declaration

public Task ClearPoolAsync(MySqlConnection connection, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
MySqlConnection	connection	The connection associated with the pool to be cleared.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
System.Threading.Tasks.Task

Clone()

Creates a new MySqlConnection object with the exact same ConnectionString value.

Declaration

public object Clone()

Returns

Type	Description
System.Object	A cloned MySqlConnection object.

CloneWith(String)

Returns an unopened copy of this connection with a new connection string. If the Password in connectionString is not set, the password from this connection will be used. This allows creating a new connection with the same security information while changing other options, such as database or pooling.

Declaration

public MySqlConnection CloneWith(string connectionString)

Parameters

Type	Name	Description
System.String	connectionString	The new connection string to be used.

Returns

Type	Description
MySqlConnection	A new MySqlConnection with different connection string options but the same password as this connection (unless overridden by `connectionString`).

Close()

Closes the connection to the database. This is the preferred method of closing any open connection.

Declaration

public override void Close()

Overrides

System.Data.Common.DbConnection.Close()

Remarks

The Close() method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled.

An application can call Close() more than one time. No exception is generated.

CloseAsync()

Asynchronous version of the Close() method.

Declaration

public override Task CloseAsync()

Returns

Type	Description
System.Threading.Tasks.Task

Overrides

System.Data.Common.DbConnection.CloseAsync()

CreateCommand()

Creates and returns a MySqlCommand object associated with the MySqlConnection.

Declaration

public MySqlCommand CreateCommand()

Returns

Type	Description
MySqlCommand	A MySqlCommand object.

CreateDbCommand()

Creates and returns a System.Data.Common.DbCommand object associated with the current connection.

Declaration

protected override DbCommand CreateDbCommand()

Returns

Type	Description
System.Data.Common.DbCommand	A System.Data.Common.DbCommand object.

Overrides

System.Data.Common.DbConnection.CreateDbCommand()

Dispose()

Releases the resources used by the MySqlConnection

Declaration

public void Dispose()

Dispose(Boolean)

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing

Overrides

System.ComponentModel.Component.Dispose(System.Boolean)

DisposeAsync()

Declaration

public override async ValueTask DisposeAsync()

Returns

Type	Description
System.Threading.Tasks.ValueTask

Overrides

System.Data.Common.DbConnection.DisposeAsync()

EnlistTransaction(Transaction)

Enlists in the specified transaction.

Declaration

public override void EnlistTransaction(Transaction transaction)

Parameters

Type	Name	Description
System.Transactions.Transaction	transaction	A reference to an existing System.Transactions.Transaction in which to enlist.

Overrides

System.Data.Common.DbConnection.EnlistTransaction(System.Transactions.Transaction)

Finalize()

Declaration

protected void Finalize()

GetSchema()

Returns schema information for the data source of this System.Data.Common.DbConnection.

Declaration

public override DataTable GetSchema()

Returns

Type	Description
System.Data.DataTable	A System.Data.DataTable that contains schema information.

Overrides

System.Data.Common.DbConnection.GetSchema()

GetSchema(String)

Returns schema information for the data source of this System.Data.Common.DbConnection using the specified string for the schema name.

Declaration

public override DataTable GetSchema(string collectionName)

Parameters

Type	Name	Description
System.String	collectionName	Specifies the name of the schema to return.

Returns

Type	Description
System.Data.DataTable	A System.Data.DataTable that contains schema information.

Overrides

System.Data.Common.DbConnection.GetSchema(System.String)

GetSchema(String, String[])

Returns schema information for the data source of this System.Data.Common.DbConnection using the specified string for the schema name and the specified string array for the restriction values.

Declaration

public override DataTable GetSchema(string collectionName, string[] restrictionValues)

Parameters

Type	Name	Description
System.String	collectionName	Specifies the name of the schema to return.
System.String[]	restrictionValues	Specifies a set of restriction values for the requested schema.

Returns

Type	Description
System.Data.DataTable	A System.Data.DataTable that contains schema information.

Overrides

System.Data.Common.DbConnection.GetSchema(System.String, System.String[])

GetSchemaAsync(String, String[], CancellationToken)

Asynchronous version of GetSchema(String, String[]).

Declaration

public Task<DataTable> GetSchemaAsync(string collectionName, string[] restrictionValues, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
System.String	collectionName	Specifies the name of the schema to return.
System.String[]	restrictionValues	Specifies a set of restriction values for the requested schema.
System.Threading.CancellationToken	cancellationToken	A token to cancel the asynchronous operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Data.DataTable>	A task representing the asynchronous operation.

GetSchemaAsync(String, CancellationToken)

Asynchronous version of GetSchema(String).

Declaration

public Task<DataTable> GetSchemaAsync(string collectionName, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
System.String	collectionName	Specifies the name of the schema to return.
System.Threading.CancellationToken	cancellationToken	A token to cancel the asynchronous operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Data.DataTable>	A task representing the asynchronous operation.

GetSchemaAsync(CancellationToken)

Asynchronous version of GetSchema().

Declaration

public Task<DataTable> GetSchemaAsync(CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	A token to cancel the asynchronous operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Data.DataTable>	A task representing the asynchronous operation.

GetSchemaCollection(String, String[])

Gets a schema collection based on the provided restriction values.

Declaration

public MySqlSchemaCollection GetSchemaCollection(string collectionName, string[] restrictionValues)

Parameters

Type	Name	Description
System.String	collectionName	The name of the collection.
System.String[]	restrictionValues	The values to restrict.

Returns

Type	Description
MySqlSchemaCollection	A schema collection object.

GetSchemaCollectionAsync(String, String[], CancellationToken)

Asynchronous version of the GetSchemaCollection(String, String[]) method.

Declaration

public Task<MySqlSchemaCollection> GetSchemaCollectionAsync(string collectionName, string[] restrictionValues, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
System.String	collectionName	The name of the collection.
System.String[]	restrictionValues	The values to restrict.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
System.Threading.Tasks.Task<MySqlSchemaCollection>	A collection of schema objects.

Open()

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

Declaration

public override void Open()

Overrides

System.Data.Common.DbConnection.Open()

Remarks

The MySqlConnection draws an open connection from the connection pool if one is available. Otherwise, it establishes a new connection to an instance of MySQL.

Exceptions

Type	Condition
System.InvalidOperationException	Cannot open a connection without specifying a data source or server.
MySqlException	A connection-level error occurred while opening the connection.

OpenAsync(CancellationToken)

Declaration

public override Task OpenAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken

Returns

Type	Description
System.Threading.Tasks.Task

Overrides

System.Data.Common.DbConnection.OpenAsync(System.Threading.CancellationToken)

Ping()

Pings the server.

Declaration

public bool Ping()

Returns

Type	Description
System.Boolean	`true` if the ping was successful; otherwise, `false`.

PingAsync()

Pings the server.

Declaration

public Task<bool> PingAsync()

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	`true` if the ping was successful; otherwise, `false`.

Events

InfoMessage

Occurs when MySQL returns warnings as a result of executing a command or query.

Declaration

public event MySqlInfoMessageEventHandler InfoMessage

Event Type

Type	Description
MySqlInfoMessageEventHandler

WebAuthnActionRequested

Occurs when WebAuthn authentication makes a request to perform the gesture action on a device.

Declaration

public event WebAuthnActionCallback WebAuthnActionRequested

Event Type

Type	Description
WebAuthnActionCallback

Implements

System.ComponentModel.IComponent

System.Data.IDbConnection

System.IDisposable

System.IAsyncDisposable

System.ICloneable