Connection Class

Overview

The Connection class represents a client connection to a DuckDB database. It provides methods for executing queries, managing transactions, and creating prepared statements. Each connection maintains its own transaction context and can execute queries independently. Defined in: duckdb/main/connection.hpp (line 40)

class Connection {
public:
    explicit Connection(DuckDB &database);
    explicit Connection(DatabaseInstance &database);
    Connection(Connection &&other) noexcept;  // moveable
    ~Connection();
    
    shared_ptr<ClientContext> context;
};

Constructors

Database Constructor

Connection(DuckDB &database)

Creates a new connection to a DuckDB database.

database

DuckDB&

Reference to the database instance to connect to.

Example:

DuckDB db(nullptr);
Connection con(db);

DatabaseInstance Constructor

Connection(DatabaseInstance &database)

Creates a connection directly from a DatabaseInstance.

database

DatabaseInstance&

Reference to the database instance.

Move Constructor

Connection(Connection &&other) noexcept

Connections support move semantics but cannot be copied.

Connection con1(db);
Connection con2(std::move(con1));  // OK
// Connection con3(con2);  // Error: copy not allowed

Query Execution

Query

unique_ptr<MaterializedQueryResult> Query(const string &query)

Executes a query and materializes the complete result set in memory.

query

const string&

SQL query string to execute.

return

unique_ptr<MaterializedQueryResult>

Materialized query result containing the complete result set.

Example:

Connection con(db);
auto result = con.Query("SELECT * FROM users WHERE age > 25");

if (result->HasError()) {
    std::cerr << "Error: " << result->GetError() << std::endl;
} else {
    result->Print();
}

Query with Statement

unique_ptr<MaterializedQueryResult> Query(
    unique_ptr<SQLStatement> statement,
    QueryResultMemoryType memory_type = QueryResultMemoryType::IN_MEMORY
)

Executes a pre-parsed SQL statement.

statement

unique_ptr<SQLStatement>

Parsed SQL statement to execute.

memory_type

QueryResultMemoryType

default:"IN_MEMORY"

Memory type for storing the result.

SendQuery

unique_ptr<QueryResult> SendQuery(
    const string &query,
    QueryParameters query_parameters = QueryResultOutputType::ALLOW_STREAMING
)

Executes a query and returns either a streaming or materialized result.

query

const string&

SQL query string to execute.

query_parameters

QueryParameters

default:"ALLOW_STREAMING"

Parameters controlling result type (streaming vs materialized).

return

unique_ptr<QueryResult>

Query result (either StreamQueryResult or MaterializedQueryResult).

Example:

// Streaming result for large datasets
auto result = con.SendQuery("SELECT * FROM large_table");

while (auto chunk = result->Fetch()) {
    // Process chunk incrementally
    for (idx_t i = 0; i < chunk->size(); i++) {
        // Process row i
    }
}

Prepared Statements

Prepare

unique_ptr<PreparedStatement> Prepare(const string &query)

Prepares a SQL statement for repeated execution with different parameters.

query

const string&

SQL query with optional parameter placeholders (

1,

2, etc.).

return

unique_ptr<PreparedStatement>

Prepared statement object that can be executed multiple times.

Example:

Connection con(db);

// Prepare a statement
auto stmt = con.Prepare("INSERT INTO users VALUES ($1, $2)");

// Execute with different parameters
stmt->Execute("Alice", 30);
stmt->Execute("Bob", 25);
stmt->Execute("Charlie", 35);

Prepare with Statement

unique_ptr<PreparedStatement> Prepare(unique_ptr<SQLStatement> statement)

Prepares a pre-parsed SQL statement.

statement

unique_ptr<SQLStatement>

Parsed SQL statement to prepare.

Pending Query Execution

PendingQuery

unique_ptr<PendingQueryResult> PendingQuery(
    const string &query,
    QueryParameters query_parameters = QueryResultOutputType::FORCE_MATERIALIZED
)

Issues a query and returns a pending result that can be executed incrementally.

query

const string&

SQL query string to execute.

query_parameters

QueryParameters

default:"FORCE_MATERIALIZED"

Query execution parameters.

return

unique_ptr<PendingQueryResult>

Pending query result that can be executed step-by-step.

Example:

auto pending = con.PendingQuery("SELECT * FROM large_table");

while (!pending->IsFinished()) {
    pending->ExecuteTask();
    // Can check progress, interrupt, etc.
}

auto result = pending->Execute();

Transaction Management

BeginTransaction

void BeginTransaction()

Explicitly begins a new transaction.

Commit

void Commit()

Commits the current transaction.

Rollback

void Rollback()

Rolls back the current transaction.

Transaction Control

void SetAutoCommit(bool auto_commit)
bool IsAutoCommit()
bool HasActiveTransaction()

Example:

Connection con(db);

con.SetAutoCommit(false);
con.BeginTransaction();

try {
    con.Query("INSERT INTO accounts VALUES (1, 100)");
    con.Query("INSERT INTO accounts VALUES (2, 200)");
    con.Commit();
} catch (...) {
    con.Rollback();
    throw;
}

Relational API

Table

shared_ptr<Relation> Table(const string &table_name)
shared_ptr<Relation> Table(const string &schema_name, const string &table_name)
shared_ptr<Relation> Table(const string &catalog_name, const string &schema_name, const string &table_name)

Returns a relation that produces a table.

table_name

const string&

Name of the table.

schema_name

const string&

Schema name (optional).

catalog_name

const string&

Catalog name (optional).

Example:

auto users_table = con.Table("users");
auto filtered = users_table->Filter("age > 25")->Project("name, age");
auto result = filtered->Execute();

ReadCSV

shared_ptr<Relation> ReadCSV(const string &csv_file)
shared_ptr<Relation> ReadCSV(const string &csv_file, const vector<string> &columns)
shared_ptr<Relation> ReadCSV(const string &csv_input, named_parameter_map_t &&options)

Reads a CSV file and returns a relation. Example:

auto csv_data = con.ReadCSV("data.csv");
auto result = csv_data->Limit(10)->Execute();

ReadParquet

shared_ptr<Relation> ReadParquet(const string &parquet_file, bool binary_as_string)

Reads a Parquet file and returns a relation. Example:

auto parquet_data = con.ReadParquet("data.parquet", true);
parquet_data->Filter("year = 2024")->Execute()->Print();

Values

shared_ptr<Relation> Values(const vector<vector<Value>> &values)
shared_ptr<Relation> Values(const string &values)

Creates a relation from literal values. Example:

vector<vector<Value>> data = {
    {Value(1), Value("Alice")},
    {Value(2), Value("Bob")}
};
auto relation = con.Values(data);

Table Information

TableInfo

unique_ptr<TableDescription> TableInfo(const string &table_name)
unique_ptr<TableDescription> TableInfo(const string &schema_name, const string &table_name)
unique_ptr<TableDescription> TableInfo(const string &database_name, const string &schema_name, const string &table_name)

Retrieves table metadata including column names and types.

return

unique_ptr<TableDescription>

Table description object, or nullptr if table doesn’t exist.

Example:

auto table_info = con.TableInfo("users");
if (table_info) {
    for (auto &col : table_info->columns) {
        std::cout << col.name << ": " << col.type.ToString() << std::endl;
    }
}

Query Analysis

ExtractStatements

vector<unique_ptr<SQLStatement>> ExtractStatements(const string &query)

Parses a SQL string and extracts individual statements.

query

const string&

SQL query string potentially containing multiple statements.

return

vector<unique_ptr<SQLStatement>>

Vector of parsed SQL statements.

ExtractPlan

unique_ptr<LogicalOperator> ExtractPlan(const string &query)

Extracts the logical query plan for a given query.

Profiling and Debugging

EnableProfiling / DisableProfiling

void EnableProfiling()
void DisableProfiling()

Enables or disables query profiling.

GetProfilingInformation

string GetProfilingInformation(ProfilerPrintFormat format = ProfilerPrintFormat::QUERY_TREE)

Returns profiling information for the last executed query. Example:

con.EnableProfiling();
con.Query("SELECT * FROM large_table WHERE x > 100");
std::cout << con.GetProfilingInformation() << std::endl;

GetProfilingTree

optional_ptr<ProfilingNode> GetProfilingTree()

Returns the root node of the profiling tree for programmatic access.

Interrupt

void Interrupt()

Interrupts the currently executing query.

GetQueryProgress

double GetQueryProgress()

Returns the progress of the currently executing query (0.0 to 1.0).

Usage Examples

Basic Query Execution

#include "duckdb.hpp"

using namespace duckdb;

int main() {
    DuckDB db(nullptr);
    Connection con(db);
    
    con.Query("CREATE TABLE integers(i INTEGER)");
    con.Query("INSERT INTO integers VALUES (3)");
    auto result = con.Query("SELECT * FROM integers");
    result->Print();
}

Prepared Statements with Parameters

Connection con(db);
con.Query("CREATE TABLE users(name VARCHAR, age INTEGER)");

auto insert_stmt = con.Prepare("INSERT INTO users VALUES ($1, $2)");

vector<pair<string, int>> users = {
    {"Alice", 30},
    {"Bob", 25},
    {"Charlie", 35}
};

for (auto &[name, age] : users) {
    insert_stmt->Execute(name, age);
}

auto result = con.Query("SELECT * FROM users ORDER BY age");
result->Print();

Transaction Management

Connection con(db);
con.Query("CREATE TABLE accounts(id INTEGER, balance INTEGER)");

con.BeginTransaction();

try {
    con.Query("INSERT INTO accounts VALUES (1, 1000)");
    con.Query("UPDATE accounts SET balance = balance - 100 WHERE id = 1");
    con.Query("INSERT INTO accounts VALUES (2, 100)");
    
    con.Commit();
    std::cout << "Transaction committed" << std::endl;
} catch (const std::exception &e) {
    con.Rollback();
    std::cerr << "Transaction rolled back: " << e.what() << std::endl;
}

Reading CSV Files

Connection con(db);

auto csv_relation = con.ReadCSV("data.csv");
auto filtered = csv_relation->Filter("age > 25");
auto result = filtered->Execute();
result->Print();

C API

C++ API

Embedded Examples

Documentation Index

​Overview

​Constructors

​Database Constructor

​DatabaseInstance Constructor

​Move Constructor

​Query Execution

​Query

​Query with Statement

​SendQuery

​Prepared Statements

​Prepare

​Prepare with Statement

​Pending Query Execution

​PendingQuery

​Transaction Management

​BeginTransaction

​Commit

​Rollback

​Transaction Control

​Relational API

​Table

​ReadCSV

​ReadParquet

​Values

​Table Information

​TableInfo

​Query Analysis

​ExtractStatements

​ExtractPlan

​Profiling and Debugging

​EnableProfiling / DisableProfiling

​GetProfilingInformation

​GetProfilingTree

​Interrupt

​GetQueryProgress

​Usage Examples

​Basic Query Execution

​Prepared Statements with Parameters

​Transaction Management

​Reading CSV Files

​See Also

Overview

Constructors

Database Constructor

DatabaseInstance Constructor

Move Constructor

Query Execution

Query

Query with Statement

SendQuery

Prepared Statements

Prepare

Prepare with Statement

Pending Query Execution

PendingQuery

Transaction Management

BeginTransaction

Commit

Rollback

Transaction Control

Relational API

Table

ReadCSV

ReadParquet

Values

Table Information

TableInfo

Query Analysis

ExtractStatements

ExtractPlan

Profiling and Debugging

EnableProfiling / DisableProfiling

GetProfilingInformation

GetProfilingTree

Interrupt

GetQueryProgress

Usage Examples

Basic Query Execution

Prepared Statements with Parameters

Transaction Management

Reading CSV Files

See Also