src/database

To use NimDrake, you must first initialize a Database obj using newDatabase. newDatabase takes as parameter the database file to read and write from, or it can be used to create an in-memory database if no parameters is provided. Note that for an in-memory database no data is persisted to disk (i.e., all data is lost when you exit the process). With the Database obj, you can create one or many Connection using db.connect(). While individual connections are thread-safe, they will be locked during querying. It is therefore recommended that each thread uses its own connection to allow for the best parallel performance.

Types

Connection = object
  handle*: duckdb_connection
Database = object of RootObj
  handle*: duckdb_database

Procs

proc `=copy`(dest: var Connection; source: Connection) {.
    error: "Connection copy is not supported".}
proc `=copy`(dest: var Database; source: Database) {.
    error: "Database copy is not supported".}
proc `=destroy`(con: Connection) {....raises: [], tags: [], forbids: [].}
proc `=destroy`(db: Database) {....raises: [], tags: [], forbids: [].}
proc `=sink`(dest: var Connection; source: Connection) {....raises: [], tags: [],
    forbids: [].}
proc `=sink`(dest: var Database; source: Database) {....raises: [], tags: [],
    forbids: [].}
proc connect(db: Database): Connection {....raises: [OperationError], tags: [],
    forbids: [].}
Create one or many Connections from a single Database. While individual connections are thread-safe, they will be locked during querying

Example:

import nimdrake

let db = newDatabase()
let conn = db.connect()
let conn2 = db.connect()

conn.execute("CREATE TABLE combined(i INTEGER, j VARCHAR);")
conn.execute(
  "INSERT INTO combined VALUES (6, 'foo'), (5, 'bar'), (?, ?);", ("7", "baz")
)
let outcome = conn2.execute("SELECT * FROM combined").fetchall()
assert outcome[0].valueInteger == @[6'i32, 5'i32, 7'i32]
proc interrupt(con: Connection) {....raises: [], tags: [], forbids: [].}
proc newDatabase(): Database {....raises: [OperationError], tags: [], forbids: [].}
Create a new in-memory database.

Example:

import nimdrake

let db = newDatabase()
proc newDatabase(config: Config): Database {....raises: [OperationError], tags: [],
    forbids: [].}
Create a new in-memory database preconfigured.

Example:

import std/tables
import nimdrake

let conf = newConfig({"threads": "3"}.toTable)
let db = newDatabase(conf)
proc newDatabase(path: string): Database {....raises: [OperationError], tags: [],
    forbids: [].}
Creates a new database or opens an existing database file stored at the given path.

Example:

import nimdrake

let db = newDatabase("duckdb.db")
proc newDatabase(path: string; config: Config): Database {.
    ...raises: [OperationError], tags: [], forbids: [].}
Creates a new preconfigured database or opens an existing database file stored at the given path.

Example:

import std/tables
import nimdrake

let
  conf = newConfig({"threads": "3"}.toTable)
  db = newDatabase("duckdb.db", conf)
  conn = db.connect()

let outcome = conn.execute("SELECT * FROM range(3);").fetchall()

assert outcome[0].valueBigInt == @[0'i64, 1'i64, 2'i64]
proc queryProgress(con: Connection): QueryProgress {....raises: [], tags: [],
    forbids: [].}