io.eezo.db

A typed reference to one column of T. DESIGN §9.1.

name is the database name, so a Ref field carries its _id suffix and users never write one: the named tuple's label is the field name, while the value knows the column. It carries its Column[A] because the macro has already summoned one, and the query DSL needs it to bind parameters through the same codec path as encode.

The runtime description of one column, produced by the Table macro.

This type deliberately renders no DDL. Every create table, alter table, and create index in the framework comes out of schema.Ddl, driven by a Change — the fresh-database path included, via Differ.diff(SchemaSnap(Nil), _). One renderer means the migration path and the reset path cannot drift apart (BACKLOG §4).

The database layer's entry trait: the one an application on eezo-db alone extends.

object Main extends DbApp {
 override def schema: Schema = AppSchema
 override def boot(): Unit   = transact { /* a job over rows */ }
}

The layer is declarative. The application names its schema and says what boot does; the framework builds the Database from DbInit's overrides, installs it around the program, and closes it after. main is inherited from Dispatch: sbt run runs the program once with a database installed, and sbt "run status|sync|freeze|migrate|reset|drop|dump|ddl" are the schema commands (design/cli.md §4). dev and routes are the http layer's and do not exist here: eezoDev on a database only application prints the unknown command line on every save, and a rerun on save loop for a job is sbt's own ~run.

A Database is installed only around what needs one. ddl, dump, freeze and help never touch it, so they work with the database down; the program and the other commands get one for their whole duration. Installing never waits on the network: the pool starts empty (initializationFailTimeout negative), so Database.connect returns at once and the pool fills in the background. It is deliberately not eager, as Phoenix is not: with Postgres down, dev keeps serving every page that needs no database, and sbt run fails on the first query that needs Postgres, after the acquire timeout, rather than refusing to start.

How an application names its database: the connection settings and the per connection hook.

Split out of DbApp so that a front end which is not the application's entry point (a deploy runner, the testkit) can build the same Database from the same settings without inheriting boot. DbApp extends this, and the umbrella's EezoApp through it; users override members here and never name the trait.

Named for databaseInit, its one member that is not a string, because it is the one people get wrong; see its comment.

Two spellings of the environment, one mechanism. EEZO_DB_URL/EEZO_DB_USER/ EEZO_DB_PASS are eezo's own and always win. When they are absent and DATABASE_URL is present (the postgres://user:pass@host/db form every PaaS injects: Fly, Heroku, Render), it is parsed into the three, so a deployed application configures itself from the one secret the platform already set. This is a fallback, not a second configuration system: the members below are still the only way the settings are read.

EEZO_DB_POOL_SIZE (default 10) and EEZO_DB_ACQUIRE_TIMEOUT (milliseconds, default 5000) size the pool; DATABASE_URL has no say in either.

A predicate over T, as the small closed ADT BACKLOG §7 asks for. DESIGN §9.2.

Values never reach the SQL string: each becomes a ? and a Bind that goes through the same Column[A] the macro summoned for encode. Injection is not defended against here, it is unrepresentable.

The persistent half of io.eezo.core.Store: a model's rows in Postgres, read and written through its Table[A].

It is what a model deriving Table gets in the generated route table, where the in-memory half in http is what every other model gets. Neither module sees the other; core's trait is the only thing both name.

A plain factory rather than a given. Implicit search for io.eezo.core.Store[Post] looks in object Store in core and in object Post, and a given in this package sits in neither, so it would need an import at every call site to be found at all. The generated table names this object outright instead.

The Table[A] it needs resolves without help wherever it is called, because derives Table puts the instance in the model's own companion.

One order by term. Postgres's own NULL ordering is used — last for asc, first for desc — rather than an explicit NULLS clause. DESIGN §9.4.

A query, as a pure description. DESIGN §9.3.

It holds no capability, so it can be built anywhere, passed around, composed conditionally and unit-tested without a database. Only the terminals require DB, and they are strict — there is no cursor here to outlive the scope that produced it.

The scopes: the whole database API's entry points. DESIGN §8.2.

import io.eezo.db.Scopes.* and write transact { ... }; no Database is ever named.

A table's columns, for the statements that address rows rather than shape.

Binds one parameter. Pure: it closes over a value and its codec, both of which capture nothing, and saying so is what lets these be stored in the tree below.

The columns of T, as a named tuple: cols.title is a Col[T, String].

Computed from the type T, which is what makes it work at all. Backlog §7's blocker was that derives Table expands to a given with an ascribed type Table[Book], widening away any refinement — so Cols could not be a type member. There is no refinement here to widen.