/phantom

Reactive type-safe Scala driver for Cassandra/Datastax Enterprise

Primary LanguageScalaOtherNOASSERTION

phantom Build Status Coverage Status Codacy Rating Maven Central Bintray ScalaDoc Gitter

Reactive type-safe Scala driver for Apache Cassandra/Datastax Enterprise

To stay up-to-date with our latest releases and news, follow us on Twitter: @outworkers.

If you use phantom, please consider adding your company to our list of adopters. phantom is and will always be freeware, but the more adopters our projects have, the more people from our company will actively work to make them better.

phantom

Using phantom

Scala 2.10 and 2.11 releases

We publish phantom in 2 formats, stable releases and bleeding edge.

  • The stable release is always available on Maven Central and will be indicated by the badge at the top of this readme. The Maven Central badge is pointing at the latest version

  • Intermediary releases are available through our managed Bintray repository available at https://dl.bintray.com/websudos/oss-releases/. The latest version available on our Bintray repository is indicated by the Bintray badge at the top of this readme.

How phantom compares

To compare phantom to similar tools in the Scala/Cassandra category, you can read more here.

Latest versions

The latest versions are available here. The badges automatically update when a new version is released.

  • Latest stable version: Maven Central (Maven Central)
  • Bleeding edge: Bintray (OSS releases on Bintray)

Roadmap to Phantom 2.0.0

With the rapidly evolving requirements, Cassansdra releases, and competition, it was only natural we kept Phantom up to scratch. In line with a lot of user feedback, the priorities of 2.0.0 were:

  • Go back to the flexible licensing model everyone knows and loves(especially your legal department). No one wants to go through corporate litigation and licensing compliance to a build.sbt dependency, and if you've ever worked in a bank we all know it's not happening.

  • Phantom was a really fun time saving introduction years ago when it was first introduced, but since then Scala has evolved to a point where many features of more esoteric components, such as the macro API, have reached a degree of stability that we can now exploit to our great advantage: boilerplate elimitation.

  • From type parameters to keys, table class cake patterns, having to define fromRow, and a whole lot of other boilerplatey items, we have eliminated them one by one, reducing the amount of code you need to type to make it all work. The future looks even brighter, as we plan on fully eliminating the mapping DSL very shortly in favour of even more lightweight techniques.

Phantom's next major release is slowly approaching completion, and if you would like to know more about what's to come and about what we have in store for you next, have a look at the below list. Feedback and contributions are welcome, and we are happy to prioritise any crucial features Phantom may currently be lacking.

If the boxes are checked it means this is already complete on the gigantic 2.0.0 pull request. This is initial "in progres" migration guide to Phantom 2.0.0 that should give you some more detail into the changes made.

Intermediary releases of phantom 2.0.x are already available via Resolver.bintrayRepo("outworkers", "oss-releases") and the latest version is Bintray .

Licensing and distribution

  • Revert all Outworkers projects and all their dependencies to the Apache V2 License.
  • Publish outworkers-util and all sub modules to Maven Central.
  • Publish outworkers-diesel and all sub modules to Maven Central.
  • Remove all non standard resolvers from Phantom, all dependencies should build from JCenter and Maven Central by default with no custom resolvers required.
  • Change all package names and resolvers to reflect our business name change from Websudos to Outworkers.
  • Create a 1.30.x release that allows users to transition to a no custom resolver version of Phantom 1.0.x even before 2.0.0 is stable.

Macro API to replace runtime features

  • Replace the Scala reflection library with a macro that can figure out what the contents of a table are.
  • Generate the name of a table using macros.
  • Generate the primary key of a table using macros.
  • Enforce primary key restrictions on a table using a macro.
  • Generate the fromRow method of CassandraTable using a macro if the case class fields and table columns are matched.
  • Enforce a same ordering restriction for case class fields and table columns to avoid generating invalid methods with the macro.
  • Generate the fromRow if the fields match, they are in abitrary order, but there are no duplicate types.
  • Allow arbitrary inheritance and usage patterns for Cassandra tables, and resolve inheritance resolutions with macros to correctly identify desired table structures.

Tech debt

  • Correctly implement Cassandra pagination using iterators, currently setting a fetchSize on a query does not correctly propagate or consume the resulting iterator, which leads to API inconsistencies and PagingState not being set on any ResultSet.
  • Add a build matrix that will test phantom against multiple versions of Cassandra in Travis for Scala 2.11, with support for all major releases of Cassandra.
  • Bump code coverage up to 100%

Features

  • Native support for multi-tenanted environments via cached sessions.
  • Case sensitive CQL.
  • Materialized views.
  • SASI index support
  • Support for PER PARTITION LIMIT in SelectQuery.
  • Support for GROUP BY in SelectQuery.

Scala 2.12 support

  • Add support for Scala 2.12 in the util library, remove all dependencies that don't comply.
  • Add support for Scala 2.12 in the diesel-engine.
  • Add support for Scala 2.12 in phantom-dsl
  • Add support for Scala 2.12 in phantom-connectors
  • Add support for Scala 2.12 in phantom-reactivestreams
  • Add support for Scala 2.12 in phantom-finagle

Documentatiom

  • Offer a complete migration guide for transitioning to Phantom 2.0.0. Guide here.
  • Move documentation back to the docs folder.
  • Add a documentation website on the main page.
  • Create a navigator that allows viewing the documentation at a particular point in time.

Tutorials on phantom and Cassandra

For ease of use and far better management of documentation, we have decided to export the README.md to a proper Wiki page, now available here.

The following are the current resources available for learning phantom, outside of tests which are very useful in highlighting all the possible features in phantom and how to use them.

This is a list of resources to help you learn phantom and Cassandra:

Issues and questions

back to top

We love Cassandra to bits and use it in every bit of our stack. phantom makes it super trivial for Scala users to embrace Cassandra.

Cassandra is highly scalable and it is by far the most powerful database technology available, open source or otherwise.

Phantom is built on top of the Datastax Java Driver, which does most of the heavy lifting.

We are very happy to help implement missing features in phantom, answer questions about phantom, and occasionally help you out with Cassandra questions! Please use GitHub for any issues or bug reports.

Adopters

Some of the companies using phantom:

License and copyright

Phantom is freeware software and uses a proprietary license that in plain English says the following:

  • Phantom is the intellectual property of Outworkers, it is not provided under an OSS license.

  • You can use phantom in commercial products or otherwise, so long as you use one of the official versions available on Bintray or Maven Central.

  • You are not allowed to distribute altered copies of phantom in binary form.

  • You cannot offer paid for training on phantom unless you are a direct partner to Outworkers and you have a written intellectual property agreement in place with us.

  • If you simply have a Build.scala or build.sbt dependency on phantom, you have nothing to worry about.

  • All paid for features are published and sold separately as phantom-pro, everything that is currently available for free will remain so forever.

If you would like our help with any new content or initiatives, we'd love to hear about it!

Contributors

back to top

Phantom was developed at outworkers as an in-house project. All Cassandra integration at outworkers goes through phantom, and nowadays it's safe to say most Scala/Cassandra users in the world rely on phantom.

Copyright

back to top

Special thanks to Viktor Taranenko from WhiskLabs, who gave us the original idea.

Copyright © 2013 - 2016 outworkers.

Contributing to phantom

back to top

Contributions are most welcome! Use GitHub for issues and pull requests and we will happily help out in any way we can!