README

Laravel Cassandra

A Cassandra based Eloquent model and Query builder for Laravel (Casloquent)

WARNING: This is a work in progress... not ready for usage yet.

Installation

Laravel version Compatibility

Laravel	Package
5.4.x - 5.5.x	dev-master

Make sure you have the Cassandra PHP driver installed (version 1.2+). You can find more information at http://datastax.github.io/php-driver/.

Installation using composer:

composer require lroman242/laravel-cassandra

Laravel

And add the service provider in config/app.php:

lroman242\LaravelCassandra\CassandraServiceProvider::class,

The service provider will register a cassandra database extension with the original database manager. There is no need to register additional facades or objects. When using cassandra connections, Laravel will automatically provide you with the corresponding cassandra objects.

For usage outside Laravel, check out the Capsule manager and add:

$capsule->getDatabaseManager()->extend('cassandra', function($config)
{
    return new lroman242\LaravelCassandra\Connection($config);
});

Lumen

Add next lines to your bootstrap.php

    $app->configure('database');

    $app->register(lroman242\LaravelCassandra\CassandraServiceProvider::class);

Configuration

Change your default database connection name in config/database.php:

'default' => env('DB_CONNECTION', 'cassandra'),

And add a new cassandra connection:

'cassandra' => [
    'driver'          => 'cassandra',
    'host'            => env('DB_HOST', 'localhost'),
    'port'            => env('DB_PORT', 9042),
    'keyspace'        => env('DB_DATABASE'),
    'username'        => env('DB_USERNAME'),
    'password'        => env('DB_PASSWORD'),
    'page_size'       => env('DB_PAGE_SIZE', 5000),
    'consistency'     => Cassandra::CONSISTENCY_LOCAL_ONE,
    'timeout'         => null,
    'connect_timeout' => 5.0,
    'request_timeout' => 12.0,
],

You can connect to multiple servers with the following configuration:

'cassandra' => [
    'driver'          => 'cassandra',
    'host'            => ['192.168.0.1', '192.168.0.2'], //or '192.168.0.1,192.168.0.2'
    'port'            => env('DB_PORT', 9042),
    'keyspace'        => env('DB_DATABASE'),
    'username'        => env('DB_USERNAME'),
    'password'        => env('DB_PASSWORD'),
    'page_size'       => env('DB_PAGE_SIZE', 5000),
    'consistency'     => Cassandra::CONSISTENCY_LOCAL_ONE,
    'timeout'         => null,
    'connect_timeout' => 5.0,
    'request_timeout' => 12.0,
],

Note: you can enter all of your nodes in .env like :

# .env
DB_HOST=192.168.0.1,192.168.0.2,192.168.0.3

Note: list of available consistency levels (php constants):

Cassandra::CONSISTENCY_ANY
Cassandra::CONSISTENCY_ONE
Cassandra::CONSISTENCY_TWO
Cassandra::CONSISTENCY_THREE
Cassandra::CONSISTENCY_QUORUM
Cassandra::CONSISTENCY_ALL
Cassandra::CONSISTENCY_SERIAL
Cassandra::CONSISTENCY_QUORUM
Cassandra::CONSISTENCY_LOCAL_QUORUM
Cassandra::CONSISTENCY_EACH_QUORUM
Cassandra::CONSISTENCY_LOCAL_SERIAL
Cassandra::CONSISTENCY_LOCAL_ONE

Note: you can set specific consistency level according to the query using options

Eloquent

Supported most of eloquent query build features, events, fields access.

    $users = User::all();
    
    $user = User::where('email', 'tester@test.com')->first();
    
    $user = User::find(new \Cassandra\Uuid("7e4c27e2-1991-11e8-accf-0ed5f89f718b"))

Relations - NOT SUPPORTED

Query Builder

The database driver plugs right into the original query builder. When using cassandra connections, you will be able to build fluent queries to perform database operations.

$users = DB::table('users')->get();

$user = DB::table('users')->where('name', 'John')->first();

If you did not change your default database connection, you will need to specify it when querying.

$user = DB::connection('cassandra')->table('users')->get();

Default use of get method of query builder will call chunked fetch from database. Chunk size can be configured on config file ( 'page_size' => env('DB_PAGE_SIZE', 5000)) or with additional query builder`s method setPageSize.

$comments = Comments::setPageSize(500)->get(); // will return all comments, not 500

WARNING: Not recomended to use get if there are a lot of data in table. Use getPage instead.

Get single page of resuts

$comments = Comments::setPageSize(500)->getPage(); // will return collection with 500 results

There is an ability to set next page token what allows to get next chunk of results

$comments = Comments::setPaginationStateToken($token)->getPage();

Get next page:

$comments = $comments->nextPage();

Get next page token:

$comments = $comments->getNextPageToken();

Append collection with next page`s result:

$comments->appendNextPage();

Check if it is last page:

$comments->isLastPage();

Get raw cassandra response for current page (\Cassandra\Rows):

$rows = $commants->getRows();

Read more about the query builder on http://laravel.com/docs/queries

Examples

store users data to csv

$users = User::setPageSize(1000)->getPage();
while(!$users->isLastPage()) {
    foreach($users as $user) {
        // here you can write a lines to csv file
    }
    
    $users = $users->nextPage();
}

Simple api to make Load more as paggination on page

public function getComments(Request $request) {
    ...
    
    $comments = Comment::setPageSize(50)
        ->setPaginationStateToken($request->get('nextPageToken', null)
        ->getPage();
    
    ...
    
    return response()->json([
        ...
        'comments' => $comments,
        'nextPageToken' => !$comments->isLastPage() ? $comments->getNextPageToken() : null,
        ...
    ]);
}

If you use cassandra materialized views you can easily use it with eloquent models

$users = User::from('users_by_country_view')->where('country', 'USA')->get();

TODO:

full support of composite primary key
improved model update
full test coverage
fix diff between \Cassandra\Date with Carbon

fuitad / laravel-cassandra

Maintainers

Details