Class DuckDbStatement

A prepared statement from a DuckDB database.

Inheritance

object

DuckDbStatement

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Mallard

Assembly: Mallard.dll

Syntax

public class DuckDbStatement : IDisposable

Remarks

Objects of this class may not be accessed from multiple threads simultaneously. If that is attempted, exceptions will be thrown. Binding parameters to values obviously mutates state which would require callers to synchronize anyway. Furthermore, the underlying object in the DuckDB native library that implements execution of prepared statements is not thread-safe. To execute the same prepared statement (possibly with different parameters) from multiple threads, each thread must work with its own instance of this class.

The SQL statement(s) that have been prepared behind this object are immutable. Unlike the ADO.NET interface IDbCommand, you must obtain new instances of class to represent different SQL statement(s). Instances are obtained via PrepareStatement(string).

Properties

Parameters

The collection of formal parameters in this prepared statement.

Declaration

public DuckDbStatement.ParametersCollection Parameters { get; }

Property Value

Type	Description
DuckDbStatement.ParametersCollection

Methods

ClearBindings()

Clear all bindings of values to parameters in the prepared statement.

Declaration

public void ClearBindings()

Dispose()

Disposes this object along with resources allocated in the native DuckDB library for it.

Declaration

public void Dispose()

Execute()

Execute the prepared statement and return the results (of the query).

Declaration

public DuckDbResult Execute()

Returns

Type	Description
DuckDbResult	The results of the query execution.

Exceptions

Type	Condition
ObjectDisposedException	This statement has been disposed.
DuckDbException	The statement failed to execute due to unbound parameters, constraint violations, or other database errors.

ExecuteNonQuery()

Execute the prepared statement, and report only the number of rows changed.

Declaration

public long ExecuteNonQuery()

Returns

Type	Description
long	The number of rows changed by the execution of the statement. The result is -1 if the statement did not change any rows, or is otherwise a statement or query for which DuckDB does not report the number of rows changed.

Exceptions

Type	Condition
ObjectDisposedException	This statement has been disposed.
DuckDbException	The statement failed to execute due to unbound parameters, constraint violations, or other database errors.

ExecuteReader()

Execute the prepared statement and return the results via an ADO.NET data reader.

Declaration

public DuckDbDataReader ExecuteReader()

Returns

Type	Description
DuckDbDataReader	An ADO.NET-compatible data reader for accessing the query results.

Exceptions

Type	Condition
ObjectDisposedException	This statement has been disposed.
DuckDbException	The statement failed to execute due to unbound parameters, constraint violations, or other database errors.

ExecuteScalar()

Execute the prepared statement, and return the first item in the results.

Declaration

public object? ExecuteScalar()

Returns

Type	Description
object	The first row and cell of the results of the statement execution, if any. Null is returned if the statement does not produce any results. This method is typically for SQL statements that produce a single value.

Exceptions

Type	Condition
ObjectDisposedException	This statement has been disposed.
DuckDbException	The statement failed to execute due to unbound parameters, constraint violations, or other database errors.

ExecuteValue<T>()

Execute the prepared statement, and return the first item in the results.

Declaration

public T? ExecuteValue<T>()

Returns

Type

Description

T

The first row and cell of the results of the statement execution, if any. This method is typically for SQL statements that produce a single value. The default value for T is produced when the SQL execution does not produce any results, unless the default value can be confused with a valid value, specifically when T is a non-nullable value type. (This exception in behavior exists to avoid silently reading the wrong values.) If T is a reference type or nullable value type, the default value means "null".

Type Parameters

Name	Description
T

Exceptions

Type	Condition
ObjectDisposedException	This statement has been disposed.
DuckDbException	The statement failed to execute due to unbound parameters, constraint violations, or other database errors.
InvalidCastException	The first cell value cannot be converted to the type T.

~DuckDbStatement()

Destructor which will dispose this object if it has yet been already.

Declaration

protected ~DuckDbStatement()

Implements

IDisposable