monet v0.0.9 Monet
Main interface for interacting with a MonetDB server. Implemented as a pool of Monet.Connection. Commands such as query/1 check out a Connection from the pool, call query/1 on it, and then check it back in.
The pool has a simple backoff implementation in the case of failed connections. The maximum sleep time before trying to reconnect is 4 seconds.
Link to this section Summary
Functions
By default, the Monet.Result
returned from a select will enumerate a list of
lists (via the Enumerable protocol or Jason.encode).
Returns a supervisor child specification for a pool of Monet.Connections.
Commits the transaction. This can either be called implicitly based on the
return value of your transaction fun
Creates a prepared statement for use in a transaction. The statements are automatically cleaned up at the end of the transaction.
Executes a query. Returns {:ok, %Monet.Result{}} or {:error, %Monet.Error{}} If no pool name is given, then the default name, Monet, is used. If no arguments are given, then a simple query is executed, otherwise, the query is prepared + executed + deallocated.
Same as query but returns a %Monet.Result{} or raises a %Monet.Error{}.
Rollsback the transaction. This can either be called implicitly based on the
return value of your transaction fun
Starts the pool and establishes the specified number of connections
Checkouts a connection and runs fun
within a transaction.
Same as query but returns a %Monet.Result{}, raises a %Monet.Error{} or raises whatever custom rollback value you provide.
Link to this section Functions
as_map(value, opts \\ [])
By default, the Monet.Result
returned from a select will enumerate a list of
lists (via the Enumerable protocol or Jason.encode).
The behavior can be changed to enumerate or encode to a list of maps:
"select id, name from saiyans"
|> Monet.query!()
|> Monet.as_map()
|> Jason.encode() # or Enum.reduce/map/...
Note that calling as_map
does not change the rows
field of the result. It
merely configures how the enumeration will operate. So, to get a list of all
maps with columns as atoms, one would do:
"select id, name from saiyans"
|> Monet.query!()
|> Monet.as_map(columns: :atoms)
|> Enum.list()
as_map
works on any value returned by query
and query!
. In the case of an
error, the error is simply returned. As such, a safer usage would be:
case Monet.as_map(Monet.query("select id, name from saiyans")) do
{:ok, result} -> ...
{:error, err} -> ...
end
child_spec(opts)
Returns a supervisor child specification for a pool of Monet.Connections.
commit(tx, result)
Commits the transaction. This can either be called implicitly based on the
return value of your transaction fun
:
Monet.transaction!(fn tx ->
....
{:commit, return_value} # or simply {:ok, return_value}
end)
or explicitly:
Monet.transaction!(fn tx ->
....
Monet.commit(tx, return_value)
end)
map(input, opts \\ [])
map!(input, opts \\ [])
maps(input, opts \\ [])
maps!(input, opts \\ [])
prepare(tx, name, sql)
Creates a prepared statement for use in a transaction. The statements are automatically cleaned up at the end of the transaction.
Use with care. MonetDB automatically deallocates prepared statements on execution error. If a query using a prepared statement fails in your transaction you should probably end the transaction.
Monet.transaction(fn tx ->
Monet.prepare(tx, :test_insert, "insert into test (id) values (?)")
with {:ok, r1} <- Monet.query(tx, :test_insert, [1]),
{:ok, r2} <- Monet.query(tx, :test_insert, [2])
do
{:ok, [r1, r2]}
else
err -> {:rollback, err}
end
end)
prepare!(tx, name, sql)
query(sql)
Executes a query. Returns {:ok, %Monet.Result{}} or {:error, %Monet.Error{}} If no pool name is given, then the default name, Monet, is used. If no arguments are given, then a simple query is executed, otherwise, the query is prepared + executed + deallocated.
query(pool, sql)
query(tx, sql, args)
query!(sql)
Same as query but returns a %Monet.Result{} or raises a %Monet.Error{}.
query!(pool, sql)
query!(tx, sql, args)
rollback(tx, result)
Rollsback the transaction. This can either be called implicitly based on the
return value of your transaction fun
:
Monet.transaction!(fn tx ->
....
{:rollback, return_value}
end)
or explicitly:
Monet.transaction!(fn tx ->
....
Monet.rollback(tx, return_value)
end)
row(result)
row!(result)
rows(result)
rows!(result)
scalar(result)
scalar!(result)
start_link(opts)
Starts the pool and establishes the specified number of connections
Options
-
:connect_timeout
- Timeout, in milliseconds, to conn10_000 -
:database
- Database to conenct to (default: "monetdb") -
:host
- Hostname or IP of the server to connect to (default:"127.0.0.1") -
:name
- The process name of the pool (default: Monet) -
:password
- Password to use (default: "monetdb") -
:pool_size
- Size of the conncetion pool (default: 10) -
:port
- Port of the server to connect to (default: 50_000) -
:schema
- The schema to use (defautls to not sending a 'set schema' command (and thus defaults to the user's defautl schema)) -
:role
- The role to use (defautls to not sending a 'set role' command (and thus defaults to the user's defautl role)) -
:read_timeout
- Timeout, in milliseconds, for individual tcp recv operations (default: 10_000) -
:send_timeout
- Timeout, in milliseconds, for individual tcp send operatins (default: 10_000) -
:username
- Username to use (default: "monetdb")
If a :name
is given, that value must be provided as the first parameter to
other functions in this module.
transaction(pool \\ __MODULE__, fun)
Checkouts a connection and runs fun
within a transaction.
If fun
returns {:rollback, res}
, the transaction is rolled back and
{:error, res}
is returned. Alternatively, Monet.rollback/2
can be used to
the same effect.
NOTE: The above means that, unlike other functions which only return
{:ok, %Monet.Result{}}
or {:error, %Monet.Error{}}
, this function can
also return {:error, term}
where term
is any value passed to Monet.rollback/2
)
or specified via {:rollback, value}
.
Any other value returned by fun
will result in the transaction being committed:
Monet.transaction(fn tx ->
Monet.query(tx, "....")
Monet.query(tx, "....")
end)
To be more explicit, fun
can return {:commit, result}
in which case the
transaction will be commited and {:ok, result}
will be returned.
transaction!(pool \\ __MODULE__, sql)
Same as query but returns a %Monet.Result{}, raises a %Monet.Error{} or raises whatever custom rollback value you provide.