diff --git a/docs/content/api/mysql-batch.md b/docs/content/api/mysql-batch.md new file mode 100644 index 000000000..aab65bdf6 --- /dev/null +++ b/docs/content/api/mysql-batch.md @@ -0,0 +1,94 @@ +--- +date: 2019-06-23 +menu: + main: + parent: api +title: MySqlBatch +weight: 10 +--- + +# MySqlBatch + +`MySqlBatch` implements the new [ADO.NET batching API](https://github.com/dotnet/corefx/issues/35135). +**It is currently experimental** and may change in the future. + +When using MariaDB (10.2 or later), the commands will be sent in a single batch, reducing network +round-trip time. With other MySQL Servers, this may be no more efficient than executing the commands +individually. + +## Example Code + +```csharp +using (var connection = new MySqlConnection("...connection string...")) +{ + await connection.OpenAsync(); + using (var batch = new MySqlBatch(connection) + { + BatchCommands = + { + new MySqlBatchCommand("INSERT INTO departments(name) VALUES(@name);") + { + Parameters = + { + new MySqlParameter("@name", "Sales"), + }, + }, + new MySqlBatchCommand("SET @dept_id = last_insert_id()"), + new MySqlBatchCommand("INSERT INTO employees(name, department_id) VALUES(@name, @dept_id);") + { + Parameters = + { + new MySqlParameter("@name", "Jim Halpert"), + }, + }, + new MySqlBatchCommand("INSERT INTO employees(name, department_id) VALUES(@name, @dept_id);") + { + Parameters = + { + new MySqlParameter("@name", "Dwight Schrute"), + }, + }, + }, + }) + { + await batch.ExecuteNonQueryAsync(); + } +} +``` + +## API Reference + +### Constructors +`public MySqlBatch()` + +Parameterless constructor. +*** +`public MySqlBatch(MySqlConnection connection)` + +Constructor that accepts a `MySqlConnection` and sets the `Connection` property. + +### Properties + +`public MySqlBatchCommandCollection BatchCommands { get; }` + +The collection of commands that will be executed in the batch. + +### Methods + +`public void ExecuteNonQuery();` +`public Task ExecuteNonQueryAsync();` + +Executes all the commands in the batch, returning nothing. +*** + +`public object ExecuteScalar();` +`public Task ExecuteScalarAsync();` + +Executes all the commands in the batch, returning the value from the first column in the first row of the first resultset. +*** + +`public MySqlDataReader ExecuteReader();` +`public Task ExecuteReaderAsync();` + +Executes all the commands in the batch, return a `DbDataReader` that can iterate over the result sets. If multiple +resultsets are returned, use `DbDataReader.NextResult` (or `NextResultAsync`) to access them. diff --git a/docs/content/api/mysql-connection.md b/docs/content/api/mysql-connection.md index 8fe5e5249..993033783 100644 --- a/docs/content/api/mysql-connection.md +++ b/docs/content/api/mysql-connection.md @@ -1,11 +1,11 @@ --- -lastmod: 2017-11-06 +lastmod: 2019-06-23 date: 2016-10-16 menu: main: parent: api title: MySqlConnection -weight: 10 +weight: 30 --- MySqlConnection @@ -17,50 +17,61 @@ please refer to its documentation. Additionally, MySqlConnection provides the following public properties and methods that may be used: ### Constructors -`public MySqlConnection()` +`MySqlConnection()` -Parameterless constructor +Parameterless constructor. *** -`public MySqlConnection(string connectionString)` +`MySqlConnection(string connectionString)` + +Constructor that sets the `ConnectionString` property. -Constructor that set the connection string -*** ### Additional Properties -`public int ServerThread` +`int ServerThread` -Connection ID from MySQL Server +Connection ID from MySQL Server. *** +`bool CanCreateBatch` + +Returns `true`. + ### Additional Instance Methods -`public Task BeginTransactionAsync(CancellationToken cancellationToken = default(CancellationToken))` +`Task BeginTransactionAsync(CancellationToken cancellationToken = default(CancellationToken))` -Async version of BeginTransaction +Async version of `BeginTransaction`. *** -`public Task BeginTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken = default(CancellationToken))` +`Task BeginTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken = default(CancellationToken))` -Async version of BeginTransaction that supports setting Isolation Level +Async version of `BeginTransaction` that supports setting Isolation Level. *** -### Additional Static Methods -`public static void ClearPool(MySqlConnection connection)` +`MySqlBatch CreateBatch()` -Clears the connection pool that the connection belongs to +Creates a `MySqlBatch` object for executing batched commands. *** -`public static Task ClearPoolAsync(MySqlConnection connection)` +`MySqlBatchCommand CreateBatchCommand()` -Async version of ClearPool +Creates a `MySqlBatchCommand` object (that can be used with `MySqlBatch.BatchCommands`). + +### Additional Static Methods +`static void ClearPool(MySqlConnection connection)` + +Clears the connection pool that the connection belongs to. *** -`public static Task ClearPoolAsync(MySqlConnection connection, CancellationToken cancellationToken)` +`static Task ClearPoolAsync(MySqlConnection connection)` -Async version of ClearPool with cancellation token support +Async version of `ClearPool`. *** -`public static void ClearAllPools()` +`static Task ClearPoolAsync(MySqlConnection connection, CancellationToken cancellationToken)` -Clears all connection pools in the entire application +Async version of `ClearPool` with cancellation token support. *** -`public static Task ClearAllPoolsAsync()` +`static void ClearAllPools()` -Async version of ClearAllPoolsAsync +Clears all connection pools in the entire application. *** -`public static Task ClearAllPoolsAsync(CancellationToken cancellationToken)` +`static Task ClearAllPoolsAsync()` -Async version of ClearAllPoolsAsync with cancellation token support +Async version of `ClearAllPoolsAsync`. *** +`static Task ClearAllPoolsAsync(CancellationToken cancellationToken)` + +Async version of `ClearAllPoolsAsync` with cancellation token support. diff --git a/docs/content/api/mysql-data-reader.md b/docs/content/api/mysql-data-reader.md index 918046d88..6382c465f 100644 --- a/docs/content/api/mysql-data-reader.md +++ b/docs/content/api/mysql-data-reader.md @@ -5,7 +5,7 @@ menu: main: parent: api title: MySqlDataReader -weight: 30 +weight: 40 --- MySqlDataReader diff --git a/docs/content/api/mysql-transaction.md b/docs/content/api/mysql-transaction.md index f246f1bd6..038da7894 100644 --- a/docs/content/api/mysql-transaction.md +++ b/docs/content/api/mysql-transaction.md @@ -5,7 +5,7 @@ menu: main: parent: api title: MySqlTransaction -weight: 40 +weight: 50 --- MySqlTransaction