Sqlite.Ecto2 v2.0.0-dev.5 Sqlite.DbConnection
DBConnection implementation for SQLite.
Summary
Functions
Returns a supervisor child specification for a DBConnection pool
Closes an (extended) prepared query and returns :ok
or
{:error, %Sqlite.DbConnection.Error{}}
if there was an error. Closing a query
releases any resources held by SQLite for a prepared query with that name. See
Sqlite.DbConnection.Query
for the query data
Closes an (extended) prepared query and returns :ok
or raises
Sqlite.DbConnection.Error
if there was an error. See close/3
Runs an (extended) prepared query and returns the result as
{:ok, %Sqlite.DbConnection.Result{}}
or {:error, %Sqlite.DbConnection.Error{}}
if there was an error. Parameters are given as part of the prepared query,
%Sqlite.DbConnection.Query{}
. See the README for information on how SQLite
encodes and decodes Elixir values by default. See Sqlite.DbConnection.Query
for the query data and Sqlite.DbConnection.Result
for the result data
Runs an (extended) prepared query and returns the result or raises
Sqlite.DbConnection.Error
if there was an error. See execute/4
Prepares an (extended) query and returns the result as
{:ok, %Sqlite.DbConnection.Query{}}
or {:error, %Sqlite.DbConnection.Error{}}
if there was an error. Parameters can be set in the query as ?1
embedded in
the query string. To execute the query call execute/4
. To close the prepared
query call close/3
. See Sqlite.DbConnection.Query
for the query data
Prepares an (extended) query and returns the prepared query or raises
Sqlite.DbConnection.Error
if there was an error. See prepare/4
Runs an (extended) query and returns the result as {:ok, %Sqlite.DbConnection.Result{}}
or {:error, %Sqlite.DbConnection.Error{}}
if there was a database error.
Parameters can be set in the query as ?1
embedded in the query string.
Parameters are given as a list of Elixir values. See the README for information
on how SQLite encodes and decodes Elixir values by default. See
Sqlite.DbConnection.Result
for the result data
Rollback a transaction, does not return
Start the connection process and connect to SQLite
Returns a stream for a query on a connection
Acquire a lock on a connection and run a series of requests inside a
transaction. The result of the transaction fun is return inside an :ok
tuple: {:ok, result}
Types
A connection process name, pid or reference.
A connection reference is used when making multiple requests to the same
connection, see transaction/3
and :after_connect
in start_link/1
.
Functions
Returns a supervisor child specification for a DBConnection pool.
close(conn, Sqlite.DbConnection.Query.t, Keyword.t) :: :ok | {:error, Sqlite.DbConnection.Error.t}
Closes an (extended) prepared query and returns :ok
or
{:error, %Sqlite.DbConnection.Error{}}
if there was an error. Closing a query
releases any resources held by SQLite for a prepared query with that name. See
Sqlite.DbConnection.Query
for the query data.
This function may still raise an exception if there is an issue with types
(ArgumentError
), connection (DBConnection.ConnectionError
), ownership
(DBConnection.OwnershipError
) or other error (RuntimeError
).
Options
:pool_timeout
- Time to wait in the queue for the connection (default:5000
):queue
- Whether to wait for connection in a queue (default:true
);:timeout
- Close request timeout (default:5000
);:pool
- The pool module to use, must match that set onstart_link/1
, seeDBConnection
Examples
query = Sqlite.DbConnection.prepare!(conn, "", "CREATE TABLE posts (id serial, title text)")
Sqlite.DbConnection.close(conn, query)
Closes an (extended) prepared query and returns :ok
or raises
Sqlite.DbConnection.Error
if there was an error. See close/3
.
execute(conn, Sqlite.DbConnection.Query.t, list, Keyword.t) :: {:ok, Sqlite.DbConnection.Result.t} | {:error, Sqlite.DbConnection.Error.t}
Runs an (extended) prepared query and returns the result as
{:ok, %Sqlite.DbConnection.Result{}}
or {:error, %Sqlite.DbConnection.Error{}}
if there was an error. Parameters are given as part of the prepared query,
%Sqlite.DbConnection.Query{}
. See the README for information on how SQLite
encodes and decodes Elixir values by default. See Sqlite.DbConnection.Query
for the query data and Sqlite.DbConnection.Result
for the result data.
This function may still raise an exception if there is an issue with types
(ArgumentError
), connection (DBConnection.ConnectionError
), ownership
(DBConnection.OwnershipError
) or other error (RuntimeError
).
Options
:pool_timeout
- Time to wait in the queue for the connection (default:5000
):queue
- Whether to wait for connection in a queue (default:true
);:timeout
- Execute request timeout (default:5000
);:decode_mapper
- Fun to map each row in the result to a term after decoding, (default:fn x -> x end
);:pool
- The pool module to use, must match that set onstart_link/1
, seeDBConnection
Examples
query = Sqlite.DbConnection.prepare!(conn, "", "CREATE TABLE posts (id serial, title text)")
Sqlite.DbConnection.execute(conn, query, [])
query = Sqlite.DbConnection.prepare!(conn, "", "SELECT id FROM posts WHERE title like $1")
Sqlite.DbConnection.execute(conn, query, ["%my%"])
execute!(conn, Sqlite.DbConnection.Query.t, list, Keyword.t) :: Sqlite.DbConnection.Result.t
Runs an (extended) prepared query and returns the result or raises
Sqlite.DbConnection.Error
if there was an error. See execute/4
.
prepare(conn, iodata, iodata, Keyword.t) :: {:ok, Sqlite.DbConnection.Query.t} | {:error, Sqlite.DbConnection.Error.t}
Prepares an (extended) query and returns the result as
{:ok, %Sqlite.DbConnection.Query{}}
or {:error, %Sqlite.DbConnection.Error{}}
if there was an error. Parameters can be set in the query as ?1
embedded in
the query string. To execute the query call execute/4
. To close the prepared
query call close/3
. See Sqlite.DbConnection.Query
for the query data.
This function may still raise an exception if there is an issue with types
(ArgumentError
), connection (DBConnection.ConnectionError
), ownership
(DBConnection.OwnershipError
) or other error (RuntimeError
).
Options
:pool_timeout
- Time to wait in the queue for the connection (default:5000
):queue
- Whether to wait for connection in a queue (default:true
);:timeout
- Prepare request timeout (default:5000
);:pool
- The pool module to use, must match that set onstart_link/1
, seeDBConnection
Examples
Sqlite.DbConnection.prepare(conn, "", "CREATE TABLE posts (id serial, title text)")
prepare!(conn, iodata, iodata, Keyword.t) :: Sqlite.DbConnection.Query.t
Prepares an (extended) query and returns the prepared query or raises
Sqlite.DbConnection.Error
if there was an error. See prepare/4
.
query(conn, iodata, list, Keyword.t) :: {:ok, Sqlite.DbConnection.Result.t} | {:error, Sqlite.DbConnection.Error.t}
Runs an (extended) query and returns the result as {:ok, %Sqlite.DbConnection.Result{}}
or {:error, %Sqlite.DbConnection.Error{}}
if there was a database error.
Parameters can be set in the query as ?1
embedded in the query string.
Parameters are given as a list of Elixir values. See the README for information
on how SQLite encodes and decodes Elixir values by default. See
Sqlite.DbConnection.Result
for the result data.
Options
:pool_timeout
- Time to wait in the queue for the connection (default:5000
):queue
- Whether to wait for connection in a queue (default:true
);:timeout
- Query request timeout (default:5000
);:decode_mapper
- Fun to map each row in the result to a term after decoding, (default:fn x -> x end
);:pool
- The pool module to use, must match that set onstart_link/1
, seeDBConnection
Examples
Sqlite.DbConnection.query(conn, "CREATE TABLE posts (id serial, title text)", [])
Sqlite.DbConnection.query(conn, "INSERT INTO posts (title) VALUES ('my title')", [])
Sqlite.DbConnection.query(conn, "SELECT title FROM posts", [])
Sqlite.DbConnection.query(conn, "SELECT id FROM posts WHERE title like $1", ["%my%"])
Rollback a transaction, does not return.
Aborts the current transaction fun. If inside multiple transaction/3
functions, bubbles up to the top level.
Example
{:error, :oops} = Sqlite.DbConnection.transaction(pid, fn(conn) ->
DBConnection.rollback(conn, :bar)
IO.puts "never reaches here!"
end)
Start the connection process and connect to SQLite.
Options
:hostname
- Server hostname (default: PGHOST env variable, then localhost);:port
- Server port (default: 5432);:database
- Database (required);:username
- Username (default: PGUSER env variable, then USER env var);:password
- User password (default PGPASSWORD);:parameters
- Keyword list of connection parameters;:timeout
- Connect timeout in milliseconds (default:5000
);:ssl
- Set totrue
if ssl should be used (default:false
);:ssl_opts
- A list of ssl options, see ssl docs;:socket_options
- Options to be given to the underlying socket;:sync_connect
- Block instart_link/1
until connection is set up (default:false
):after_connect
- A function to run on connect, either a 1-arity fun called with a connection reference,{module, function, args}
with the connection reference prepended toargs
ornil
, (default:nil
):idle_timeout
- Idle timeout to ping SQLite to maintain a connection (default:5000
):backoff_start
- The first backoff interval when reconnecting (default:200
);:backoff_max
- The maximum backoff interval when reconnecting (default:15_000
);:backoff_type
- The backoff strategy when reconnecting,:stop
for no backoff and to stop (see:backoff
, default::jitter
):transactions
- Set to:strict
to error on unexpected transaction state, otherwise set tonaive
(default::naive
);:pool
- The pool module to use, seeDBConnection
, it must be included with all requests if not the default (default:DBConnection.Connection
);Sqlite.DbConnection
uses theDBConnection
framework and supports allDBConnection
options like:idle
,:after_connect
etc.See
DBConnection.start_link/2
for more information.
stream(DBConnection.t, iodata | Sqlite.DbConnection.Query.t, list, Keyword.t) :: Sqlite.DbConnection.Stream.t
Returns a stream for a query on a connection.
Except that it doesn’t. The implementation currently reads the entire query into memory and returns it as one “stream” result. A future version may implement this more fully.
transaction(conn, (DBConnection.t -> result), Keyword.t) :: {:ok, result} | {:error, any} when result: var
Acquire a lock on a connection and run a series of requests inside a
transaction. The result of the transaction fun is return inside an :ok
tuple: {:ok, result}
.
To use the locked connection call the request with the connection
reference passed as the single argument to the fun
. If the
connection disconnects all future calls using that connection
reference will fail.
rollback/2
rolls back the transaction and causes the function to
return {:error, reason}
.
transaction/3
can be nested multiple times if the connection
reference is used to start a nested transaction. The top level
transaction function is the actual transaction.
Options
:pool_timeout
- Time to wait in the queue for the connection (default:5000
):queue
- Whether to wait for connection in a queue (default:true
);:timeout
- Transaction timeout (default:5000
);:pool
- The pool module to use, must match that set onstart_link/1
, seeDBConnection
:mode
- Set to:savepoint
to use savepoints instead of an SQL transaction, otherwise set to:transaction
(default::transaction
);
The :timeout
is for the duration of the transaction and all nested
transactions and requests. This timeout overrides timeouts set by internal
transactions and requests. The :pool
and :mode
will be used for all
requests inside the transaction function.
Example
{:ok, res} = Sqlite.DbConnection.transaction(pid, fn(conn) ->
Sqlite.DbConnection.query!(conn, "SELECT title FROM posts", [])
end)