Class DuckDbConnection

A connection to a DuckDB database.

Inheritance

object

DuckDbConnection

Implements

IDbConnection

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Mallard

Assembly: Mallard.dll

Syntax

public sealed class DuckDbConnection : IDbConnection, IDisposable

Remarks

Mallard provides a high-performance API to access DuckDB through this class and related types with the DuckDb prefix. Alternatively, the standard ADO.NET API may be used which this class also implements.

This class represents a connection to some DuckDB database. Each connection is generally used only by at most one thread at once, although it may be passed between different threads without issue.

This class is thread-safe in the sense that no memory or state corruption will occur if an instance is used from multiple threads. There are checks to prevent conflicting operations, such as disposing an instance while it is being used by another thread. However, key operations such as making queries will be serialized (with locks internally in DuckDB) if made from multiple threads.

For true concurrent usage, make multiple connections to the same database. DuckDB will mediate between the connections by its optimistic multi-version concurrency control (MVCC).

There is no asynchronous interface, because DuckDB does not natively offer one. As an embedded database, most of wait time for SQL execution is (or is assumed to be) CPU-bound for the local computer, not network-bound like traditional database servers. This class does not attempt to emulate asynchonicity since both the design and implementation of the necessary API is non-trivial. An asynchronous interface could be built on top of this class instead.

Constructors

DuckDbConnection(string, IEnumerable<KeyValuePair<string, string>>?)

Open a connection to a database from DuckDB.

Declaration

public DuckDbConnection(string path, IEnumerable<KeyValuePair<string, string>>? options = null)

Parameters

Type	Name	Description
string	path	Specifies the location of the database as a path in DuckDB syntax.
IEnumerable<KeyValuePair<string, string>>	options	Options for opening the database, as a sequence of key-value pairs. (All options in DuckDB are in string format.)

Exceptions

Type	Condition
DuckDbException	Failed to open or connect to the database due to an invalid path, invalid configuration options, or other database-related error.

Properties

NativeLibraryVersion

The version of the native DuckDB library being used.

Declaration

public static string NativeLibraryVersion { get; }

Property Value

Type	Description
string	The string representation of the DuckDB version. For official releases, it will be in SemVer format: Major.Minor.Patch.

OriginalNativeLibraryVersion

The version of the native DuckDB library that Mallard has been built against.

Declaration

public static string OriginalNativeLibraryVersion { get; }

Property Value

Type	Description
string	The string representation of the DuckDB version. For official releases, it will be in SemVer format: Major.Minor.Patch.

Remarks

In contrast to NativeLibraryVersion, this property is available even when the native library has not been loaded yet. The reported version may be used to locate the DuckDB library to load (if the installation allows multiple versions of the library), and to check when an actual version of the library is API/ABI-compatible with what this version of Mallard was built against.

Methods

BeginTransaction()

Begin a transaction on the current connection.

Declaration

public DuckDbTransaction BeginTransaction()

Returns

Type	Description
DuckDbTransaction	A "holder" object that is used to either commit the transaction or to roll it back. In C#, wrap it in a using block or statement.

Exceptions

Type	Condition
ObjectDisposedException	This connection has been disposed.
InvalidOperationException	There is already an existing transaction for this connection.
DuckDbException	A database-level error occurred in starting the transaction.

Dispose()

Disposes (closes) this database connection.

Declaration

public void Dispose()

Remarks

Native resources for the DuckDB connection will be released.

This method does nothing if the connection is already disposed (closed).

Exceptions

Type	Condition
InvalidOperationException	Another thread is using this connection, e.g. a query is still running on this connection. The connection may not be disposed concurrently.

Duplicate()

Open a new connection to the same database.

Declaration

public DuckDbConnection Duplicate()

Returns

Type	Description
DuckDbConnection	A new connection to the same database.

Remarks

This method creates a new connection to the same database that this instance is connected to. The new connection allows queries and statements to be submitted to the same database, in parallel, from a different thread. (If multiple threads attempt to execute statements on the same connection, execution will be serialized by locks inside DuckDB.)

Exceptions

Type	Condition
ObjectDisposedException	This connection has been disposed.
DuckDbException	Failed to open or connect to the database due to an invalid path, invalid configuration options, or other database-related error.

Execute(string)

Execute a SQL statement and return the results (of the query).

Declaration

public DuckDbResult Execute(string sql)

Parameters

Type	Name	Description
string	sql	SQL statement(s) in the DuckDB dialect. Multiple statements may be separated/terminated by semicolons; the results returned are always from the last statement.

Returns

Type	Description
DuckDbResult	The results of the query execution.

Exceptions

Type	Condition
ObjectDisposedException	This connection has been disposed.
DuckDbException	The SQL statement failed to execute due to a syntax error, constraint violation, or other database error.

ExecuteNonQuery(string)

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

Declaration

public long ExecuteNonQuery(string sql)

Parameters

Type	Name	Description
string	sql	SQL statement(s) in the DuckDB dialect. Multiple statements may be separated/terminated by semicolons. The number of rows changed is always from the last statement.

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 connection has been disposed.
DuckDbException	The SQL statement failed to execute due to a syntax error, constraint violation, or other database error.

ExecuteScalar(string)

Execute a SQL query, and return the first item in the results.

Declaration

public object? ExecuteScalar(string sql)

Parameters

Type	Name	Description
string	sql	SQL statement(s) in the DuckDB dialect. Multiple statements may be separated/terminated by semicolons; the result returned is always from the last statement.

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 connection has been disposed.
DuckDbException	The SQL statement failed to execute due to a syntax error, constraint violation, or other database error.

ExecuteValue<T>(string)

Execute a SQL query, and return the first item in the results.

Declaration

public T? ExecuteValue<T>(string sql)

Parameters

Type	Name	Description
string	sql	SQL statement(s) in the DuckDB dialect. Multiple statements may be separated/terminated by semicolons; the result returned is always from the last statement.

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 T is a non-nullable value type. (The special case in behavior exists because the default value of a non-nullable value type, such as int, may be a valid value, which needs to be distinguished from a missing value.) If T is a reference type or nullable value type, the default value means "null".

Type Parameters

Name	Description
T	The .NET type to convert the result (first item) from the SQL query to.

Exceptions

Type	Condition
ObjectDisposedException	This connection has been disposed.
DuckDbException	The SQL statement failed to execute due to a syntax error, constraint violation, or other database error.
InvalidCastException	The first cell value cannot be converted to the type T.

~DuckDbConnection()

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

Declaration

protected ~DuckDbConnection()

Interrupt()

Interrupt a query or statement, running in another thread, if any.

Declaration

public void Interrupt()

Remarks

If multiple queries are queued up (by multiple threads calling methods like Execute(string)), only the first one is cancelled.

PrepareStatement(string)

Create a prepared statement for (parameterized) execution.

Declaration

public DuckDbStatement PrepareStatement(string sql)

Parameters

Type	Name	Description
string	sql	SQL statement(s) in the DuckDB dialect that may have formal parameters. Multiple statements may be separated/terminated by semicolons.

Returns

Type	Description
DuckDbStatement	Object that holds the prepared statement from DuckDB.

Exceptions

Type	Condition
ObjectDisposedException	This connection has been disposed.
DuckDbException	The SQL statement failed to prepare due to a syntax error or other database error.

Implements

IDbConnection

IDisposable