Getting started
Install #
Install Agentica 0.31.0 or later for the tag 0.12.0, and a C compiler (cc, or CC; on Debian gcc and libc6-dev) where a program that imports a driver of the package first runs or is compiled: Agentica builds the native SQLite, PostgreSQL or MySQL module of each driver the program imports then (see SQLite). Without a compiler Agentica prints a warning (warning: native module db_sqlite not built: ...) and the program runs the FFI drivers, which are slower. agentica-db is a package: you add it to the agentica.toml of your project as a dependency on its git repository.
[dependencies]
db = { git = "https://github.com/agentica-lang/agentica-db", tag = "0.12.0", subdir = "src/db" }Or run agentica add db https://github.com/agentica-lang/agentica-db --tag 0.12.0 --subdir src/db. Both (and agentica install for a manifest you edited) write agentica.lock and put the files in deps/db/.
The package is the src/db folder of the repository, so the dependency needs subdir = "src/db", for every release after 0.3.0 and for ref = "COMMIT" (a commit of main). The releases up to 0.3.0 have the package at the root of the repository: with those tags leave subdir out. The imports are the same in both.
Import the modules with pkg/db/.... Db is the API, Orm the typed layer, and Sqlite, Postgres and Mysql the drivers that Db.open takes: import only the ones the program uses (see Connecting).
import Db from "pkg/db/db"
import Orm from "pkg/db/orm"
import Sqlite from "pkg/db/sqlite"
struct Note
id: Int = 0
text: String
end
def main() -> Void
notes = Orm.schema("notes", Note.codec)
puts(Db.open("sqlite::memory:", [Sqlite.driver()]).ok?)
puts(notes.table)
endtrue
notesSystem libraries #
You need the client library of each database you open. A library loads when the first call needs it, so SQLite alone works without libpq or libmariadb.
| Database | Library | Package on Debian and Ubuntu |
|---|---|---|
| SQLite | libsqlite3.so.0 | libsqlite3-0 |
| PostgreSQL 12 or later | libpq.so.5 | libpq5 |
| MySQL, MariaDB | libmariadb.so.3 | libmariadb3 |
macOS and Windows names are declared (libsqlite3.dylib, libpq.5.dylib, libmariadb.3.dylib, winsqlite3.dll, libpq.dll, libmariadb.dll), but CI runs the SQLite suite on macOS and Windows, and the whole suite on Linux. On macOS the manifest cannot name an absolute path, so run with Homebrew’s libraries, as in DYLD_LIBRARY_PATH="$(brew --prefix libpq)/lib" agentica app.agc (for MySQL, mariadb-connector-c). On Windows the DLLs are looked up next to agentica.exe and in System32, never in PATH, and so are the DLLs they need.
A library that is missing does not stop the program: open gives an error that says so, as in sqlite error: cannot load the SQLite library: ....
A first program #
Save this as app.agc and run it with agentica app.agc. It opens a database, makes a table, writes in a transaction and reads back.
import Db from "pkg/db/db"
import Sqlite from "pkg/db/sqlite"
def save(conn: Db.Connection, name: String, age: Int) -> Result[Int]
return Db.execute(conn, "insert into users (name, age) values (?, ?)", [Db.Value.Text(name), Db.Value.Int(age)])
end
def run() -> Result[Void]
conn = try Db.open("sqlite::memory:", [Sqlite.driver()])
try Db.execute(conn, "create table users (name text not null, age integer)", [])
try Db.transaction(conn) do |tx|
try save(tx, "Ana", 31)
try save(tx, "Bob", 27)
ok()
end
rows = try Db.query(conn, "select name from users order by name", [])
puts(rows.size)
Db.close(conn)
return ok()
end
def main() -> Void
case run()
ok(_) -> puts("done")
error(message) -> IO.warn(message)
end
end2
doneEvery call gives a Result, so the program uses try to pass an error up, and main is the one place that looks at it. The next pages explain each call: connecting, queries, values and transactions.