# Epiphany

An Elixir driver for [Apache Cassandra](http://cassandra.apache.org/).

## 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:

```elixir
# 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({'10.5.5.5', 9043})
{:ok, #PID<0.124.0>}
```
The connection can (and should) be shared among several clients.

Running simple queries:

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

iex(3)> Epiphany.query(conn, "INSERT INTO users(user_name, birth_year) VALUES ('alice', 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:

```elixir
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:

```elixir
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

Copyright 2016 Vincent Theron

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.