Direct Xandra connection wrapper for AshScylla.
Replaces the Exandra/Ecto.Repo pattern. Manages a Xandra connection process and provides query/prepare operations.
Supports both single-node (Xandra.start_link/1) and multi-node
(Xandra.Cluster.start_link/1) connections.
Usage
Single-node connection:
# 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")Multi-node cluster connection (all nodes must use the same port):
children = [
{AshScylla.Connection,
name: MyApp.Scylla,
nodes: ["scylla-1:9042", "scylla-2:9042", "scylla-3:9042"],
keyspace: "my_app",
pool_size: 10}
]Options
All options are passed through to Xandra.start_link/1 (single node) or
Xandra.Cluster.start_link/1 (multiple nodes). Key options:
:name- Register the connection under this name (required for supervised start):nodes- List of nodes, e.g.["127.0.0.1:9042"]or[{"127.0.0.1", 9042}]:keyspace- Keyspace to USE on connect:pool_size- Number of connections per node (cluster mode, default: 1):connect_timeout- Connection timeout in milliseconds (default: 5000):autodiscovered_nodes_port- Port for autodiscovered peers (default: 9042). When using a cluster with a non-standard port, this is auto-detected from the first node if all nodes share the same port.:sync_connect- Wait for at least one connection before returning. Set tofalsefor async connect (default: 5000ms timeout in cluster mode).
Cluster Mode
When multiple nodes are provided, AshScylla.Connection uses Xandra.Cluster
for load balancing and fault tolerance.
Important: Xandra.Cluster requires all nodes to share the same port.
It uses a single autodiscovered_nodes_port for all discovered peers
(Scylla/Cassandra system.peers does not advertise ports).
If nodes have different ports, AshScylla.Connection falls back to a
single-node connection to the first node and logs a warning.
Summary
Functions
Returns a specification to start this module under a supervisor.
Ensures the keyspace is selected. Retries USE if not yet applied.
Returns the connection struct by name (local or global).
Prepares a CQL statement.
Prepares a CQL statement, raising on error.
Executes a simple or prepared query.
Executes a simple or prepared query, raising on error.
Reconnects to the keyspace. Useful after the keyspace has been created.
Returns {:ok, :set} or {:error, reason}.
Sets the keyspace to use. Useful when the keyspace is created after connection start.
Returns {:ok, :set} or {:error, reason}.
Stops the connection.
Converts raw Elixir values to typed Xandra params.
Types
Functions
@spec child_spec(keyword()) :: Supervisor.child_spec()
Returns a specification to start this module under a supervisor.
See Supervisor.
Ensures the keyspace is selected. Retries USE if not yet applied.
Returns the connection struct by name (local or global).
@spec prepare(t() | module(), String.t(), keyword()) :: {:ok, Xandra.Prepared.t()} | {:error, term()}
Prepares a CQL statement.
Prepares a CQL statement, raising on error.
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.
Executes a simple or prepared query, raising on error.
Reconnects to the keyspace. Useful after the keyspace has been created.
Returns {:ok, :set} or {:error, reason}.
Sets the keyspace to use. Useful when the keyspace is created after connection start.
Returns {:ok, :set} or {:error, reason}.
@spec start_link(keyword()) :: GenServer.on_start()
Stops the connection.
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.