d2sqlite3

D2SQLite3 provides a thin and convenient wrapper around the SQLite C API.

Features:

  • Use reference-counted structs (Database, Statement) instead of SQLite objects pointers.
  • Run multistatement SQL code with Database.run().
  • Use built-in integral types, floating point types, string, immutable(ubyte)[] and Nullable types directly: conversions to and from SQLite types is automatic and GC-safe.
  • Bind multiple values to a prepare statement with Statement.bindAll() or Statement.inject(). It's also possible to bind the fields of a struct automatically with Statement.inject().
  • Handle the results of a query as a range of Rows, and the columns of a row as a range of ColumnData (equivalent of a Variant fit for SQLite types).
  • Access the data in a result row directly, by index or by name, with the Row.peek!T() methods.
  • Make a struct out of the data of a row with Row.as!T().
  • Register D functions as SQLite callbacks, with Database.setUpdateHook() et al.
  • Create new SQLite functions, aggregates or collations out of D functions or delegate, with automatic type converions, with Database.createFunction() et al.
  • Store all the rows and columns resulting from a query at once with the cached function (sometimes useful even if not memory-friendly...).
  • Use an unlock notification when two or more connections access the same database in shared-cache mode, either using SQLite's dedicated API (sqlite_unlock_notify) or using an emulated equivalent.

Modules:

  • d2sqlite3.database: database connections and library global data.
  • d2sqlite3.statement: prepared statements creation and parameter binding.
  • d2sqlite3.results: query results.
  • d2sqlite3.sqlite3: autogenerated C API bindings.

Modules

database
module d2sqlite3.database

This module is part of d2sqlite3.

results
module d2sqlite3.results

This module is part of d2sqlite3.

sqlite3
module d2sqlite3.sqlite3
statement
module d2sqlite3.statement

This module is part of d2sqlite3.

Members

Functions

config
void config(int code, Args args)

Sets a configuration option.

initialize
void initialize()

Manually initializes (or shuts down) SQLite.

isCompiledWith
bool isCompiledWith(string option)

Tests if an SQLite compile option is set

shutdown
void shutdown()

Manually initializes (or shuts down) SQLite.

sourceID
string sourceID()

Gets the library's version string (e.g. "3.8.7"), version number (e.g. 3_008_007) or source ID.

threadSafe
bool threadSafe()

Tells whether SQLite was compiled with the thread-safe options.

versionNumber
int versionNumber()

Gets the library's version string (e.g. "3.8.7"), version number (e.g. 3_008_007) or source ID.

versionString
string versionString()

Gets the library's version string (e.g. "3.8.7"), version number (e.g. 3_008_007) or source ID.

Examples

1 // Note: exception handling is left aside for clarity.
2 import d2sqlite3;
3 import std.typecons : Nullable;
4 
5 // Open a database in memory.
6 auto db = Database(":memory:");
7 
8 // Create a table
9 db.run("DROP TABLE IF EXISTS person;
10         CREATE TABLE person (
11           id    INTEGER PRIMARY KEY,
12           name  TEXT NOT NULL,
13           score FLOAT
14         )");
15 
16 // Prepare an INSERT statement
17 Statement statement = db.prepare(
18     "INSERT INTO person (name, score)
19      VALUES (:name, :score)"
20 );
21 
22 // Bind values one by one (by parameter name or index)
23 statement.bind(":name", "John");
24 statement.bind(2, 77.5);
25 statement.execute();
26 statement.reset(); // Need to reset the statement after execution.
27 
28 // Bind muliple values at the same time
29 statement.bindAll("John", null);
30 statement.execute();
31 statement.reset();
32 
33 // Bind, execute and reset in one call
34 statement.inject("Clara", 88.1);
35 
36 // Count the changes
37 assert(db.totalChanges == 3);
38 
39 // Count the Johns in the table.
40 auto count = db.execute("SELECT count(*) FROM person WHERE name == 'John'")
41                .oneValue!long;
42 assert(count == 2);
43 
44 // Read the data from the table lazily
45 ResultRange results = db.execute("SELECT * FROM person");
46 foreach (Row row; results)
47 {
48     // Retrieve "id", which is the column at index 0, and contains an int,
49     // e.g. using the peek function (best performance).
50     auto id = row.peek!long(0);
51 
52     // Retrieve "name", e.g. using opIndex(string), which returns a ColumnData.
53     auto name = row["name"].as!string;
54 
55     // Retrieve "score", which is at index 2, e.g. using the peek function,
56     // using a Nullable type
57     auto score = row.peek!(Nullable!double)(2);
58     if (!score.isNull)
59     {
60         // ...
61     }
62 }

Meta

Authors

Nicolas Sicard (biozic) and other contributors at https://github.com/biozic/d2sqlite3