Struct Database 

pub struct Database { /* private fields */ }

An in process database.

One catalog, held in memory, with no file behind it. ATTACH and the storage format are E2, and the shape of this type does not change when they arrive: a database with a file behind it is a catalog whose tables read from a block manager rather than from a Vec of chunks, which is a change under rudb_catalog::Table and not a change here.

A handle rather than the thing itself. Cloning one is cheap and gives another handle on the same database, and Database::connect gives a Connection, which is the same sharing with a name that says what it is for. The catalog is behind a lock, so every method here takes &self and a write from one thread is serialized against a read from another rather than refused by the compiler. That is what an embedded database has to do, because the program embedding it is the one that decided how many threads it has.

Implementations

impl Database

pub fn new() -> Self

An empty database with the default catalog and schema, held in memory.

pub fn with_config(config: Config) -> Self

An empty database held in memory, opened with these settings.

pub fn config(&self) -> Config

What this database is running with now.

By value rather than by reference, because SET changes it while the database is open and a reference into the settings would be a lock held for as long as the caller kept it. A Config is three numbers, so a copy costs nothing worth avoiding.

pub fn opened_with(&self) -> Config

What this database was opened with, which is what RESET puts a setting back to.

pub fn setting(&self, name: &str) -> Result<String>

One setting, by the name SET uses for it, in the spelling DuckDB prints.

The Rust side of reading a setting back. current_setting() is the SQL side and it is not written yet, because a scalar function over engine state is a shape no function in rudb has.

Errors

For a name that is not a setting, with the names there are.

pub fn memory(&self) -> &Memory

The memory budget every query against this database is held to.

One budget for the database rather than one per query, which is what Config::memory_limit means: two queries running at once share the limit rather than getting one each. Public because rudb_common::Memory::used is the only way to see what is being held, and a program that sets a limit wants to know how close it is.

pub fn open(path: &str) -> Result<Self>

Opens a database by name.

:memory: and the empty string are an in memory database, which are DuckDB’s two spellings of it. Anything else names a file, and a file needs a storage format, which is #103. It is an error here rather than a silent in memory database, because a program that opened a file and wrote to it would be told nothing until it looked for its data again.

Errors

When the name is a file.

pub fn open_with(path: &str, config: Config) -> Result<Self>

Opens a database by name, with these settings.

Errors

When the name is a file.

pub fn connect(&self) -> Connection

A connection to this database.

pub fn prepare(&self, sql: &str) -> Result<Prepared>

Parses a statement so it can be run more than once, with values for its parameters.

The same call as Connection::prepare.

Errors

A parse error. A name that does not resolve or a type that does not work out is an error at execution rather than here, because a parameter has no type until it has a value.

pub fn with_catalog<T>(&self, read: impl FnOnce(&Catalog) -> T) -> T

Reads the catalog.

A closure rather than a returned reference, because the catalog is behind a lock and a reference out of it would outlive the guard. The lock is held for the call and no longer.

pub fn with_catalog_mut<T>(&self, write: impl FnOnce(&mut Catalog) -> T) -> T

Writes the catalog.

Public because a program that builds its own catalog rather than parsing SQL to build one is a real thing an embedded database gets used for.

pub fn create_table(&self, name: &str, columns: Vec<Field>) -> Result<()>

Defines a table.

The name is table, schema.table or catalog.schema.table, and anything unqualified goes to the default catalog and schema, which is what an unqualified name in a query resolves against too.

Errors

If the name has more than three parts, if the catalog or the schema does not exist, if the table already exists, or if two of the columns have the same name.

pub fn drop_table(&self, name: &str) -> Result<()>

Drops a table.

Errors

If the name does not resolve or the table does not exist.

pub fn append(&self, name: &str, rows: &[Vec<Value>]) -> Result<()>

Appends rows to a table, each row left to right in the table’s column order.

The row shaped write path, because the caller with rows in hand is the common case and the caller with columns in hand can reach Database::with_catalog_mut and append a rudb_vector::Chunk directly. Values are converted to the column’s type on the way in, so an Integer lands in a BIGINT column.

Errors

If the name does not resolve, if a row is not as wide as the table, or if a value cannot be converted to its column’s type.

pub fn table_len(&self, name: &str) -> Result<usize>

How many rows a table holds.

Errors

If the name does not resolve or the table does not exist.

pub fn table_names(&self) -> Vec<String>

Every table in the database, unqualified, in creation order.

Unqualified because that is what a person typing .tables wants to read and what they would then type into a query. Two tables of the same name in different schemas both appear, which is the same thing DuckDB’s .tables does.

pub fn table_sql(&self, name: &str) -> Result<String>

The CREATE TABLE that would define a table as it stands.

Built from the catalog rather than remembered from the statement that made it, so a table defined by Database::create_table describes itself as well as one defined by SQL. It carries the column names, the types and NOT NULL, and nothing else, because nothing else is in the catalog yet. Defaults, primary keys and check constraints appear here the day the catalog holds them.

Errors

If the name does not resolve or the table does not exist.

pub fn query(&self, sql: &str) -> Result<QueryResult>

Runs one query and returns every row it produced.

The same call as Connection::query, for a program that has one database and no reason to name a connection.

The query timeout in Database::config applies, and nothing can interrupt it, because an interrupt needs somebody holding the other end of a token and a bare database hands out no token. Connection::interrupt is that other end.

Errors

A parse error, a binder error, or anything the operators raise while running, which is mostly cast failures and arithmetic that leaves the range of its type.

pub fn execute(&self, sql: &str) -> Result<QueryResult>

Runs one statement, which may change the database.

Errors

A parse error, a binder error, a catalog error, or anything the operators raise.

pub fn plan(&self, sql: &str) -> Result<String>

The plan for a query, in the textual form spec/07-execution.md describes, without running it.

This is EXPLAIN before there is an EXPLAIN, and it is what the plan tests and the optimizer work read. The text round trips: rudb_plan::Plan::parse of this string gives back the plan it was printed from.

Errors

A parse error or a binder error.

pub fn value(&self, sql: &str) -> Result<Value>

Runs a query and returns the single value it produced.

A convenience for SELECT count(*) FROM t and the rest of the one cell queries, which are most of what a program embedded in something else asks.

Errors

Everything Database::query can raise, plus an error if the result is not one row of one column.

Trait Implementations

impl Clone for Database

fn clone(&self) -> Database

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Database

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Database

fn default() -> Self

Returns the “default value” for a type.