New docs.

FirebirdSQL · Apr 12, 2022 · eee30d6 · eee30d6
1 parent 205c126
commit eee30d6
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -11,6 +11,7 @@
 * [Time zones](docs/time-zones.md)
 * [DECFLOAT datatype](docs/decfloat.md)
 * [INT128 datatype](docs/int128.md)
+* [Batching](docs/batching.md)
 
 ## Packages
 
@@ -41,4 +42,4 @@
 ### 3rd party code
 
 * For zlib compression the provider uses pieces from [DotNetZip](http://dotnetzip.codeplex.com/) library.
-* For RC4 encryption the provider uses pieces from [Bouncy Castle](https://www.bouncycastle.org/csharp/index.html) library.
+* For RC4 encryption the provider uses pieces from [Bouncy Castle](https://www.bouncycastle.org/csharp/index.html) library.
diff --git a/docs/batching.md b/docs/batching.md
@@ -0,0 +1,21 @@
+# Batching
+
+Batching is supported for Firebird 4 (and above). The work is handled by `FbBatchCommand` class. It has similar API surface as `FbCommand`. The usage should feel familiar.
+
+### Specifics
+
+Calling the `ExecuteNonQuery`/`ExecuteNonQueryAsync` does not throw an exception, should the exception happen on server while processing the data. Instead the returned `FbBatchNonQueryResult` object should be used to check the status. The `EnsureSuccess` method or `AllSuccess` property can be used for global check. Further enumeration gives detailed information.
+
+Properties `MultiError`, `ReturnRecordsAffected` and `BatchBufferSize` allow for behavior fine-tuning (these represent `TAG_MULTIERROR`, `TAG_RECORD_COUNTS` and `TAG_BUFFER_BYTES_SIZE` in BPB).
+
+When dealing with huge batches of possible unlimited size, it's good to use `ComputeCurrentBatchSize`/`ComputeCurrentBatchSizeAsync` to make sure the batch is not over `BatchBufferSize`. However calling `ComputeCurrentBatchSize`/`ComputeCurrentBatchSizeAsync` is not cheap and should be handled accordingly.    
+
+### Limitations
+
+At the moment batching is not supported for Firebird Embedded. The progress is tracked [here](https://github.com/FirebirdSQL/NETProvider/issues/1022).
+
+Using (real) blobs as values is not supported. Regular `byte[]`, `string`, etc. values and the implicit conversions work just fine. The progress is tracked [here](https://github.com/FirebirdSQL/NETProvider/issues/1038). 
+
+### Examples
+
+Examples can be found in `FbBatchCommandTests`.