Class MySqlConnection

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

Inheritance

Object

MarshalByRefObject

Component

DbConnection

MySqlConnection

Implements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data.dll

Version: 8.0.32

Syntax

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

Remarks

A MySqlConnection object represents a session to a MySQL Server 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
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 Server database.

Declaration

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

Property Value

Type	Description
String

Overrides

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
Int32

Overrides

DbConnection.ConnectionTimeout

Remarks

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

Exceptions

Type	Condition
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
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

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
String

Overrides

DbConnection.DataSource

DbProviderFactory

Gets the instance of the MySqlClientFactory

Declaration

protected override DbProviderFactory DbProviderFactory { get; }

Property Value

Type	Description
DbProviderFactory

Overrides

DbConnection.DbProviderFactory

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
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
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
String	The version of the instance of MySQL.

Overrides

DbConnection.ServerVersion

Exceptions

Type	Condition
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
ConnectionState	A bitwise combination of the ConnectionState values. The default is Closed.

Overrides

DbConnection.State

Remarks

The allowed state changes are:

From Closed to Open, using the 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
Boolean

Methods

BeginDbTransaction(IsolationLevel)

Starts a database transaction.

Declaration

protected override DbTransaction BeginDbTransaction(IsolationLevel isolationLevel)

Parameters

Type	Name	Description
IsolationLevel	isolationLevel	Specifies the isolation level for the transaction.

Returns

Type	Description
DbTransaction	An object representing the new transaction.

Overrides

DbConnection.BeginDbTransaction(IsolationLevel)

BeginTransaction()

Declaration

public MySqlTransaction BeginTransaction()

Returns

Type	Description
MySqlTransaction

BeginTransaction(IsolationLevel, String)

Declaration

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

Parameters

Type	Name	Description
IsolationLevel	iso
String	scope

Returns

Type	Description
MySqlTransaction

BeginTransactionAsync()

Initiates the asynchronous execution of a transaction.

Declaration

public Task<MySqlTransaction> BeginTransactionAsync()

Returns

Type	Description
Task<MySqlTransaction>	An object representing the new transaction.

BeginTransactionAsync(IsolationLevel)

Asynchronous version of BeginTransaction.

Declaration

public Task<MySqlTransaction> BeginTransactionAsync(IsolationLevel iso)

Parameters

Type	Name	Description
IsolationLevel	iso	The isolation level under which the transaction should run.

Returns

Type	Description
Task<MySqlTransaction>	An object representing the new transaction.

BeginTransactionAsync(IsolationLevel, CancellationToken)

Asynchronous version of BeginTransaction.

Declaration

public Task<MySqlTransaction> BeginTransactionAsync(IsolationLevel iso, CancellationToken cancellationToken)

Parameters

Type	Name	Description
IsolationLevel	iso	The isolation level under which the transaction should run.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<MySqlTransaction>	An object representing the new transaction.

BeginTransactionAsync(CancellationToken)

Asynchronous version of BeginTransaction.

Declaration

public Task<MySqlTransaction> BeginTransactionAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<MySqlTransaction>	An object representing the new transaction.

CancelQuery(Int32)

Cancels the query after the specified time interval.

Declaration

public void CancelQuery(int timeout)

Parameters

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

ChangeDatabase(String)

Changes the current database for an open MySqlConnection.

Declaration

public override void ChangeDatabase(string databaseName)

Parameters

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

Overrides

DbConnection.ChangeDatabase(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
ArgumentException	The database name is not valid.
InvalidOperationException	The connection is not open.
MySqlException	Cannot change the database.

ChangeDataBaseAsync(String)

Asynchronous version of the ChangeDataBase method.

Declaration

public Task ChangeDataBaseAsync(string databaseName)

Parameters

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

Returns

Type	Description
Task

ChangeDataBaseAsync(String, CancellationToken)

Asynchronous version of the ChangeDataBase method.

Declaration

public Task ChangeDataBaseAsync(string databaseName, CancellationToken cancellationToken)

Parameters

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

Returns

Type	Description
Task

ClearAllPools()

Clears all connection pools.

Declaration

public static void ClearAllPools()

Remarks

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

ClearAllPoolsAsync()

Asynchronous version of the ClearAllPools() method.

Declaration

public Task ClearAllPoolsAsync()

Returns

Type	Description
Task

ClearAllPoolsAsync(CancellationToken)

Asynchronous version of the ClearAllPools() method.

Declaration

public Task ClearAllPoolsAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
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)

Asynchronous version of the ClearPool(MySqlConnection) method.

Declaration

public Task ClearPoolAsync(MySqlConnection connection)

Parameters

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

Returns

Type	Description
Task

ClearPoolAsync(MySqlConnection, CancellationToken)

Asynchronous version of the ClearPool(MySqlConnection) method.

Declaration

public Task ClearPoolAsync(MySqlConnection connection, CancellationToken cancellationToken)

Parameters

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

Returns

Type	Description
Task

Clone()

Creates a new MySqlConnection object with the exact same ConnectionString value

Declaration

public object Clone()

Returns

Type	Description
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
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

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

Returns

Type	Description
Task

CloseAsync(CancellationToken)

Asynchronous version of the Close() method.

Declaration

public Task CloseAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task

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
DbCommand	A DbCommand object.

Overrides

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
Boolean	disposing

Overrides

Component.Dispose(Boolean)

EnlistTransaction(Transaction)

Enlists in the specified transaction.

Declaration

public override void EnlistTransaction(Transaction transaction)

Parameters

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

Overrides

DbConnection.EnlistTransaction(Transaction)

Finalize()

Declaration

protected void Finalize()

GetSchema()

Returns schema information for the data source of this DbConnection.

Declaration

public override DataTable GetSchema()

Returns

Type	Description
DataTable	A DataTable that contains schema information.

Overrides

DbConnection.GetSchema()

GetSchema(String)

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

Declaration

public override DataTable GetSchema(string collectionName)

Parameters

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

Returns

Type	Description
DataTable	A DataTable that contains schema information.

Overrides

DbConnection.GetSchema(String)

GetSchema(String, String[])

Returns schema information for the data source of this 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
String	collectionName	Specifies the name of the schema to return.
String[]	restrictionValues	Specifies a set of restriction values for the requested schema.

Returns

Type	Description
DataTable	A DataTable that contains schema information.

Overrides

DbConnection.GetSchema(String, String[])

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
String	collectionName	The name of the collection.
String[]	restrictionValues	The values to restrict.

Returns

Type	Description
MySqlSchemaCollection	A schema collection object.

GetSchemaCollectionAsync(String, String[])

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

Declaration

public Task<MySqlSchemaCollection> GetSchemaCollectionAsync(string collectionName, string[] restrictionValues)

Parameters

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

Returns

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

GetSchemaCollectionAsync(String, String[], CancellationToken)

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

Declaration

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

Parameters

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

Returns

Type	Description
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

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
InvalidOperationException	Cannot open a connection without specifying a data source or server.
MySqlException	A connection-level error occurred while opening the connection.

Ping()

Pings the server.

Declaration

public bool Ping()

Returns

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

Events

FidoActionRequested

Occurs when FIDO authentication request to perform gesture action on a device.

Declaration

public event FidoActionCallback FidoActionRequested

Event Type

Type	Description
FidoActionCallback

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

Implements

System.ComponentModel.IComponent

System.Data.IDbConnection

System.IDisposable

System.IAsyncDisposable

System.ICloneable