AshScylla.Connection (AshScylla v0.10.0)

Copy Markdown View Source

Direct Xandra connection wrapper for AshScylla.

Replaces the Exandra/Ecto.Repo pattern. Manages a Xandra connection process and provides query/prepare operations.

Usage

# In your application supervision tree:
children = [
  {AshScylla.Connection, name: MyApp.Scylla, nodes: ["127.0.0.1:9042"], keyspace: "my_app"}
]

# Or start manually:
{:ok, conn} = AshScylla.Connection.start_link(nodes: ["127.0.0.1:9042"], keyspace: "my_app")

Options

All options are passed through to Xandra.start_link/1. Key options:

  • :name - Register the connection under this name (required for supervised start)
  • :nodes - List of nodes, e.g. ["127.0.0.1:9042"]
  • :keyspace - Keyspace to USE on connect

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

ensure_keyspace!(conn, name)

Ensures the keyspace is selected. Retries USE if not yet applied.

get_conn(name \\ __MODULE__)

Returns the connection struct by name (local or global).

prepare(conn_or_name, query, opts \\ [])

Prepares a CQL statement.

prepare!(conn_or_name, query, opts \\ [])

Prepares a CQL statement, raising on error.

query(conn_or_name, query, params, opts \\ [])

Executes a simple or prepared query.

query!(conn_or_name, query, params, opts \\ [])

Executes a simple or prepared query, raising on error.

reconnect_keyspace(name)

Reconnects to the keyspace. Useful after the keyspace has been created. Returns {:ok, :set} or {:error, reason}.

set_keyspace(name, keyspace)

Sets the keyspace to use. Useful when the keyspace is created after connection start. Returns {:ok, :set} or {:error, reason}.

start_link(opts)
stop(name)

Stops the connection.

typed_params(params)

Converts raw Elixir values to typed Xandra params.

Types

t()

@type t() :: %AshScylla.Connection{
  conn: pid(),
  keyspace: String.t() | nil,
  keyspace_used: boolean(),
  nodes: [String.t()]
}

Functions

child_spec(init_arg)

@spec child_spec(keyword()) :: Supervisor.child_spec()

Returns a specification to start this module under a supervisor.

See Supervisor.

ensure_keyspace!(conn, name)

Ensures the keyspace is selected. Retries USE if not yet applied.

get_conn(name \\ __MODULE__)

@spec get_conn(module() | atom()) :: t() | nil

Returns the connection struct by name (local or global).

prepare(conn_or_name, query, opts \\ [])

@spec prepare(t() | module(), String.t(), keyword()) ::
  {:ok, Xandra.Prepared.t()} | {:error, term()}

Prepares a CQL statement.

prepare!(conn_or_name, query, opts \\ [])

@spec prepare!(t() | module(), String.t(), keyword()) ::
  Xandra.Prepared.t() | no_return()

Prepares a CQL statement, raising on error.

query(conn_or_name, query, params, opts \\ [])

@spec query(t() | module(), String.t(), list(), keyword()) ::
  {:ok, term()} | {:error, term()}

Executes a simple or prepared query.

Automatically types simple query values for Xandra 0.19.x compatibility. Xandra requires typed {type_string, value} tuples for simple query parameters, so we wrap raw Elixir values in their appropriate CQL type annotations.

query!(conn_or_name, query, params, opts \\ [])

@spec query!(t() | module(), String.t(), list(), keyword()) :: term() | no_return()

Executes a simple or prepared query, raising on error.

reconnect_keyspace(name)

@spec reconnect_keyspace(atom()) :: {:ok, :set} | {:error, term()}

Reconnects to the keyspace. Useful after the keyspace has been created. Returns {:ok, :set} or {:error, reason}.

set_keyspace(name, keyspace)

@spec set_keyspace(atom(), String.t()) :: {:ok, :set} | {:error, term()}

Sets the keyspace to use. Useful when the keyspace is created after connection start. Returns {:ok, :set} or {:error, reason}.

start_link(opts)

@spec start_link(keyword()) :: GenServer.on_start()

stop(name)

@spec stop(t() | module()) :: :ok

Stops the connection.

typed_params(params)

@spec typed_params(list()) :: list()

Converts raw Elixir values to typed Xandra params.

Xandra 0.19.x requires simple query values to be {type_string, value} tuples. This function infers the CQL type from the Elixir type.