Epiphany

Important Disclaimer

Epiphany is a pet project for now. I use it to practice and learn Elixir.

Do not use in production. The API will probably change a lot. Furthermore, I will not put a lot of effort into tests and documentation until I have a better idea of where this is going.

However, if you would like to help improve the driver and provide feedback, you are very welcome to do so :)

Usage

Epiphany implements version 3 of the CQL binary protocol used by Cassandra.
This means that it should work with versions 2.x and 3.x of Cassandra. It is currently tested against Apache Cassandra 3.3.

Installation

Add epiphany to your list of dependencies in mix.exs:

def deps do
  [{:epiphany, "~> 0.1.0-dev"}]
end

Examples

For now, Epiphany supports opening/closing a connection to one Cassandra node, and running simple queries.

Opening a connection:

# Open a connection to default (localhost:9042)
iex(1)> {:ok, conn} = Epiphany.new()
{:ok, #PID<0.124.0>}

# Open a connection to 10.5.5.5 on 9043
iex(1)> {:ok, conn} = Epiphany.new({&#39;10.5.5.5&#39;, 9043})
{:ok, #PID<0.124.0>}

The connection can (and should) be shared among several clients.

Running simple queries:

iex(2)> Epiphany.query(conn, "use excelsior")
{:result, {:set_keyspace, "excelsior"}}

iex(3)> Epiphany.query(conn, "INSERT INTO users(user_name, birth_year) VALUES (&#39;alice&#39;, 1993)")          
{:result, :void}

iex(4)> Epiphany.query(conn, "SELECT * FROM users")
{:result,
 [["bob", <<0, 0, 0, 0, 0, 0, 7, 110>>],
  ["alice", <<0, 0, 0, 0, 0, 0, 7, 201>>]]}

Using prepared queries:

iex(5)> {:result, {:prepared, id}} = Epiphany.prepare(conn, "SELECT * FROM users")
{:result,
 {:prepared,
  <<101, 144, 20, 44, 208, 131, 139, 221, 194, 118, 95, 142, 46, 35, 223, 228>>}}
  
iex(6)> Epiphany.execute(conn, id)
{:result,
 [["bob", <<0, 0, 0, 0, 0, 0, 7, 110>>],
  ["alice", <<0, 0, 0, 0, 0, 0, 7, 201>>]]}

Closing the connection:

iex(7)> Epiphany.close(conn)
:ok

Roadmap

A lot of things left to do. My main goal is to improve the quality of the code, the tests and the documentation. I use this project to learn the "Elixir Way". Other than that, here is a non-exhaustive list of what I have in mind:

Improve access to query result. Including functions to turn the bytes into the expected type (e.g. int, string, list, etc). Also, support access to paging_state to query for the rest of the result set
Access to metadata in query result to be able to access fields by name instead of by indices
Support creating queries with value placeholders and more parameters like consistency
Handle reconnection to a node
Support authentication and SSL
Support batch statements
Introduce Cluster type to support connection to an entire cluster with automatic discovery of the nodes, reconnection, session management, etc

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.