database

README

arandu-io/database

Dialect registry, pool policy and Open for Arandu's SQL connections.

About

database is the part of Arandu that opens a SQL connection: a dialect registry, the pool policy, and Open. It carries no query contract of its own — Repository, data.DB, Dialect and Transaction live in the framework, because that is where a Grant is mandatory on every call. What lives here is everything that needs a driver, and nothing that does not: resolving which driver a binary has linked in, tuning the pool for it, and connecting once at boot instead of deferring the failure to a visitor's first request.

Moving into hesape

This repository is the previous address. Its content — the registry, the pool policy, Open, and the three driver compartments — now lives inside arandu-io/hesape, at hesape/database, with the drivers under hesape/database/connectors/{pgx,mysql,sqlite}. See ADR-0048 for the reasoning: hesape collects the framework's components in one place, and a developer looking for the SQL connection code finds it inside that collection instead of needing to know it lives in a repository of its own.

This module is not being deleted. It stays published, and the Go module proxy keeps serving every version already tagged. New work happens in hesape; this address is for whatever already depends on it.

What it delivers

Zero third-party dependency in the root module. Each driver is its own module with its own go.mod, because Go has no optional dependency — a project on SQLite should not pull pgx into its build, its binary, or its vulnerability surface:

driver	module	dependency
PostgreSQL	database/pgx	jackc/pgx/v5 v5.10.0
SQLite	database/sqlite	modernc.org/sqlite v1.55.0
MySQL	database/mysql	go-sql-driver/mysql v1.9.3

The pool policy is not left to each project's main. Open connects once at boot, with a 5-second connect timeout — a database that cannot be reached fails the deploy instead of the first request that hits it. On PostgreSQL and MySQL the pool holds up to 25 open connections, 5 idle, with a one-hour connection lifetime; on SQLite it holds exactly one, because SQLite serializes writes regardless, and a bigger pool only turns the wait into "database is locked."

Conformance against a real server is mandatory, not optional. Every driver runs the same suite in database/conformance/ against a live instance of its engine — a claim that only holds against a fake proves nothing about the case that matters. A query the generator writes is a query proven portable across all three engines, or it is not written.

564 lines of production code, 638 of test, across 5 test files.

Installation

go get github.com/arandu-io/hesape/database
go get github.com/arandu-io/hesape/database/connectors/pgx   # or /mysql, /sqlite

This module's own path, github.com/arandu-io/database, still resolves for anything already pinned to it.

Related repositories

• arandu-io/hesape — where this adapter lives now.
• arandu-io/framework — the core this package wraps: Repository, data.DB, Dialect, Transaction.
• arandu-io/kv, arandu-io/queue, arandu-io/storage — the other adapters making the same move.

Learning Arandu

The API reference is generated from the doc comments and lives on pkg.go.dev. Every exported symbol carries one, and that is deliberate: it is the documentation that cannot drift from the code, because it sits in the same file.

The CLI documents itself. aru help lists every command, and each one explains what it writes and what to do with it. aru doctor explains what it found and what breaks, not which rule was violated.

A guide and a website do not exist yet, and that is a decision rather than a gap: a guide written against an API that still moves is work done twice, and the second time is worse — there is wrong documentation published. The site is the next phase, and it will be an Arandu application.

Contributing

See CONTRIBUTING.md. Before opening a pull request, the three commands at the top of that file have to pass, and CI runs exactly them.

Security Vulnerabilities

Please review our security policy on how to report a vulnerability. Never open a public issue for one.

License

Open-sourced software licensed under the MIT license.

Documentation

Overview

Package database opens the connection: one Open, one pool policy, and each driver in its own module.

What is shared, and where it lives

The contract stays in the core. framework/data owns Repository, Query, DB, Dialect, Transaction and Migration, because that is where the Grant is mandatory -- the reason a handler cannot reach the database without passing a Policy. Moving it here would move the thesis of the product into an optional package, and an optional guarantee is not one.

What lives here is everything that needs a driver, and only that. This module imports the core; the core does not import this one. One direction, one contract, no duplication.

Why the drivers are separate modules

In Go there is no optional dependency. A single module carrying pgx, MySQL and SQLite would put all three in the go.sum of every project -- in the build, in the binary, and in the vulnerability surface. That is not hypothetical: the skeleton carried pgx and modernc/sqlite together, and govulncheck found a pgx advisory in a project that could have been SQLite-only.

So each driver is its own module with its own go.mod:

go get github.com/arandu-io/database/sqlite   // needs nothing installed
go get github.com/arandu-io/database/pgx      // Postgres
go get github.com/arandu-io/database/mysql    // MySQL

and the project blank-imports the ones it uses:

import (
    "github.com/arandu-io/database"
    _ "github.com/arandu-io/database/pgx"
    _ "github.com/arandu-io/database/sqlite"
)

db, closeDB, err := database.Open(cfg.Database)

Switching engines is a line in .env. The import list is what decides which engines a build can speak at all.

Index

• func DriverName(d data.Dialect) (string, error)
• func Open(cfg hdatabase.Config) (*data.DB, func(), error)
• func Register(d data.Dialect, driverName string)
• func Registered() []data.Dialect

Functions

func DriverName

func DriverName(d data.Dialect) (string, error)

DriverName returns the database/sql driver a compartment registered for a dialect, or the error that names the missing import.

It exists for the conformance suite, which has to open a connection with the same driver Open would use rather than a name it hardcoded -- a suite testing a driver nobody links is a suite testing nothing.

func Open

func Open(cfg hdatabase.Config) (*data.DB, func(), error)

Open connects, tunes the pool, and returns the instrumented handle plus the function that closes it.

The pool policy lives here rather than in each project's main, because it is not a preference: the defaults of database/sql are an unbounded pool, which turns one traffic spike into "too many connections" on the server instead of a queue in the process.

func Register

func Register(d data.Dialect, driverName string)

Register records that a driver for this dialect is linked into the binary.

Driver compartments call it from init(). It is not meant for application code: a project that registers its own driver name is a project that will get a different pool policy than every other, for no gain.

Registering the same dialect twice panics rather than picking one. Two drivers for one dialect is an import nobody meant to add, and finding out at boot is better than finding out from a query that behaves differently.

func Registered

func Registered() []data.Dialect

Registered reports the dialects this binary can speak, sorted.

`aru doctor` reads it, and so does the error below.