Mariaex v0.9.1 Mariaex View Source

Main API for Mariaex.

Link to this section Summary

Types

conn()

A connection process name, pid or reference

Functions

child_spec(opts)

Returns a supervisor child specification for a DBConnection pool

close!(conn, query, opts \\ [])

Close a prepared query and returns :ok or raises Mariaex.Error if there was an error. See close/3

close(conn, query, opts \\ [])

Close a prepared a query and returns :ok or {:error, %Mariaex.Error{}} if there was an error

execute!(conn, query, params, opts \\ [])

Runs an (extended) prepared query and returns the result or raises Mariaex.Error if there was an error. See execute/4

execute(conn, query, params, opts \\ [])

Runs an (extended) prepared query and returns the result as {:ok, %Mariaex.Query{}, %Mariaex.Result{}} or {:error, %Mariaex.Error{}} if there was an error. Parameters are given as part of the prepared query, %Mariaex.Query{}

prepare!(conn, name, statement, opts \\ [])

Prepared an (extended) query and returns the prepared query or raises Mariaex.Error if there was an error. See prepare/4

prepare(conn, name, statement, opts \\ [])

Prepares an query and returns the result as {:ok, %Mariaex.Query{}} or {:error, %Mariaex.Error{}} if there was an error. Parameters can be set in the query as ? embedded in the query string. To execute the query call execute/4. To close the prepared query call close/3. See Mariaex.Query for the query data

prepare_execute!(conn, name, statement, params, opts \\ [])

Prepares and executes a query and returns the result or raises Mariaex.Error if there was an error. See execute/4

prepare_execute(conn, name, statement, params, opts \\ [])

Prepares and executes a query and returns the result as {:ok, %Mariaex.Query{}, %Mariaex.Result{}} or {:error, exception} if there was an error. Parameters are given as part of the prepared query, %Mariaex.Query{}

query!(conn, statement, params \\ [], opts \\ [])

Runs an (extended) query and returns the result or raises Mariaex.Error if there was an error. See query/3

query(conn, statement, params \\ [], opts \\ [])

Runs an (extended) query and returns the result as {:ok, %Mariaex.Result{}} or {:error, %Mariaex.Error{}} if there was an error. Parameters can be set in the query as ? embedded in the query string. Parameters are given as a list of elixir values. See the README for information on how Mariaex encodes and decodes elixir values by default. See Mariaex.Result for the result data

rollback(conn, any)

Rollback a transaction, does not return

start_link(opts)

Start the connection process and connect to mariadb

stream(conn, query, params, opts \\ [])

Returns a stream for a query on a connection

transaction(conn, fun, opts \\ [])

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}

Link to this section Types

conn()

conn() :: DBConnection.conn()

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.

Link to this section Functions

child_spec(opts)

child_spec(Keyword.t()) :: Supervisor.Spec.spec()

Returns a supervisor child specification for a DBConnection pool.

close!(conn, query, opts \\ [])

close!(conn(), Mariaex.Query.t(), Keyword.t()) :: :ok

Close a prepared query and returns :ok or raises Mariaex.Error if there was an error. See close/3.

close(conn, query, opts \\ [])

close(conn(), Mariaex.Query.t(), Keyword.t()) :: :ok | {:error, Exception.t()}

Close a prepared a query and returns :ok or {:error, %Mariaex.Error{}} if there was an error.

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: 15000);

Examples

query = Mariaex.prepare!(conn, "SELECT id FROM posts WHERE title like $1")
Mariaex.close(conn, query)

execute!(conn, query, params, opts \\ [])

execute!(conn(), Mariaex.Query.t(), list(), Keyword.t()) :: Mariaex.Result.t()

Runs an (extended) prepared query and returns the result or raises Mariaex.Error if there was an error. See execute/4.

execute(conn, query, params, opts \\ [])

execute(conn(), Mariaex.Query.t(), list(), Keyword.t()) ::
  {:ok, Mariaex.Query.t(), Mariaex.Result.t()} | {:error, Exception.t()}

See the README for information on how Mariaex encodes and decodes Elixir values by default. See Mariaex.Query for the query data and Mariaex.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 - Execute request timeout (default: 15000);
:decode_mapper - Fun to map each row in the result to a term after decoding, (default: fn x -> x end);

Examples

query = Mariaex.prepare!(conn, "CREATE TABLE posts (id serial, title text)")
Mariaex.execute(conn, query, [])

query = Mariaex.prepare!(conn, "SELECT id FROM posts WHERE title like $1")
Mariaex.execute(conn, query, ["%my%"])

prepare!(conn, name, statement, opts \\ [])

prepare!(conn(), iodata(), iodata(), Keyword.t()) :: Mariaex.Query.t()

Prepared an (extended) query and returns the prepared query or raises Mariaex.Error if there was an error. See prepare/4.

prepare(conn, name, statement, opts \\ [])

prepare(conn(), iodata(), iodata(), Keyword.t()) ::
  {:ok, Mariaex.Query.t()} | {:error, Exception.t()}

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: 15000);
:query_type - :binary to use binary protocol, :text to use text protocol or nil to try binary but fallback to text (default nil)

Examples

Mariaex.prepare(conn, "", "CREATE TABLE posts (id serial, title text)")

prepare_execute!(conn, name, statement, params, opts \\ [])

Prepares and executes a query and returns the result or raises Mariaex.Error if there was an error. See execute/4.

prepare_execute(conn, name, statement, params, opts \\ [])

prepare_execute(conn(), iodata(), iodata(), list(), Keyword.t()) ::
  {:ok, Mariaex.Query.t(), Mariaex.Result.t()} | {:error, Exception.t()}

See the README for information on how Mariaex encodes and decodes Elixir values by default. See Mariaex.Query for the query data and Mariaex.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 - Execute request timeout (default: 15000);
:decode_mapper - Fun to map each row in the result to a term after decoding, (default: fn x -> x end);

Examples

Mariaex.prepare_execute(conn, "", "SELECT id FROM posts WHERE title like $1", ["%my%"])

query!(conn, statement, params \\ [], opts \\ [])

Runs an (extended) query and returns the result or raises Mariaex.Error if there was an error. See query/3.

query(conn, statement, params \\ [], opts \\ [])

query(conn(), iodata(), list(), Keyword.t()) ::
  {:ok, Mariaex.Result.t()} | {:error, Exception.t()}

A type hinted query is run if both the options :param_types and :result_types are given. One client-server round trip can be saved by providing the types to Mariaex because the server doesn’t have to be queried for the types of the parameters and the result.

Options

:timeout - Call timeout (default: 15000)
:param_types - A list of type names for the parameters
:result_types - A list of type names for the result rows
:decode - If the result set decoding should be done automatically (:auto) or manually (:manual) via decode/2. Defaults to :auto.
: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: 15000);
:encode_mapper - Fun to map each parameter before encoding, see (default: fn x -> x end)
:decode_mapper - Fun to map each row in the result to a term after decoding, (default: fn x -> x end);
:include_table_name - Boolean specifying whether the columns list in the result prepends the table name to the column name with a period. (default false)
:binary_as - encoding binary as :field_type_var_string (default) or :field_type_blob
:query_type - :binary to use binary protocol, :text to use text protocol nil to try binary but fallback to text (default nil)

Examples

Mariaex.query(pid, "CREATE TABLE posts (id serial, title text)")

Mariaex.query(pid, "INSERT INTO posts (title) VALUES ('my title')")

Mariaex.query(pid, "SELECT title FROM posts", [])

Mariaex.query(pid, "SELECT id FROM posts WHERE title like ?", ["%my%"])

Mariaex.query(pid, "SELECT ? || ?", ["4", "2"],
                          param_types: ["text", "text"], result_types: ["text"])

rollback(conn, any)

rollback(DBConnection.t(), any()) :: no_return()

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} = Mariaex.transaction(pid, fn(conn) ->
  Mariaex.rollback(conn, :oops)
  IO.puts "never reaches here!"
end)

start_link(opts)

start_link(Keyword.t()) :: {:ok, pid()} | {:error, Mariaex.Error.t() | term()}

Start the connection process and connect to mariadb.

Options

:hostname - Server hostname (default: MDBHOST env variable, then localhost);
:port - Server port (default: MDBPORT env var, then 3306);
:socket - Local socket file name, if exists overrides :hostname and :port
:sock_type - Socket type (default: :tcp);
:database - Database (required, if :skip_database not true);
:skip_database - Flag to set connection without database;
:username - Username (default: MDBUSER env variable, then USER env var);
:password - User password (default MDBPASSWORD);
:encoder - Custom encoder function;
:decoder - Custom decoder function;
:sync_connect - Block in start_link/1 until connection is set up (default: false)
:formatter - Function deciding the format for a type;
:parameters - Keyword list of connection parameters;
:timeout - Connect timeout in milliseconds (default: 15000);
:charset - Database encoding (default: “utf8”);
:socket_options - Options to be given to the underlying socket;
:cache_size - Prepared statement cache size (default: 100);
:insecure_auth - Secure authorization (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 to args or nil, (default: nil)
:idle_timeout - Idle timeout to ping database 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 to naive (default: :naive);
:idle - Either :active to asynchronously detect TCP disconnects when idle or :passive not to (default: :passive);
:pool - The pool module to use, see DBConnection for pool dependent options (default: DBConnection.ConnectionPool);
:name - A name to register the started process (see the :name option in GenServer.start_link/3).
:datetime - How datetimes should be returned. :structs for Elixir v1.3 calendar types or :tuples for the backwards compatible tuples

Function signatures

@spec encoder(info :: TypeInfo.t, default :: fun, param :: term) ::
      binary
@spec decoder(info :: TypeInfo.t, default :: fun, bin :: binary) ::
      term
@spec formatter(info :: TypeInfo.t) ::
      :binary | :text | nil

stream(conn, query, params, opts \\ [])

stream(DBConnection.t(), iodata() | Mariaex.Query.t(), list(), Keyword.t()) ::
  DBConnection.Stream.t()

Returns a stream for a query on a connection.

Streams read chunks of at most max_rows rows and can only be used inside a transaction.

Options

:max_rows - Maximum numbers of rows in a result (default to 500)
:query_type - :binary to use binary protocol, :text to use text protocol or nil to try binary but fallback to text (default nil)

Mariaex.transaction(pid, fn(conn) -> stream = Mariaex.stream(conn, “SELECT id FROM posts WHERE title like $1”, [“%my%”]) Enum.to_list(stream) end)

transaction(conn, fun, opts \\ [])

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: 15000);
: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 :mode will be used for all requests inside the transaction function.

Example

{:ok, res} = Mariaex.transaction(pid, fn(conn) ->
  Mariaex.query!(conn, "SELECT title FROM posts", [])
end)