depo v1.4.2 Depo

Depo provides lightweight storage and querying capabilities in Elixir by providing a minimal and polished API that builds on the unique advantages of SQLite.

You can read about SQLite’s architecture to learn about the SQLite bytecode compiler and other modules within SQLite that you can utilize.

Depo provides create/1 to create a new Depo.DB object with which you can interact with the database.

Anywhere you give a command, you can give either a valid string of SQL or an atom registered to a cached statement. You can also include numbered variables like ?1 in your SQL statements and pass a list of values as the third parameter to write/3, read/3, and stream/3.

Usage Example

# Open a new in-memory database.
{:ok, db} = Depo.open(:memory)
# {:ok, #PID<0.155.0>}
# Write SQL statements to the database.
Depo.write(db, "CREATE TABLE greetings (phrase)")
# :ok
# Teach the database statements to cache them.
Depo.teach(db, %{
  new_greeting: "INSERT INTO greetings VALUES (?1)",
  greetings: "SELECT * FROM greetings",
})
# :ok
# Enclose operations within a transaction.
Depo.transact(db, fn ->
  Enum.each(["hola", "bonjour", "今日は"], fn phrase ->
    Depo.write(db, :new_greeting, [phrase])
  end)
end)
# :ok
# Stream the results of a query to a PID.
Depo.stream(db, self(), :greetings)
# #PID<0.187.0>
:timer.sleep(5)
self() |> Process.info() |> Keyword.get(:messages)
# [ {#PID<0.187.0>, %{phrase: "hola"}}, 
#   {#PID<0.187.0>, %{phrase: "bonjour"}},
#   {#PID<0.187.0>, %{phrase: "今日は"}}]

Summary

Functions

Safely close the database connection

Open a connection to a database and return a new Depo.DB object to manage the database connection

Synchronously read an SQL query from the database and return a list of the results

Asynchronously stream the results of an SQL query from the database to the given PID

Prepare, cache, and register named SQL statements for more efficient repeated use

Wrap any operations within the given anonymous function in a nestable transaction. If any error occurs within, the transaction will be automatically rolled back

Asynchronously write SQL statements to the database

Functions

close(db)

Safely close the database connection.

open(path)

Open a connection to a database and return a new Depo.DB object to manage the database connection.

There are a few ways you can open a database:

  • pass a path to open an existing on-disk database
  • pass create: path to create and open a database at the path
  • pass :memory to create a new in-memory database
read(db, query)
read(db, query, values)

Synchronously read an SQL query from the database and return a list of the results.

Optionally supply a list of values as the third argument to bind to variables in the query.

stream(db, pid, query)
stream(db, pid, query, values)

Asynchronously stream the results of an SQL query from the database to the given PID.

The given process will receive each result as a tuple {stream_id, value} where stream_id is the PID of the stream process that uniquely identifies the stream, and value is a single result map.

Optionally supply a list of values as the fourth argument to bind to variables in the query.

teach(db, stmts)

Prepare, cache, and register named SQL statements for more efficient repeated use.

statements should be a keyword list, where the keys are atoms and the values are SQL statements.

transact(db, func)

Wrap any operations within the given anonymous function in a nestable transaction. If any error occurs within, the transaction will be automatically rolled back.

You can read about SQLite’s transactions in depth in its documentation.

write(db, cmd)
write(db, cmd, values)

Asynchronously write SQL statements to the database.

Optionally supply a list of values as the third argument to bind to variables in the statement.