# agentica-db

agentica-db is a database package for [Agentica](https://agentica-lang.github.io/agentica/). One API, `Db`, opens SQLite, PostgreSQL and MySQL or MariaDB, runs queries with bound parameters, and runs transactions. A small layer on top, `Orm`, reads rows into plain structs.

Each database is reached through its system client library, by the C FFI. SQLite and PostgreSQL also have a native driver, a small C module of the package that caches prepared statements and reads many rows per call (see [SQLite](https://agentica-lang.github.io/agentica-db/databases/sqlite/index.md#drivers) and [PostgreSQL](https://agentica-lang.github.io/agentica-db/databases/postgresql/index.md#drivers)); MySQL's runs on Linux (see [MySQL](https://agentica-lang.github.io/agentica-db/databases/mysql/index.md#drivers)).

Add it to the `agentica.toml` of your project:

```toml
[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`. [Getting started](https://agentica-lang.github.io/agentica-db/getting-started/index.md) has the details.

A first program, on a private in-memory SQLite database:

```agentica
import Db from "pkg/db/db"
import Sqlite from "pkg/db/sqlite"

def main() -> Void
  conn = Db.open("sqlite::memory:", [Sqlite.driver()]).unwrap!
  Db.execute(conn, "create table users (name text not null, age integer)", []).unwrap!
  Db.execute(conn, "insert into users (name, age) values (?, ?)", [Db.Value.Text("Ana"), Db.Value.Int(31)]).unwrap!
  rows = Db.query(conn, "select name, age from users where age > ?", [Db.Value.Int(28)]).unwrap!
  puts(rows)
  Db.close(conn)
end
```

```output
[{"name": Value.Text("Ana"), "age": Value.Int(31)}]
```

- [Getting started](https://agentica-lang.github.io/agentica-db/getting-started/index.md) installs the package and shows the system libraries it needs.
- [Basics](https://agentica-lang.github.io/agentica-db/basics/index.md): connecting, queries, values and transactions.
- [ORM](https://agentica-lang.github.io/agentica-db/orm/index.md): schema, reads, the query builder, writes and errors.
- [Production](https://agentica-lang.github.io/agentica-db/production/index.md): timeouts and the generic pool.
- [Tools](https://agentica-lang.github.io/agentica-db/tools/index.md): migrations and testing.
- [Databases](https://agentica-lang.github.io/agentica-db/databases/index.md): the reference for SQLite, PostgreSQL, and MySQL and MariaDB.
- The source and the changelog are [on GitHub](https://github.com/agentica-lang/agentica-db).

Not yet: preloading of related rows.

agentica-db 0.12.0 needs Agentica 0.31.0 or later (a C compiler gives the faster native drivers), and is under the Apache License 2.0.
