#moondb

Moved on mooncakes from Lfan-ke/moondb to moonbitstack/moondb.

flowchart TD
    subgraph layers["query layers — build on moondb"]
      ORM["moonorm<br/><small>SQLAlchemy-style ORM / query builder</small>"]
      APP["your app / repository code"]
    end
    IFACE(["<b>@moondb</b><br/><small>Value · Row · ExecResult · DbError · Driver</small>"])
    subgraph drivers["drivers — implement moondb"]
      SQLITE["moonsqlite<br/><small>C-FFI, native</small>"]
      PG["moonpostgres<br/><small>pure-MoonBit wire</small>"]
      MYSQL["moonmysql<br/><small>pure-MoonBit wire</small>"]
      MOCK["MockDriver<br/><small>in-memory, ships here</small>"]
    end
    APP --> ORM --> IFACE
    IFACE --> SQLITE
    IFACE --> PG
    IFACE --> MYSQL
    IFACE --> MOCK

#Install

moon add moonbitstack/moondb

#The interface at a glance

#The binding contract

#Quickstart

test "round-trip through the interface" {
  // A query layer is written against the `Driver` trait, not a concrete backend.
  let db = @moondb.MockDriver::new()

  // Bind values as parameters — never string-interpolated into the SQL.
  db.execute("INSERT INTO hero (id, name) VALUES (?, ?)", [Int(1), Text("Nova")])
  |> ignore

  db.begin()
  db.execute("INSERT INTO hero (id, name) VALUES (?, ?)", [Int(2), Text("Iris")])
  |> ignore
  db.rollback() // Iris is undone; Nova remains.

  let rows = db.query("SELECT id, name FROM hero", [])
  assert_eq(rows.length(), 1)
  assert_eq(rows[0].int_by("c0"), 1)
  assert_eq(rows[0].text_by("c1"), "Nova")
}

#Your own types

test "read a nullable column as an option" {
  let row : @moondb.Row = { columns: ["id", "age"], values: [Int(1), Null] }
  let id : Int64 = row.read(0)
  let age : Int? = row.read_by("age")
  assert_eq((id, age), (1L, None))
}

struct Email(String)

impl @moondb.ToValue for Email with fn to_value(self) {
  let Email(s) = self
  Text(s)
}

impl @moondb.FromValue for Email with fn from_value(v) {
  match v {
    Text(s) if s.contains("@") => Email(s)
    other => raise TypeError(other.kind() + ", not Email")
  }
}

#Implementing a driver

pub impl @moondb.Driver for MyConn with execute(self, sql, params) {
  // ... bind `params` positionally, run `sql`, then:
  { rows_affected: n, last_insert_id: id }
}
// query / begin / commit / rollback / close likewise.

#Design notes

• Why raise, not Result. Typed accessors and driver calls raise DbError rather than returning Result[_, DbError], so a decode bug or a dropped connection surfaces at the call site instead of being silently swallowed. A caller opts into recovery with try/catch.
• Typed accessors are strict. row.int(i) raises TypeError if the cell is not an integer — including when it is NULL. Read a nullable column as T? with read, or guard it with is_null first. Integer→integer and integer→double conversions are allowed and lossless; int narrows an Int64 and says so.
• DbError is pub(all). A plain pub suberror can be caught from another package but not constructed — which would stop out-of-tree drivers from raising it. pub(all) opens the constructors.
• There are two driver traits, on purpose. Driver is synchronous, which is right for a backend whose calls block in C (moonsqlite steps a prepared statement and returns). A backend reached over TCP cannot be written that way: MoonBit's only socket stack is async-only, and an async fn cannot be called from a synchronous one. A wire driver forced to conform to Driver can do nothing but raise from every method — and because ping is a defaulted method built on query, it swallows that raise into false, so a Pool with pre_ping judges every one of its connections permanently unhealthy. AsyncDriver is the seam for those backends: the same eight operations, each awaited. It is a peer of Driver, not a replacement — a synchronous backend keeps implementing Driver and never becomes async. Declaring async methods pulls in no async runtime, so moondb stays dependency-free and still compiles on every backend; only a driver that implements the trait, and a caller that runs it in an event loop, need one.

• The pool is synchronous, and its counting is moonpool's. @pool.Pool[D] reuses idle connections under a size ceiling, evicts a connection that fails its pre_ping probe or outlives max_lifetime (age measured by an injected clock, the way database/sql swaps nowFunc in tests), and offers a non-blocking try_acquire. Because moondb's base contract is sync and the pure backends have no threads, an exhausted acquire fails immediately rather than blocking — the acquire_timeout is the budget an async driver layers real waiting on top of. ping is a default Driver method (SELECT 1), so every driver gets a health probe for free. The bookkeeping underneath — how many are live, which are idle, when each was born — is moonpool's Pool, and so is the optional ward in front of the database: a backoff after failed connects (acquire then raises ConnectError until the delay has passed), a token bucket spacing reconnections, a breaker that stops connecting to a failing backend, a shedder. This package adds only opening, closing and probing. It is a separate package because that dependency is the pool's alone: import { "moonbitstack/moondb/pool" } where a pool is wanted, and the interface stays dependency-free where it is not.

#Roadmap

• Prepared statements — a Stmt handle for repeated execution with rebinding.
• Streaming rows — a Rows cursor so large result sets need not fully materialise.
• A temporal Value case — dates/times currently ride as ISO-8601 Text; a dedicated case (with a decided epoch/precision) will follow.
• Named parameters and nested transactions (savepoints) as a layer over the flat begin/commit/rollback.

#Tests

moon test --target all

#License