# Class NpgsqlBatch

Namespace
  Npgsql

Assembly
  Npgsql.dll

Represents a batch of commands that can be executed against a data source in a single round trip. Provides a base class for database-specific classes that represent command batches.

    public class NpgsqlBatch : DbBatch, IDisposable, IAsyncDisposable

Inheritance
  object
  DbBatch
  NpgsqlBatch

Implements
  IDisposable
  IAsyncDisposable

Inherited Members
  DbBatch.DisposeAsync()
  object.Equals(object)
  object.Equals(object, object)
  object.GetHashCode()
  object.GetType()
  object.MemberwiseClone()
  object.ReferenceEquals(object, object)
  object.ToString()

## Constructors

### NpgsqlBatch(NpgsqlConnection?, NpgsqlTransaction?)

Initializes a new NpgsqlBatch.

    public NpgsqlBatch(NpgsqlConnection? connection = null, NpgsqlTransaction? transaction = null)

#### Parameters

`connection` NpgsqlConnection

  A NpgsqlConnection that represents the connection to a PostgreSQL server.

`transaction` NpgsqlTransaction

  The NpgsqlTransaction in which the NpgsqlCommand executes.

## Properties

### BatchCommands

Gets the collection of DbBatchCommand objects.

    public NpgsqlBatchCommandCollection BatchCommands { get; }

#### Property Value

NpgsqlBatchCommandCollection

  The commands contained within the batch.

### Connection

Gets or sets the DbConnection used by this DbBatch.

    public NpgsqlConnection? Connection { get; set; }

#### Property Value

NpgsqlConnection

  The connection to the data source.

### DbBatchCommands

When overridden in a derived class, gets the collection of DbBatchCommand objects.

    protected override DbBatchCommandCollection DbBatchCommands { get; }

#### Property Value

DbBatchCommandCollection

  The commands contained within the batch.

### DbConnection

When overridden in a derived class, gets or sets the DbConnection used by this DbBatch.

    protected override DbConnection? DbConnection { get; set; }

#### Property Value

DbConnection

  The connection to the data source.

### DbTransaction

When overridden in a derived class, gets or sets the DbTransaction within which this DbBatch object executes.

    protected override DbTransaction? DbTransaction { get; set; }

#### Property Value

DbTransaction

  The transaction within which a batch of a .NET data provider executes. The default value is a null reference (`Nothing` in Visual Basic).

### EnableErrorBarriers

Controls whether to place error barriers between all batch commands within this batch. Default to false.

    public bool EnableErrorBarriers { get; set; }

#### Property Value

bool

#### Remarks

By default, any exception in a command causes later commands in the batch to be skipped, and earlier commands to be rolled back. Enabling error barriers ensures that errors do not affect other commands in the batch.

Note that if the batch is executed within an explicit transaction, the first error places the transaction in a failed state, causing all later commands to fail in any case. As a result, this option is useful mainly when there is no explicit transaction.

At the PostgreSQL wire protocol level, this corresponds to inserting a Sync message between each command, rather than grouping all the batch's commands behind a single terminating Sync.

To control error barriers on a command-by-command basis, see AppendErrorBarrier.

### Timeout

Gets or sets the wait time (in seconds) before terminating the attempt to execute the batch and generating an error.

    public override int Timeout { get; set; }

#### Property Value

int

  The time in seconds to wait for the batch to execute.

### Transaction

Gets or sets the DbTransaction within which this DbBatch object executes.

    public NpgsqlTransaction? Transaction { get; set; }

#### Property Value

NpgsqlTransaction

  The transaction within which a batch of a .NET data provider executes. The default value is a null reference (`Nothing` in Visual Basic).

## Methods

### Cancel()

Attempts to cancel the execution of a DbBatch.

    public override void Cancel()

### CreateBatchCommand()

Creates a new instance of a DbBatchCommand object.

    public NpgsqlBatchCommand CreateBatchCommand()

#### Returns

NpgsqlBatchCommand

  A DbBatchCommand object.

### CreateDbBatchCommand()

When overridden in a derived class, creates a new instance of a DbBatchCommand object.

    protected override DbBatchCommand CreateDbBatchCommand()

#### Returns

DbBatchCommand

  A DbBatchCommand object.

### Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

    public override void Dispose()

### ExecuteDbDataReader(CommandBehavior)

When overridden in a derived class, executes the batch against its connection, returning a DbDataReader that can be used to access the results.

    protected override DbDataReader ExecuteDbDataReader(CommandBehavior behavior)

#### Parameters

`behavior` CommandBehavior

  An instance of CommandBehavior, specifying options for batch execution and data retrieval.

#### Returns

DbDataReader

  A DbDataReader object.

#### Exceptions

DbException

  An error occurred while executing the batch.

ArgumentException

  The CommandBehavior value is invalid.

### ExecuteDbDataReaderAsync(CommandBehavior, CancellationToken)

Providers should implement this method to provide a non-default implementation for System.Data.Common.DbCommand.ExecuteReader* overloads.

The default implementation invokes the synchronous ExecuteReader() method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteReader will be communicated via the returned Task Exception property.

This method accepts a cancellation token that can be used to request the operation to be cancelled early. Implementations may ignore this request.

    protected override Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBehavior behavior, CancellationToken cancellationToken)

#### Parameters

`behavior` CommandBehavior

  One of the enumeration values that specifies options for batch execution and data retrieval.

`cancellationToken` CancellationToken

  A token to cancel the asynchronous operation.

#### Returns

Task<DbDataReader>

  A task representing the asynchronous operation.

#### Exceptions

OperationCanceledException

  The cancellation token was canceled. This exception is stored into the returned task.

### ExecuteNonQuery()

Executes the batch against its connection object, returning the total number of rows affected across all the batch commands.

    public override int ExecuteNonQuery()

#### Returns

int

  The total number of rows affected across all the batch commands.

### ExecuteNonQueryAsync(CancellationToken)

This is the asynchronous version of ExecuteNonQuery(). Providers should override with an appropriate implementation. The cancellation token may optionally be ignored.

The default implementation invokes the synchronous ExecuteNonQuery() method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteNonQuery() will be communicated via the returned Task Exception property.

Do not invoke other methods and properties of the `DbCommand` object until the returned Task is complete.

    public override Task<int> ExecuteNonQueryAsync(CancellationToken cancellationToken = default)

#### Parameters

`cancellationToken` CancellationToken

  A token to cancel the asynchronous operation.

#### Returns

Task<int>

  A task representing the asynchronous operation.

#### Exceptions

DbException

  An error occurred while executing the batch.

OperationCanceledException

  The cancellation token was canceled. This exception is stored into the returned task.

### ExecuteReader(CommandBehavior)

Executes the batch against its connection, returning a DbDataReader that can be used to access the results.

    public NpgsqlDataReader ExecuteReader(CommandBehavior behavior = CommandBehavior.Default)

#### Parameters

`behavior` CommandBehavior

  One of the enumeration values that specifies options for batch execution and data retrieval.

#### Returns

NpgsqlDataReader

  A DbDataReader object.

### ExecuteReaderAsync(CommandBehavior, CancellationToken)

An asynchronous version of System.Data.Common.DbBatch.ExecuteReader*, which executes the batch against its connection, returning a DbDataReader that can be used to access the results.

    public Task<NpgsqlDataReader> ExecuteReaderAsync(CommandBehavior behavior, CancellationToken cancellationToken = default)

#### Parameters

`behavior` CommandBehavior

  One of the enumeration values that specifies options for batch execution and data retrieval.

`cancellationToken` CancellationToken

  A token to cancel the asynchronous operation.

#### Returns

Task<NpgsqlDataReader>

  A task representing the asynchronous operation.

#### Exceptions

DbException

  An error occurred while executing the batch.

ArgumentException

  The CommandBehavior value is invalid.

OperationCanceledException

  The cancellation token was canceled. This exception is stored into the returned task.

### ExecuteReaderAsync(CancellationToken)

An asynchronous version of System.Data.Common.DbBatch.ExecuteReader*, which executes the batch against its connection, returning a DbDataReader that can be used to access the results.

    public Task<NpgsqlDataReader> ExecuteReaderAsync(CancellationToken cancellationToken = default)

#### Parameters

`cancellationToken` CancellationToken

#### Returns

Task<NpgsqlDataReader>

  A task representing the asynchronous operation.

#### Exceptions

DbException

  An error occurred while executing the batch.

ArgumentException

  The CommandBehavior value is invalid.

OperationCanceledException

  The cancellation token was canceled. This exception is stored into the returned task.

### ExecuteScalar()

Executes the batch and returns the first column of the first row in the first returned result set. All other columns, rows and resultsets are ignored.

    public override object? ExecuteScalar()

#### Returns

object

  The first column of the first row in the first result set.

#### Exceptions

DbException

  An error occurred while executing the batch.

### ExecuteScalarAsync(CancellationToken)

An asynchronous version of ExecuteScalar(), which executes the batch and returns the first column of the first row in the first returned result set. All other columns, rows and result sets are ignored.

    public override Task<object?> ExecuteScalarAsync(CancellationToken cancellationToken = default)

#### Parameters

`cancellationToken` CancellationToken

  A token to cancel the asynchronous operation.

#### Returns

Task<object>

  The first column of the first row in the first result set.

#### Exceptions

DbException

  An error occurred while executing the batch.

OperationCanceledException

  The cancellation token was canceled. This exception is stored into the returned task.

### Prepare()

Creates a prepared (or compiled) version of the batch, or of each of its commands, on the data source.

    public override void Prepare()

### PrepareAsync(CancellationToken)

Asynchronously creates a prepared (or compiled) version of the batch, or of each of its commands, on the data source.

    public override Task PrepareAsync(CancellationToken cancellationToken = default)

#### Parameters

`cancellationToken` CancellationToken

  An optional token to cancel the asynchronous operation. The default value is None.

#### Returns

Task

  A Task representing the asynchronous operation.

#### Exceptions

OperationCanceledException

  The cancellation token was canceled. This exception is stored into the returned task.