Schema
Orm is a small typed layer over Db. A schema ties a plain struct to a table. Every function takes the Db.Connection and gives a new value: there is no global connection and no lazy loading. Import it with import Orm from "pkg/db/orm".
import Db from "pkg/db/db"
import Orm from "pkg/db/orm"
import Sqlite from "pkg/db/sqlite"
CREATE_USERS = "create table users (id integer primary key, name text not null, age integer)"
struct User
id: Int = 0
name: String
age: Optional[Int] = none
end
def run() -> Result[Void]
conn = try Db.open("sqlite::memory:", [Sqlite.driver()])
try Db.execute(conn, CREATE_USERS, [])
users = Orm.schema("users", User.codec)
try Orm.check(conn, users)
puts(users.table)
puts(users.primary_key)
Db.close(conn)
return ok()
end
def main() -> Void
case run()
ok(_) -> puts("done")
error(message) -> IO.warn(message)
end
endOutput
users
id
doneThe schema #
Orm.schema(table, T.codec) gives an Orm.Schema[T]. It checks nothing. Orm.check(conn, schema) does, once, at start up, and reads no row:
- the table and column names are plain identifiers (a letter or
_, then letters, digits or_); - every field has a type a column can hold;
- the key is a field, and not an
Optionalor aJSON.Field(a NULL key would match no row); - the table has every column. A table or a column that is missing is the error of
Db, unchanged.
The key is id, and the database generates it, unless .with(...) says otherwise:
import Orm from "pkg/db/orm"
struct Tag
code: String
label: String
end
def main() -> Void
tags = Orm.schema("tags", Tag.codec).with(primary_key: "code", generated: false)
puts(tags.primary_key)
puts(tags.generated)
endOutput
code
falseA generated key must be an Int. The key of a table the database numbers is written id: Int = 0, so a value can be built before the database gives it its id.
Fields and columns #
- A column has the name of its field. The Orm quotes every name (double quotes for PostgreSQL, backticks for MySQL and SQLite), so a name is exact in PostgreSQL, which folds an unquoted name to lower case.
- A field is an
Int, aFloat, aBoolor aString, alone or inside anOptionalor aJSON.Field. - A column that can be NULL is an
Optional[T]: NULL reads asnone, andnonewrites a NULL. With a default,age: Optional[Int] = none, a value can leave it out. - A
JSON.Field[T]field also tells a column that is not there: NULL reads asJSON.Field.Null, and a column the query does not select isJSON.Field.Absent, which a write leaves alone (see writes). Use it only when that matters. - A NULL in any other field is an error, and so is a missing column for any field but a
JSON.Field. AnOptionalfield needs its column in the select, NULL or not: for a projection that leaves a column out, use aJSON.Fieldfield orquery_as. - A
Boolcolumn of SQLite and MySQL comes back fromDbas 0 or 1, and the Orm reads it as aBool. - An
Intcolumn is read as aFloatfor aFloatfield, unless theIntis beyond 2^53, which could round: that is an error. - A
numeric, a date or a uuid arrives asText: use aStringfield.
Errors of the Orm are Result failures, like those of Db. The errors page tells the kinds apart.