MySqlCommandBuilder Class

MySQL Connector/Net

previous page next page

Automatically generates single-table commands used to reconcile changes made to a DataSet with the associated MySQL database. This class cannot be inherited.

Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll) Version: 6.2.2.0

Syntax

C#
public sealed class MySqlCommandBuilder : DbCommandBuilder

Visual Basic (Declaration)
Public NotInheritable Class MySqlCommandBuilder _ Inherits DbCommandBuilder

Visual C++
public ref class MySqlCommandBuilder sealed : public DbCommandBuilder

Remarks

The MySqlDataAdapter does not automatically generate the SQL statements required to reconcile changes made to a DataSet with the associated instance of MySQL. However, you can create a MySqlCommandBuilder object to automatically generate SQL statements for single-table updates if you set the SelectCommand property of the MySqlDataAdapter. Then, any additional SQL statements that you do not set are generated by the MySqlCommandBuilder.

The MySqlCommandBuilder registers itself as a listener for RowUpdating events whenever you set the DataAdapter property. You can only associate one MySqlDataAdapter or MySqlCommandBuilder object with each other at one time.

To generate INSERT, UPDATE, or DELETE statements, the MySqlCommandBuilder uses the SelectCommand property to retrieve a required set of metadata automatically. If you change the SelectCommand after the metadata has is retrieved (for example, after the first update), you should call the [!:RefreshSchema] method to update the metadata.

The SelectCommand must also return at least one primary key or unique column. If none are present, an InvalidOperation exception is generated, and the commands are not generated.

The MySqlCommandBuilder also uses the Connection, CommandTimeout, and Transaction properties referenced by the SelectCommand. The user should call RefreshSchema if any of these properties are modified, or if the SelectCommand itself is replaced. Otherwise the InsertCommand, UpdateCommand, and DeleteCommand properties retain their previous values.

If you call Dispose, the MySqlCommandBuilder is disassociated from the MySqlDataAdapter, and the generated commands are no longer used.

Note: Caution must be used when using MySqlCOmmandBuilder on MySql 4.0 systems. With MySql 4.0, database/schema information is not provided to the connector for a query. This means that a query that pulls columns from two identically named tables in two or more different databases will not cause an exception to be thrown but will not work correctly. Even more dangerous is the situation where your select statement references database X but is executed in database Y and both databases have tables with similar layouts. This situation can cause unwanted changes or deletes. This note does not apply to MySQL versions 4.1 and later.

Examples

The following example uses the MySqlCommand, along MySqlDataAdapter and MySqlConnection, to select rows from a data source. The example is passed an initialized DataSet, a connection string, a query string that is a SQL SELECT statement, and a string that is the name of the database table. The example then creates a MySqlCommandBuilder.

CopyVB.NET

Public Shared Function SelectRows(myConnection As String, mySelectQuery As String, myTableName As String) As DataSet
Dim myConn As New MySqlConnection(myConnection)
Dim myDataAdapter As New MySqlDataAdapter()
myDataAdapter.SelectCommand = New MySqlCommand(mySelectQuery, myConn)
Dim cb As SqlCommandBuilder = New MySqlCommandBuilder(myDataAdapter)

myConn.Open()

Dim ds As DataSet = New DataSet
myDataAdapter.Fill(ds, myTableName)

' Code to modify data in DataSet here


' Without the MySqlCommandBuilder this line would fail.
myDataAdapter.Update(ds, myTableName)

myConn.Close()
End Function 'SelectRows

CopyC#

public static DataSet SelectRows(string myConnection, string mySelectQuery, string myTableName)
{
MySqlConnection myConn = new MySqlConnection(myConnection);
MySqlDataAdapter myDataAdapter = new MySqlDataAdapter();
myDataAdapter.SelectCommand = new MySqlCommand(mySelectQuery, myConn);
MySqlCommandBuilder cb = new MySqlCommandBuilder(myDataAdapter);

myConn.Open();

DataSet ds = new DataSet();
myDataAdapter.Fill(ds, myTableName);

//code to modify data in DataSet here

//Without the MySqlCommandBuilder this line would fail
myDataAdapter.Update(ds, myTableName);

myConn.Close();

return ds;
}

Inheritance Hierarchy

System..::.Object
  System..::.MarshalByRefObject
    System.ComponentModel..::.Component
      System.Data.Common..::.DbCommandBuilder
        MySql.Data.MySqlClient..::.MySqlCommandBuilder