Table of Contents

Connection String Parameters

To connect to a DuckDB database, a connection string should be specified. The connection string contains information about the target database and other parameters that control different aspects of the database behavior.

Basic connection

DuckDB.NET connection strings follow the standard ADO.NET syntax as a semicolon-separated list of keywords and values. The connection string must specify the database path to the database file with either DataSource or Data Source keyword. If the specified file does not exist, it will be created the first time the connection is opened.

In-Memory database

For an in-memory database use Data Source=:memory: connection string. When using an in-memory database no data is persisted on disk. Every in-memory connection results in a new, isolated database so tables created inside one in-memory connection aren't visible to another in-memory connection. If you want to create a shared in-memory database, you can use the Data Source=:memory:?cache=shared connection string. Both connection strings are exposed by the library as DuckDBConnectionStringBuilder.InMemoryDataSource and DuckDBConnectionStringBuilder.InMemorySharedDataSource respectively.

MotherDuck

To connect to MotherDuck:

using var duckDBConnection = new DuckDBConnection("DataSource=md:{your_database}?motherduck_token=ey...");

DuckDB configuration

DuckDB has many configuration options that change how it behaves. Add them to the connection string as keywords, and DuckDB.NET sets them when it opens the database. For example, DataSource=train_services.db;access_mode=READ_ONLY;threads=8 opens the database read-only and limits DuckDB to 8 threads.

  • A keyword that isn't a DuckDB configuration option throws an InvalidOperationException.
  • Some options can't be set when the database opens, and opening the connection fails with an error such as Error setting 'enable_progress_bar' to 'false'. Set these options with a SET statement after the connection is open.
  • An option that takes a list of values needs the value in DuckDB's list syntax, in double quotes because it contains single quotes: extension_directories="['/ext1', '/ext2']". DuckDBConnectionStringBuilder adds the double quotes when you set the value through its indexer.
  • allowed_directories and allowed_paths can't be set in the connection string at all, because of a DuckDB bug (duckdb/duckdb#25057). Set them with SET after the connection is open, for example SET allowed_directories = ['/data'];.

Typed properties

Starting with version 1.5.6, DuckDBConnectionStringBuilder has typed properties for 24 options that can be set when the database opens. Each property reads and writes the keyword in the table below. Set a property to null to leave its option out of the connection string, so that DuckDB's default applies.

var builder = new DuckDBConnectionStringBuilder
{
    DataSource = "train_services.db",
    AccessMode = DuckDBAccessMode.ReadOnly,
    Threads = 8,
    MemoryLimit = "10GB"
};

// An option without a typed property is set through the indexer.
builder["TimeZone"] = "UTC";

// DataSource=train_services.db;access_mode=read_only;threads=8;memory_limit=10GB;TimeZone=UTC
using var connection = new DuckDBConnection(builder.ConnectionString);
connection.Open();
Category Property Keyword Type
Data Source AccessMode access_mode DuckDBAccessMode
Resources Threads threads int
Resources ExternalThreads external_threads int
Resources MemoryLimit memory_limit string
Resources TempDirectory temp_directory string
Resources MaxTempDirectorySize max_temp_directory_size string
Storage CheckpointThreshold checkpoint_threshold string
Storage StorageCompatibilityVersion storage_compatibility_version string
Security EnableExternalAccess enable_external_access bool
Security AllowUnsignedExtensions allow_unsigned_extensions bool
Security AllowCommunityExtensions allow_community_extensions bool
Security AllowPersistentSecrets allow_persistent_secrets bool
Security SecretDirectory secret_directory string
Security LockConfiguration lock_configuration bool
Extensions AutoloadKnownExtensions autoload_known_extensions bool
Extensions AutoinstallKnownExtensions autoinstall_known_extensions bool
Extensions ExtensionDirectory extension_directory string
Extensions CustomExtensionRepository custom_extension_repository string
Query DefaultOrder default_order DuckDBSortOrder
Query DefaultNullOrder default_null_order DuckDBNullOrder
Query DefaultCollation default_collation string
Query PreserveInsertionOrder preserve_insertion_order bool
Client CustomUserAgent custom_user_agent string
Client ErrorsAsJson errors_as_json bool

Properties of type int and bool are nullable. Threads must be at least 1. Sizes such as MemoryLimit are strings in DuckDB's format, for example 10GB.

The builder stores both Data Source and DataSource as DataSource, so a connection string can't hold two different data sources.

Example connection strings

Connection String Description
DataSource = :memory: Connect to a new in-memory database
DataSource = :memory:?cache=shared Connect to a shared, in-memory database
DataSource = train_services.db Connect to train_services.db
DataSource = train_services.db;ACCESS_MODE=READ_ONLY Connect to train_services.db, make connection read-only
DataSource = :memory:;threads=8;ACCESS_MODE=READ_ONLY Connect to a new in-memory database, limit threads to 8, make connection read-only
DataSource = train_services.db;ACCESS_MODE=READ_ONLY;memory_limit=10GB Connect to train_services.db, make connection read-only, limit RAM usage to 10GB
Edit this page