# sqlight

[![Package Version](https://img.shields.io/hexpm/v/sqlight)](https://hex.pm/packages/sqlight)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/sqlight/)

Use [SQLite](https://www.sqlite.org/index.html) from Gleam!

This library is a Gleam wrapper around the excellent Erlang library
[esqlite](https://hex.pm/packages/esqlite), which in turn is a wrapper around
the SQLite C library. It is implemented as a NIF, which means that the SQLite
database engine is linked to the erlang virtual machine.

```gleam
pub fn main() {
  use conn <- sqlight.with_connection(":memory:")
  let cat_decoder = dynamic.tuple2(dynamic.string, dynamic.int)

  let sql = "
  create table cats (name text, age int);

  insert into cats (name, age) values 
  ('Nubi', 4),
  ('Biffy', 10),
  ('Ginny', 6);
  "
  assert Ok(Nil) = sqlight.exec(sql, conn)

  let sql = "
  select name, age from cats
  where age < ?
  "
  assert Ok([#("Nubi", 4), #("Ginny", 6)]) =
    sqlight.query(sql, on: conn, with: [sqlight.int(7)], expecting: cat_decoder)
}
```

## Why SQLite?

SQLite is a implementation of SQL as a library. This means that you don't run a
separate SQL server that your program communicates with, but you embed the SQL
implementation directly in your program. SQLite stores its data in a single
file. The file format is portable between different machine architectures. It
supports atomic transactions and it is possible to access the file by multiple
processes and different programs.

You can also use in-memory databases with SQLite, which may be useful for testing.

## Usage

Add SQLight to your Gleam project:

```sh
gleam add sqlight
```

And start making queries:

```gleam
import sqlight

pub fn main() -> Result(Int, sqlight.Error) {
  use conn <- sqlight.with_connection("mydb.sqlite3")
  // TODO: Use the connection
}
```

Further documentation can be found at <https://hexdocs.pm/sqlight>.