Skip to content

Latest commit

 

History

History
262 lines (193 loc) · 18.6 KB

README.md

File metadata and controls

262 lines (193 loc) · 18.6 KB
Raw

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 open source, but the more adopters our projects have, the more people from our company will actively work to make them better.

phantom

Available modules

This is a table of the available modules for the various Scala versions. Not all modules are available for all versions just yet, and this is because certain dependencies have yet to be published for Scala 2.12.

Module name Scala 2.10.x Scala 2.11.x Scala 2.12.0
phantom-connectors yes yes yes
phantom-dsl yes yes yes
phantom-jdk8 yes yes yes
phantom-sbt yes no no
phantom-example yes yes no
phantom-thrift yes yes no
phantom-finagle yes yes no
phantom-streams yes yes no

Using phantom

Scala 2.10, 2.11 and 2.12 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/outworkers/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)

2.0.0 Migration guide

As a word of introduction, this guide is brand new and there may be certain elements we have currently left out. Phantom has an immense adopter base which includes many of you using the library in ways which we do not know of. 2.0.0 completely replaces fundemental aspects of the framework to provide superior performance and reliability, and we have tested back and forth to ensure the smoothest possible transition, but please feel free to report any issues via GitHub and we will fix them straight away.

  • The OSS version of phantom has as of 2.0.0 returned to the Apache V2 license and the license is here to stay.
  • All packages and dependencies are now available under the com.outworkers organisation instead of com.websudos. As part of long term re-branding efforts, we have finally felt it's time to make sure the change is consistent throughout.
  • There is a new and now completely optional Bintray resolver, Resolver.bintrayRepo("outworkers", "oss-releases"), that gives you free access to the latest cuts of our open source releases before they hit Maven Central. We assume no liability for your usage of latest cuts, but we welcome feedback and we do our best to have elaborate CI processes in place.
  • Manually defining a fromRow inside a CassandraTable is no longer required if your column types match your case class types.
  • EnumColumn is now relying entirely on Primitive.macroImpl, which means you will not need to pass in the enumeration as an argument to EnumColumn anymore. This means object enum extends EnumColumn(this, enum: MyEnum) is now simply object enum extends EnumColumn[MyEnum#Value](this)
  • All dependencies are now being published to Maven Central. This includes outworkers util and outworkers diesel, projects which have in their own right been completely open sourced under Apache V2 and made public on GitHub.
  • All dependencies on scala-reflect have been completely removed.
  • A new, macro based mechanism now performs the same auto-discovery task that reflection used to, thanks to macro-compat.
  • Index modifiers no longer require a type parameter, PartitionKey, PrimaryKey, ClusteringOrder and Index don't require the column type passed anymore.
  • KeySpaceDef has been renamed to the more appropiate CassandraConnector.
  • CassandraConnector now natively supports specifying a keyspace creation query.
  • TimeWindowCompactionStrategy is now natively supported in the CREATE/ALTER dsl.
  • Collections can now be used as part of a primary or partition key.
  • Tuples are now natively supported as valid types via TupleColumn.
  • phantom-reactivestreams is now simply called phantom-streams.
  • Database.autocreate and Database.autotruncate are now no longer accessible. Use create, createAsync, truncate and truncateAsync instead.
  • Database now requires an f-bounded type argument: class MyDb(override val connector: CassandraConnection) extends Database[MyDb](connector).
  • Automated Cassandra pagination via paging states has been moved to a new method called paginateRecord. Using fetchRecord with a PagingState is no longer possible. This is done to distinguish the underlying consumer mechanism of parsing and fetching records from Cassandra.
  • com.outworkers.phantom.dsl.context should be used instead of scala.concurrent.ExecutionContext.Implicits.global.

What got completed in Phantom 2.0.0

With the rapidly evolving requirements, Cassandra 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.

Feedback and contributions are welcome, and we are happy to prioritise any crucial features Phantom may currently be lacking.

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 arbitrary 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-example
  • Add support for Scala 2.12 in phantom-streams
  • Add support for Scala 2.12 in phantom-thrift
  • Add support for Scala 2.12 in phantom-finagle

Documentation

  • 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

The following are just some of the biggest phantom adopters, though the full list is far more comprehensive.

License and copyright

Phantom is distributed under the Apache V2 License.

  • Outworkers, Limited is the copyright holder.

  • You can use phantom in commercial products or otherwise.

  • We strongly appreciate and encourage contributions.

  • 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 - 2017 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!