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

Link to this function

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
Link to this function

child_spec(opts)

Returns a supervisor child specification for a pool of Monet.Connections.

Link to this function

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)
Link to this function

map(input, opts \\ [])

Link to this function

map!(input, opts \\ [])

Link to this function

maps(input, opts \\ [])

Link to this function

maps!(input, opts \\ [])

Link to this macro

pool(args \\ [])

(macro)
Link to this macro

pool(record, args)

(macro)
Link to this function

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)
Link to this function

prepare!(tx, name, 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.

Link to this function

query(pool, sql)

Link to this function

query(tx, sql, args)

Same as query but returns a %Monet.Result{} or raises a %Monet.Error{}.

Link to this function

query!(pool, sql)

Link to this function

query!(tx, sql, args)

Link to this function

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)
Link to this function

scalar!(result)

Link to this function

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.

Link to this function

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.

Link to this function

transaction!(pool \\ __MODULE__, sql)

Same as query but returns a %Monet.Result{}, raises a %Monet.Error{} or raises whatever custom rollback value you provide.