Database API Reference

Elide ships three built-in database drivers, each exposed as a synthetic ESM module under the elide: scheme:

There is no Elide.db global and no Elide.db.connect(); each driver is its own module, imported by name. MongoDB and Redis are not supported, and there is no ORM or query builder — these modules execute SQL directly.

Each module is registered lazily via ModuleRegistry.deferred(...) and resolves only when imported; importing a module does not pollute the global scope.

elide:sqlite

SQLite is fully synchronous and embedded — there is no connection pool and no network. You construct a Database directly.

Source: dev.elide.lang.javascript.sqlite.JsSqliteModule:SqliteDatabaseConstructor, interface dev.elide.db.sqlite3.SqliteDatabase, statement interface dev.elide.db.sqlite3.SqliteStatement.

Constructor

new Database()                  // in-memory database
new Database(":memory:")        // in-memory database (explicit)
new Database("")                // in-memory database (empty string)
new Database("./data.db")       // file-backed database
new Database("./data.db", opts) // file-backed with options

The second argument is an options object (file-backed databases only):

If a path is given that does not exist and create is not true, the constructor throws FileNotFoundException.

Database methods

query and prepare both return a Statement. The difference is intent: query is for one-off execution, prepare for reuse. The statement is prepared eagerly when arguments are passed.

Statement methods

Rows are returned as objects keyed by column name.

Example

import { Database } from "elide:sqlite";

const db = new Database(); // in-memory

db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
db.exec("INSERT INTO users (name) VALUES (?)", "Ada");
db.exec("INSERT INTO users (name) VALUES (?)", "Linus");

const all = db.query("SELECT * FROM users").all();
// → [ { id: 1, name: "Ada" }, { id: 2, name: "Linus" } ]

const one = db.query("SELECT name FROM users WHERE id = ?", 1).get();
// → { name: "Ada" }

db.close();

Transactions wrap a function; the returned wrapper is invoked to run the function inside BEGIN / COMMIT (rolling back on a thrown error):

const insertAll = db.transaction((names) => {
  for (const name of names) db.exec("INSERT INTO users (name) VALUES (?)", name);
});
insertAll(["Grace", "Margaret"]);

elide:postgres and elide:mysql

PostgreSQL and MySQL share an identical JavaScript surface — only the import name, default port, and SQL dialect differ. Both connect over a pooled JDBC connection (HikariCP) and expose async methods that return Promises.

Sources: dev.elide.lang.javascript.postgresql.JsPostgresModule, dev.elide.lang.javascript.mysql.JsMysqlModule, dev.elide.db.postgresql.PostgresDatabase, dev.elide.db.mysql.MysqlDatabase, config dev.elide.db.jdbc.JdbcConnectionConfig.

Database.connect(config | url)

Database is a factory object with a single static method, connect, which returns a Promise resolving to a database instance. It accepts either a configuration object or a connection URL string.

await Database.connect({
  host: "localhost",      // optional, default "localhost"
  port: 5432,             // optional, default 5432 (postgres) / 3306 (mysql)
  database: "myapp",      // required
  user: "postgres",       // required
  password: "secret",     // required
  pool: { /* PoolConfig */ },
  ssl:  { /* SslConfig  */ },
  properties: { /* extra JDBC props */ },
});

// Or a URL:
await Database.connect("postgresql://postgres:secret@localhost:5432/myapp");
await Database.connect("mysql://root:secret@localhost:3306/myapp");

database, user, and password are required when passing a config object; omitting any throws a TypeError.

pool (optional)

ssl (optional)

Database instance

query returns synchronously a lazy result object; the SQL is not executed until you call one of its consuming methods:

ExecResult carries affectedRows (number), insertId (number | null), and insertIds (number[]).

Parameter placeholders

PostgreSQL uses positional $1, $2, … placeholders (these must be sequential, no gaps or repeats). MySQL uses ? placeholders. In both cases, bind values are passed as trailing arguments to query / exec.

Example (PostgreSQL)

import { Database } from "elide:postgres";

const db = await Database.connect({
  database: "myapp",
  user: "postgres",
  password: "secret",
});

// Read
const users = await db.query("SELECT * FROM users WHERE active = $1", true).all();

// Single row
const user = await db.query("SELECT * FROM users WHERE id = $1", 42).get();

// Write
const res = await db.exec("INSERT INTO users (name) VALUES ($1)", "Ada");
res.affectedRows; // → 1
res.insertId;     // → generated key (or null)

// Transaction
await db.transaction(async (tx) => {
  await tx.exec("UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, 1);
  await tx.exec("UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, 2);
});

await db.close();

Example (MySQL)

import { Database } from "elide:mysql";

const db = await Database.connect({
  database: "myapp",
  user: "root",
  password: "secret",
});

const rows = await db.query("SELECT * FROM users WHERE name = ?", "Ada").all();
await db.exec("INSERT INTO users (name) VALUES (?)", "Linus");
await db.close();

Prepared statements

const stmt = await db.prepare("INSERT INTO logs (msg) VALUES ($1)");
await stmt.exec("started");
await stmt.exec("stopped");
await stmt.close();

A prepared Statement exposes query(...args), exec(...args), executeBatch(argsList), and close().

Transactions

The callback passed to transaction receives a Transaction object. It is committed when the callback resolves and rolled back if it throws (or its returned Promise rejects). The transaction object exposes:

The default isolation level is READ_COMMITTED.

Notes

• SQLite is synchronous; PostgreSQL and MySQL are asynchronous (Promise-based).
• Connection pooling (PostgreSQL/MySQL) is provided by HikariCP and configured via the pool option.
• Plain JavaScript objects cannot be bound as SQL parameters — use primitives, strings, byte arrays, or arrays.

See also

• SQLite upstream: https://www.sqlite.org/docs.html
• PostgreSQL upstream: https://www.postgresql.org/docs/
• MySQL upstream: https://dev.mysql.com/doc/