arsd.database

Generic interface for RDBMS access. Use with one of the implementations in arsd.mysql, arsd.sqlite, arsd.postgres, or arsd.mssql. I'm sorry the docs are not good, but a little bit goes a long way:

	auto db = new Sqlite("file.db"); // see the implementations for constructors
	// then the interface, for any impl can be as simple as:

	foreach(row; db.query("SELECT id, name FROM people")) {
             string id = row[0];
	     string name = row[1];
	}

	db.query("INSERT INTO people (id, name) VALUES (?, ?)", 5, "Adam");

To convert to other types, just use std.conv.to since everything comes out of this as simple strings with the exception of binary data, which you'll want to cast to const(ubyte)[].

Public Imports

std.variant public import std.variant;: Undocumented in source.

std.datetime public import std.datetime;: Undocumented in source.

Members

Classes

ConnectionPool class ConnectionPool(alias connectionFactory): A ConnectionPool manages a set of shared connections to a database.
DataUsageException class DataUsageException: Thrown when you use result data incorrectly. These almost always are preventable, but may be the result of a schema change and a select * query too.
DatabaseConnectionException class DatabaseConnectionException: Thrown when something is wrong with your connection to the database server.
DatabaseException class DatabaseException: Parent class of various forms of errors you can get when using the database.d library. It may be thrown generically when other details are not provided by a driver.
InsertBuilder class InsertBuilder: Undocumented in source.
PredefinedResultSet class PredefinedResultSet: Unittest utility that returns a predefined set of values
QueryResultRow class QueryResultRow(alias queryMetadata): Undocumented in source.
SelectBuilder class SelectBuilder: WARNING: this is as susceptible to SQL injections as you would be writing it out by hand
SimpleDataObject class SimpleDataObject(string tableToUse, fieldsToUse): This creates an editable data object out of a simple struct.
SqlException class SqlException: Thrown when your sql query has reached the database server, but failed to run there for some reason.

Functions

DataObjectField string DataObjectField(): You can subclass DataObject if you want to get some compile time checks or better types.
VALUES auto VALUES(): Helpers for interpolated queries.
escapedVariants string escapedVariants(Database db, string sql, Variant[] t): Note: ?n params are zero based!
resultSetToHtmlTable auto resultSetToHtmlTable(ResultSet resultSet): Converts a database result set to a html table, using arsd.dom.
sql auto sql(): Helpers for interpolated queries.

Mixin templates

DatabaseRestObject mixintemplate DatabaseRestObject(alias getDb): Easy interop with arsd.cgi serveRestObject classes.

Structs

DatabaseDatum struct DatabaseDatum: Represents a single item in a result. A row is a set of these DatabaseDatums.
PooledConnection struct PooledConnection(ConnectionPoolType): PooledConnection is an RAII holder for a database connection that is automatically recycled to the pool it came from (unless you discard it).
Row struct Row: A row in a result set from a query.
StructFromCreateTable struct StructFromCreateTable(string sql, string tableName): Given some SQL, it finds the CREATE TABLE instruction for the given tableName. (this is so it can find one entry from a file with several SQL commands. But it may break on a complex file, so try to only feed it simple sql files.)

Templates

DataObjectFromSqlCreateTable template DataObjectFromSqlCreateTable(string sql, string tableName): Combines StructFromCreateTable and SimpleDataObject into a one-stop template. alias DataObjectFromSqlCreateTable(import("file.sql"), "my_table") MyTable;

Meta

On August 2, 2022, the behavior of BLOB (or BYTEA in postgres) changed significantly. Before, it would convert to strings with to!string(bytes) on insert and platform specific on query. It didn't really work at all.

It now actually stores ubyte[] as a blob and retrieves it without modification. Note you need to cast it.

This is potentially breaking, but since it didn't work much before I doubt anyone was using it successfully but this might be a problem. I advise you to retest.

Be aware I don't like this string interface much anymore and want to change it significantly but idk how to work it in without breaking a decade of code.

On June 7, 2023 (dub 11.0), I started the process of moving away from strings as the inner storage unit. This is a potentially breaking change, but you can use .toString to convert as needed and alias this will try to do this automatically in many situations. See DatabaseDatum for details. This transition is not yet complete.

Notably, passing it to some std.string functions will cause errors referencing DatabaseDatum like:

Error: template std.array.replace cannot deduce function from argument types !()(string, string, DatabaseDatum)
path/phobos/std/array.d(2459):        Candidates are: replace(E, R1, R2)(E[] subject, R1 from, R2 to)
  with `E = immutable(char),
       R1 = string,
       R2 = DatabaseDatum`

Because templates do not trigger alias this - you will need to call .toString() yourself at the usage site.