Build StatusHex.pmEbertCoverage Status

sqlite_ecto2

sqlite_ecto2 is an Ecto 2.x adapter that allows you to create and maintain SQLite3 databases.

Read the tutorial for a detailed example of how to setup and use a SQLite repo with Ecto, or just check-out the CliffsNotes in the sections below if you want to get started quickly.

When to Use sqlite_ecto2

(and when not to use it ...)

IMPORTANT!!!! This is a preliminary, bleeding-edge release. It is believed to work with all 2.0.x and 2.1.x versions of Ecto, but it has not been subjected to any serious performance analysis or stress test. I recommend against deploying this into any sort of production environment at this time.

If you're able to use Ecto 1.x, please look at sqlite_ecto, on which this project is based.

Setting aside the prerelease nature of this library, I strongly recommend reading Appropriate Uses for SQLite on the SQLite page itself. All of the considerations mentioned there apply to this library as well.

I will add one more: If there is any potential that more than one server node will need to write directly to the database at once (as often happens when using Elixir in a clustered environment), do not usesqlite_ecto2. Remember that there is no separate database process in this configuration, so each of your cluster nodes would be writing to its own copy of the database without any synchronization. You probably don't want that. Look for a true client/server database (Postgres, MySQL, or similar) in that case. SQLite's sweet spot is single-machine deployments (embedded, desktop, etc.).

Help Wanted!

If you are willing to live on the bleeding edge, I would welcome any assistance in getting sqlite_ecto2 to a production quality 2.0.0 release. Some specific areas of concern:

Documentation:

Code quality:

This is by no means an exhaustive list. If you have other questions or concerns, please file issues or PRs. I do this in my spare time, so it may take me until I have time on an evening or weekend to reply, but I will appreciate any contribution.

A WARNING About OTP 19.0.x

OTP 19.0.x appears to have a bug that causes it to misinterpret certain pattern matches. This causes the unit tests for sqlite_ecto to fail on some platforms when hosted on OTP 19.0.x. This bug did not appear in OTP 18.0 and appears to have been fixed for OTP 19.1. Consequently, I strongly advise you to avoid using OTP 19.0.x when running sqlite_ecto, especially if using decimal value types.

Note that the Travis configuration for this repo specifically excludes OTP 19.0 for this reason.

Dependencies

This library makes use of Sqlitex and esqlite. Since esqlite uses Erlang NIFs to incorporate SQLite, you will need a valid C compiler to build the library.

Example

Here is an example usage:

# In your config/config.exs file
config :my_app, Repo,
  adapter: Sqlite.Ecto2,
  database: "ecto_simple.sqlite3"

# In your application code
defmodule Repo do
  use Ecto.Repo,
    otp_app: :my_app,
    adapter: Sqlite.Ecto2
end

defmodule Weather do
  use Ecto.Model

  schema "weather" do
    field :city     # Defaults to type :string
    field :temp_lo, :integer
    field :temp_hi, :integer
    field :prcp,    :float, default: 0.0
  end
end

defmodule Simple do
  import Ecto.Query

  def sample_query do
    query = from w in Weather,
          where: w.prcp > 0 or is_nil(w.prcp),
         select: w
    Repo.all(query)
  end
end

Usage

Add sqlite_ecto2 as a dependency in your mix.exs file.

def deps do
  [{:sqlite_ecto2, "~> 2.0.0-dev.5"}]
end

If you are using Elixir 1.3, you should also update your applications list to include sqlite_ecto2 and ecto:

def application do
  [applications: [:logger, :sqlite_ecto2, :ecto]]
end

With Elixir 1.4+, you can do this or rely on application inference.

To use the adapter in your repo:

defmodule MyApp.Repo do
  use Ecto.Repo,
    otp_app: :my_app,
    adapter: Sqlite.Ecto2
end

Incorrect (Surprising?) Implementation of Boolean Operators

SQLite's implementation of the boolean operator ('AND', 'OR', and 'NOT') return a integer values (0 or 1) since there is no boolean data type in SQLite. Certain Ecto code (and, in particular, some Ecto integration tests) expect actual boolean values to be returned. When sqlite_ecto2 is returning a value directly from a column, it is possible to determine that the expected value is boolean and that mapping will occur. Once any mapping occurs (even as simple as NOT column_value), this mapping is no longer possible and you will get the integer value as presented by SQLite instead.

Incomplete Ecto Constraint Implementation

Several Ecto constraints are not fully implemented in sqlite_ecto2 because SQLite does not provide enough information in its error reporting to implement changeset validation properly in all cases. Specifically, some foreign key and uniqueness constraints are reported by raising Sqlite.Ecto2.Error exceptions instead of returning an Ecto changeset with the error detail.

Silently Ignored Options

There are a few Ecto options which sqlite_ecto2 silently ignores because SQLite does not support them and raising an error on them does not make sense: