Skip to content

Commit 03d237a

Browse files
committed
Add MySqlBulkLoader documentation. Fixes #781
1 parent 972a83a commit 03d237a

File tree

2 files changed

+130
-0
lines changed

2 files changed

+130
-0
lines changed

docs/content/api/mysql-bulk-copy.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ Due to [security features](../troubleshooting/load-data-local-infile/) in MySQL
2020
`MySqlBulkCopy` currently requires that the source data (`DataTable` or `IDataReader`) contain all
2121
the columns of the destination table in the same order.
2222

23+
For data that is in CSV or TSV format, use [`MySqlBulkLoader`](api/mysql-bulk-loader/) to bulk load the file.
24+
2325
**Note:** This API is a unique feature of MySqlConnector; you must [switch to MySqlConnector](../../overview/installing/)
2426
in order to use it. It is supported in version 0.62.0 and later.
2527

docs/content/api/mysql-bulk-loader.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
date: 2020-04-04
3+
menu:
4+
main:
5+
parent: api
6+
title: MySqlBulkLoader
7+
weight: 18
8+
---
9+
10+
# MySqlBulkLoader
11+
12+
`MySqlBulkLoader` lets you efficiently load a MySQL Server Table with data from a CSV or TSV file or `Stream`.
13+
14+
Due to [security features](../troubleshooting/load-data-local-infile/) in MySQL Server, the connection string
15+
**must** have `AllowLoadLocalInfile=true` in order to use a local source.
16+
17+
## Example Code
18+
19+
```csharp
20+
using (var connection = new MySqlConnection("...;AllowLoadLocalInfile=True"))
21+
{
22+
await connection.OpenAsync();
23+
var bulkLoader = new MySqlBulkLoader(connection)
24+
{
25+
FileName = @"C:\Path\To\file.csv",
26+
TableName = "destination",
27+
CharacterSet = "UTF8",
28+
NumberOfLinesToSkip = 1,
29+
FieldTerminator = ",",
30+
FieldQuotationCharacter = '"',
31+
FieldQuotationOptional = true,
32+
Local = true,
33+
}
34+
var rowCount = await bulkLoader.LoadAsync();
35+
}
36+
```
37+
38+
## API Reference
39+
40+
### Constructors
41+
42+
`public MySqlBulkLoader(MySqlConnection connection)`
43+
44+
Initializes a `MySqlBulkLoader` with the specified connection.
45+
46+
### Properties
47+
48+
`public string? CharacterSet { get; set; }`
49+
50+
(Optional) The character set of the source data. By default, the database's character set is used.
51+
52+
`public List<string> Columns { get; }`
53+
54+
(Optional) A list of the column names in the destination table that should be filled with data from the input file.
55+
56+
`public MySqlBulkLoaderConflictOption ConflictOption { get; set; }`
57+
58+
A `MySqlBulkLoaderConflictOption` value that specifies how conflicts are resolved (default `None`).
59+
60+
`public MySqlConnection Connection { get; set; }`
61+
62+
The `MySqlConnection` to use.
63+
64+
`public char EscapeCharacter { get; set; }`
65+
66+
(Optional) The character used to escape instances of `FieldQuotationCharacter` within field values.
67+
68+
`public List<string> Expressions { get; }`
69+
70+
(Optional) A list of expressions used to set field values from the columns in the source data.
71+
72+
`public char FieldQuotationCharacter { get; set; }`
73+
74+
(Optional) The character used to enclose fields in the source data.
75+
76+
`public bool FieldQuotationOptional { get; set; }`
77+
78+
Whether quoting fields is optional (default `false`).
79+
80+
`public string? FieldTerminator { get; set; }`
81+
82+
(Optional) The string fields are terminated with.
83+
84+
`public string? FileName { get; set; }`
85+
86+
The name of the local (if `Local` is `true`) or remote (otherwise) file to load. Either this or `SourceStream` must be set.
87+
88+
`public string? LinePrefix { get; set; }`
89+
90+
(Optional) A prefix in each line that should be skipped when loading.
91+
92+
`public string? LineTerminator { get; set; }`
93+
94+
(Optional) The string lines are terminated with.
95+
96+
`public bool Local { get; set; }`
97+
98+
Whether a local file is being used (default `true`).
99+
100+
`public int NumberOfLinesToSkip { get; set; }`
101+
102+
The number of lines to skip at the beginning of the file (default `0`).
103+
104+
`public MySqlBulkLoaderPriority Priority { get; set; }`
105+
106+
A `MySqlBulkLoaderPriority` giving the priority to load with (default `None`).
107+
108+
`public Stream? SourceStream { get; set; }`
109+
110+
A `Stream` containing the data to load. Either this or `FileName` must be set. The `Local` property must be `true` if this is set.
111+
112+
`public string? TableName { get; set; }`
113+
114+
The name of the table to load into. If this is a reserved word or contains spaces, it must be quoted.
115+
116+
`public int Timeout { get; set; }`
117+
118+
The timeout (in milliseconds) to use.
119+
120+
### Methods
121+
122+
`public int Load();`
123+
124+
`public Task<int> LoadAsync();`
125+
126+
`public Task<int> LoadAsync(CancellationToken cancellationToken);`
127+
128+
Loads all data in the source file or `Stream` into the destination table. Returns the number of rows inserted.

0 commit comments

Comments
 (0)