arangodb-scala-driver
Idiomatic ArangoDB driver for Scala as Tagless-Final DSL.
This library is under heavy development until v1.0.0 and therefore not ready for production!
Example
Example app using cats.effect.IO
as effect type:
import cats.effect._
import cats.implicits._
import ch.acmesoftware.arangodbscaladriver._
import scala.concurrent.ExecutionContext.Implicits.global
case class Test(_key: String, name: String)
object Test {
// Use DocumentCodec.derive[T] from one of the supported json libs
// or implement a codec using DocumentCodec.of[T]
implicit val codec: DocumentCodec[Test] = ???
}
object Main extends IOApp {
def run(args: List[String]): IO[ExitCode] = for {
// connect to server
arango <- ArangoDBBuilder.interpreter[IO].build("http://localhost", 8529)
// get or create database instance
db <- arango.db("myDb")
// get or create collection
collection <- db.collection("myCollection")
// add document to collection
_ <- collection.insertDocument(Test("key-1234", "Frank"))
// delete document
deleted <- collection.deleteDocument[Test]("key-1234")
// output name of deleted document
_ <- IO{ println(deleted.getOld.name) }
res <- IO.pure(ExitCode.Success)
} yield res
}
Features
- Tagless final DSL. Choose your own effect type.
- Scala
2.11
,2.12
and2.13 (planned)
- Wraps the official arangodb-java-driver-async and therefore supports a wide range of ArangoDB versions
- Fully async & non-blocking (just provide custom
ExecutionContext
to do so) - Supports Scala types like
Option[T]
,Iterable[T]
, etc. - Simple case class mapping by using third-party JSON library of choice
Usage
Installation
Add dependency to SBT build:
libraryDependencies ++= Seq(
"ch.acmesoftware" %% "arangodb-scala-driver" % version
)
Scaladoc
The full scaladoc can be found here
Keep reading for examples & explanations
Document Codecs
A document codec is needed to serialize/deserialize JSON, which is in turn used by ArangoDB. You can provide an implicit DocumentCodec
in two different ways:
By using one of the supported JSON libs
Add the appropriate dependency for the json lib you like:
libraryDependencies ++= Seq(
// ...
"ch.acmesoftware" %% "arangodb-scala-driver-circe" % version
)
Add the imports:
import ch.acmesoftware.arangodbscaladriver._
// circe support
import ch.acmesoftware.arangodbscaladriver.circe._
// derive codec by using an implicit circe `Encoder[Test]` and `Decoder[Test]`
implicit val codec = DocumentCodec.derive[Test]
By implementing it (not recommended)
import ch.acmesoftware.arangodbscaladriver._
case class Test(name: String)
DocumentCodec.of[Test](
e => s"""{ name: "${e.name}" }""",
str => Left(new RuntimeException("Not deserializable"))
)
About
Design
The complete library is designed as a tagless final DSL. Therefore, the Effect type (F[_]
) can be virtually everything which satisfies cats.effect.Sync[F]
. In the examples, cats.effect.IO
is used.
Beside that, one key point during API design was to keep is as similar as possible to arangodb-driver-java. This simplifies documentation, usability and the upgrade path for future ArangoDB versions.
In the examples, the global Scala ExecutionContext
is used. For production purposes, please create your own and pass it either implicitly or explicit.
Versioning
The lib follows semantic versioning while majors can be mapped to the underlying ArangoDB driver version:
Library Version | ArangoDB Driver Version |
---|---|
0.x.x | 5.x.x |
1.x.x | 5.x.x |
Disclaimer
This library is released under the terms of the MIT License by ACME Software Solutions GmbH. There is no legal relationship to ArangoDB Inc., ArangoDB GmbH, nor any of their employees. Please visit arangodb.com for more information.