Skip to content

Latest commit

 

History

History
168 lines (138 loc) · 5.91 KB

gettingstarted.md

File metadata and controls

168 lines (138 loc) · 5.91 KB
Raw

Adding rdbc to your project

rdbc is just an API — to actually use it as a database client you need an implementation called a driver. So — to use rdbc in your project you need to include two dependencies, one for the API, and one for a driver. This documentation doesn't describe any particular driver — you should be able to find artifact names you need to include in your build definition in the driver's documentation. For your convenience, however, Drivers page lists available drivers grouped by a database engine they support.

rdbc JARs are published to Maven Central repository. The API is currently available for Scala 2.11 and 2.12 and requires Java 8 runtime or newer.

SBT

For sbt projects, add the following to build.sbt:

libraryDependencies ++= Vector(
  "io.rdbc" %% "rdbc-api-scala" % "{{version}}",
  //here goes the driver dependency
)

Gradle

For Gradle projects, add the following to the dependencies section of build.gradle:

Scala 2.12

compile group: 'io.rdbc', name: 'rdbc-api-scala_2.12', version: '{{version}}'
compile //here goes the driver dependency

Scala 2.11

compile group: 'io.rdbc', name: 'rdbc-api-scala_2.11', version: '{{version}}'
compile //here goes the driver dependency

Maven

For Maven projects, add the following to the dependencies element of pom.xml:

Scala 2.12

<dependency>
  <groupId>io.rdbc</groupId>
  <artifactId>rdbc-api-scala_2.12</artifactId>
  <version>{{version}}</version>
</dependency>
<dependency>
  <!-- here goes the driver dependency -->
</dependency>

Scala 2.11

<dependency>
  <groupId>io.rdbc</groupId>
  <artifactId>rdbc-api-scala_2.11</artifactId>
  <version>{{version}}</version>
</dependency>
<dependency>
  <!-- here goes the driver dependency -->
</dependency>

Working with Scala Futures

Since all rdbc API methods that perform I/O return Scala's Futures you'll need a knowledge on how to write asynchronous code using them. Throughout this documentation it is assumed that the reader has a basic knowledge about Future trait. If you're new to this concept you may find these resources useful:

A "Hello world" application

It's time for a small but complete example of rdbc API usage. A snippet below inserts a "Hello world!" greeting into a messages database table.

A table with the following definition is assumed to exist:

create table messages(txt varchar(100))

And here's the actual code snippet:

#!scala
import io.rdbc.sapi._

import scala.concurrent.ExecutionContext.Implicits.global
import scala.concurrent.duration._
import scala.concurrent.{Await, Future}
import scala.util.{Failure, Success}

object HelloRdbc extends App {

  val connFactory: ConnectionFactory = ???

  val greeting = "Hello World!"
  val insertFut: Future[Long] = connFactory.withConnection { conn =>
    conn
      .statement(sql"insert into messages(txt) values ($greeting)")
      .executeForRowsAffected()
  }.andThen {
    case Success(count) => println(s"inserted $count greeting(s)")
    case Failure(ex) => ex.printStackTrace()
  }

  Await.ready(
    insertFut.transformWith(_ => connFactory.shutdown()),
    10.seconds
  )
}

In this very simple application:

  • At line 10 a ConnectionFactory coming from a driver package should be instantiated. Each rdbc driver provides an implementation of this trait that allows to estabilish a connection to a database. ConnectionFactory implementation and classes needed for its configuration should be the only classes directly used from the driver package.

  • At line 13 a connection to the database is requested to be estabilished - when that happens, a function passed as a code block is executed.

  • In this code block, at line 15 a prepared statement is requested to be created using a sql string interpolator which passes a greeting string argument to it.

  • The statement is requested to be executed at line 16 and to return number of affected rows.

  • When the database operation finishes and the connection is released, at line 17 the Future's result is handled: number of affected rows is printed in case of a success or a stack trace is printed in case of an error.

  • None of the database calls block the executing thread - all of them return Futures that are then chained. The only statement that blocks starts at line 22 when the application waits for operations requested earlier to complete. Because this demo is just a simple console application, we need to block the thread somewhere to wait for a moment that the application can exit.

Scaladoc

You can browse Scaladoc using javadoc.io site here. The site allows to switch between Scala versions and rdbc versions.