Class NpgsqlBatch

Namespace

Npgsql

Assembly

Npgsql.dll

Represents a batch of commands which 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 which 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.

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.

ExecuteReader(CommandBehavior)

Executes the batch against its connection, returning a DbDataReader which 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 which 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.

ExecuteReaderAsync(CancellationToken)

An asynchronous version of System.Data.Common.DbBatch.ExecuteReader*, which executes the batch against its connection, returning a DbDataReader which 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.

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.

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.