database

README

database

Database adapter for Arandu: 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.

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 used to carry pgx and modernc/sqlite together, and govulncheck found a pgx advisory in a project that could have been SQLite-only.

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

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 stays what it was: a line in .env. The import list is what decides which engines a build can speak at all — and a missing one says so:

DB_CONNECTION is pgsql and no driver for it is linked into this binary
(linked: sqlite).
Add it:

    go get github.com/arandu-io/database/pgx

and blank-import it in cmd/app/main.go:

    _ "github.com/arandu-io/database/pgx"

MIT. See LICENSE.md.

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 stays what ADR 0009 promised: 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 config.DatabaseConfig) (*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 config.DatabaseConfig) (*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.