Merge pull request #4 from typesafehub/wip/2.0-improvements

Some improvements to Hello Slick, still targeting 2.0

Author: szeiger

build.sbt

@@ -10,5 +10,5 @@ libraryDependencies ++= List(
   "com.typesafe.slick" %% "slick" % "2.0.0",
   "org.slf4j" % "slf4j-nop" % "1.6.4",
   "com.h2database" % "h2" % "1.3.170",
-  "org.scalatest" %% "scalatest" % "2.0"
+  "org.scalatest" %% "scalatest" % "2.0" % "test"
 )

src/main/scala/CaseClassMapping.scala

@@ -5,7 +5,8 @@ object CaseClassMapping extends App {
   // the base query for the Users table
   val users = TableQuery[Users]
 
-  Database.forURL("jdbc:h2:mem:hello", driver = "org.h2.Driver").withSession { implicit session =>
+  val db = Database.forURL("jdbc:h2:mem:hello", driver = "org.h2.Driver")
+  db.withSession { implicit session =>
 
     // create the schema
     users.ddl.create
@@ -27,6 +28,7 @@ class Users(tag: Tag) extends Table[User](tag, "USERS") {
   def id = column[Int]("ID", O.PrimaryKey, O.AutoInc)
   // The name can't be null
   def name = column[String]("NAME", O.NotNull)
-  // the * projection (e.g. select * ...) auto-transform the tupled column values to / from a User
+  // the * projection (e.g. select * ...) auto-transforms the tupled
+  // column values to / from a User
   def * = (name, id.?) <> (User.tupled, User.unapply)
-}
+}

src/main/scala/HelloSlick.scala

@@ -10,17 +10,19 @@ object HelloSlick extends App {
   val coffees: TableQuery[Coffees] = TableQuery[Coffees]
 
   // Create a connection (called a "session") to an in-memory H2 database
-  Database.forURL("jdbc:h2:mem:hello", driver = "org.h2.Driver").withSession { implicit session =>
+  val db = Database.forURL("jdbc:h2:mem:hello", driver = "org.h2.Driver")
+  db.withSession { implicit session =>
 
-    // Create the schema by combining the DDLs for the Suppliers and Coffees tables using the query interfaces
+    // Create the schema by combining the DDLs for the Suppliers and Coffees
+    // tables using the query interfaces
     (suppliers.ddl ++ coffees.ddl).create
 
 
     /* Create / Insert */
 
     // Insert some suppliers
     suppliers += (101, "Acme, Inc.", "99 Market Street", "Groundsville", "CA", "95199")
-    suppliers += (49, "Superior Coffee", "1 Party Place", "Mendocino", "CA", "95460")
+    suppliers += ( 49, "Superior Coffee", "1 Party Place", "Mendocino", "CA", "95460")
     suppliers += (150, "The High Ground", "100 Coffee Lane", "Meadows", "CA", "93966")
 
     // Insert some coffees (using JDBC's batch insert feature)
@@ -32,10 +34,13 @@ object HelloSlick extends App {
       ("French_Roast_Decaf", 49, 9.99, 0, 0)
     )
 
-    val allSuppliers: List[(Int, String, String, String, String, String)] = suppliers.list
+    val allSuppliers: List[(Int, String, String, String, String, String)] =
+      suppliers.list
 
     // Print the number of rows inserted
-    coffeesInsertResult foreach (numRows => println(s"Inserted $numRows rows into the Coffees table"))
+    coffeesInsertResult foreach { numRows =>
+      println(s"Inserted $numRows rows into the Coffees table")
+    }
 
 
     /* Read / Query / Select */
@@ -52,7 +57,8 @@ object HelloSlick extends App {
     /* Filtering / Where */
 
     // Construct a query where the price of Coffees is > 9.0
-    val filterQuery: Query[Coffees, (String, Int, Double, Int, Int)] = coffees.filter(_.price > 9.0)
+    val filterQuery: Query[Coffees, (String, Int, Double, Int, Int)] =
+      coffees.filter(_.price > 9.0)
 
     println("Generated SQL for filter query:\n" + filterQuery.selectStatement)
 
@@ -77,7 +83,8 @@ object HelloSlick extends App {
     /* Delete */
 
     // Construct a delete query that deletes coffees with a price less than 8.0
-    val deleteQuery: Query[Coffees,(String, Int, Double, Int, Int)] = coffees.filter(_.price < 8.0)
+    val deleteQuery: Query[Coffees,(String, Int, Double, Int, Int)] =
+      coffees.filter(_.price < 8.0)
 
     // Print the SQL for the Coffees delete query
     println("Generated SQL for Coffees delete:\n" + deleteQuery.deleteStatement)
@@ -93,27 +100,32 @@ object HelloSlick extends App {
     // Construct a new coffees query that just selects the name
     val justNameQuery: Query[Column[String], String] = coffees.map(_.name)
 
-    println("Generated SQL for query returning just the name:\n" + justNameQuery.selectStatement)
+    println("Generated SQL for query returning just the name:\n" +
+      justNameQuery.selectStatement)
 
     // Execute the query
     println(justNameQuery.list)
 
 
     /* Sorting / Order By */
 
-    val sortByPriceQuery: Query[Coffees, (String, Int, Double, Int, Int)] = coffees.sortBy(_.price)
+    val sortByPriceQuery: Query[Coffees, (String, Int, Double, Int, Int)] =
+      coffees.sortBy(_.price)
 
-    println("Generated SQL for query sorted by price:\n" + sortByPriceQuery.selectStatement)
+    println("Generated SQL for query sorted by price:\n" +
+      sortByPriceQuery.selectStatement)
 
     // Execute the query
     println(sortByPriceQuery.list)
 
 
     /* Query Composition */
 
-    val composedQuery: Query[Column[String], String] = coffees.sortBy(_.name).take(3).filter(_.price > 9.0).map(_.name)
+    val composedQuery: Query[Column[String], String] =
+      coffees.sortBy(_.name).take(3).filter(_.price > 9.0).map(_.name)
 
-    println("Generated SQL for composed query:\n" + composedQuery.selectStatement)
+    println("Generated SQL for composed query:\n" +
+      composedQuery.selectStatement)
 
     // Execute the composed query
     println(composedQuery.list)
@@ -161,4 +173,4 @@ object HelloSlick extends App {
     println(plainQuery.list)
 
   }
-}
+}

src/main/scala/InvokerMethods.scala

@@ -0,0 +1,65 @@
+import scala.slick.driver.H2Driver.simple._
+
+// Demonstrates various ways of reading data from an Invoker.
+object InvokerMethods extends App {
+
+  // A simple dictionary table with keys and values
+  class Dict(tag: Tag) extends Table[(Int, String)](tag, "INT_DICT") {
+    def key = column[Int]("KEY", O.PrimaryKey)
+    def value = column[String]("VALUE")
+    def * = (key, value)
+  }
+  val dict = TableQuery[Dict]
+
+  val db = Database.forURL("jdbc:h2:mem:invoker", driver = "org.h2.Driver")
+  db.withSession { implicit session =>
+
+    // Create the dictionary table and insert some data
+    dict.ddl.create
+    dict ++= Seq(1 -> "a", 2 -> "b", 3 -> "c", 4 -> "d", 5 -> "e")
+
+    // Define a pre-compiled parameterized query for reading all key/value
+    // pairs up to a given key.
+    val upTo = Compiled { k: Column[Int] =>
+      dict.filter(_.key <= k).sortBy(_.key)
+    }
+
+    println("List of k/v pairs up to 3 with .list")
+    println("- " + upTo(3).list)
+
+    println("IndexedSeq of k/v pairs up to 3 with .buildColl")
+    println("- " + upTo(3).buildColl[IndexedSeq])
+
+    println("Set of k/v pairs up to 3 with .buildColl")
+    println("- " + upTo(3).buildColl[Set])
+
+    println("Array of k/v pairs up to 3 with .buildColl")
+    println("- " + upTo(3).buildColl[Array])
+
+    println("All keys in an unboxed Array[Int]")
+    val allKeys = dict.map(_.key)
+    println("  " + allKeys.buildColl[Array]())
+
+    println("Stream k/v pairs up to 3 via an Iterator")
+    val it = upTo(3).iterator
+    try {
+      it.foreach { case (k, v) => println(s"- $k -> $v") }
+    } finally {
+      // Make sure to close the Iterator in case of an error. (It is
+      // automatically closed when all data has been read.)
+      it.close
+    }
+
+    println("Only get the first result, failing if there is none")
+    println("- " + upTo(3).first)
+
+    println("Get the first result as an Option, or None")
+    println("- " + upTo(3).firstOption)
+
+    println("Map of k/v pairs up to 3 with .toMap")
+    println("- " + upTo(3).toMap)
+
+    println("Combine the k/v pairs up to 3 with .foldLeft")
+    println("- " + upTo(3).foldLeft("") { case (z, (k, v)) => s"$z[$k -> $v] " })
+  }
+}

src/main/scala/Tables.scala

@@ -2,27 +2,34 @@ import scala.slick.driver.H2Driver.simple._
 import scala.slick.lifted.{ProvenShape, ForeignKeyQuery}
 
 // A Suppliers table with 6 columns: id, name, street, city, state, zip
-class Suppliers(tag: Tag) extends Table[(Int, String, String, String, String, String)](tag, "SUPPLIERS") {
-  def id: Column[Int] = column[Int]("SUP_ID", O.PrimaryKey) // This is the primary key column
+class Suppliers(tag: Tag)
+  extends Table[(Int, String, String, String, String, String)](tag, "SUPPLIERS") {
+
+  // This is the primary key column:
+  def id: Column[Int] = column[Int]("SUP_ID", O.PrimaryKey)
   def name: Column[String] = column[String]("SUP_NAME")
   def street: Column[String] = column[String]("STREET")
   def city: Column[String] = column[String]("CITY")
   def state: Column[String] = column[String]("STATE")
   def zip: Column[String] = column[String]("ZIP")
 
   // Every table needs a * projection with the same type as the table's type parameter
-  def * : ProvenShape[(Int, String, String, String, String, String)] = (id, name, street, city, state, zip)
+  def * : ProvenShape[(Int, String, String, String, String, String)] =
+    (id, name, street, city, state, zip)
 }
 
 // A Coffees table with 5 columns: name, supplier id, price, sales, total
-class Coffees(tag: Tag) extends Table[(String, Int, Double, Int, Int)](tag, "COFFEES") {
+class Coffees(tag: Tag)
+  extends Table[(String, Int, Double, Int, Int)](tag, "COFFEES") {
+
   def name: Column[String] = column[String]("COF_NAME", O.PrimaryKey)
   def supID: Column[Int] = column[Int]("SUP_ID")
   def price: Column[Double] = column[Double]("PRICE")
   def sales: Column[Int] = column[Int]("SALES")
   def total: Column[Int] = column[Int]("TOTAL")
 
-  def * : ProvenShape[(String, Int, Double, Int, Int)] = (name, supID, price, sales, total)
+  def * : ProvenShape[(String, Int, Double, Int, Int)] =
+    (name, supID, price, sales, total)
 
   // A reified foreign key relation that can be navigated to create a join
   def supplier: ForeignKeyQuery[Suppliers, (Int, String, String, String, String, String)] = 

tutorial/index.html

@@ -54,7 +54,8 @@ <h2>Database Connection</h2>
 
     <p>
         Every query that runs against the database needs a database session to run with.  The <a href="#code/src/main/scala/HelloSlick.scala" class="shortcut">HelloSlick.scala</a> file sets up a database connection and gets a session:
-        <pre><code>Database.forURL("jdbc:h2:mem:hello", driver = "org.h2.Driver").withSession { session =&gt;</code></pre>
+        <pre><code>val db = Database.forURL("jdbc:h2:mem:hello", driver = "org.h2.Driver")
+db.withSession { implicit session =&gt; ... }</code></pre>
         Note: the <code>session</code> can be implicit to avoid specifying it explicitly with every query.<br/>
 
         The <code>session</code> can now be used in the scope of the provided function to make queries to the database.  The session is automatically closed after the function completes.
@@ -69,11 +70,12 @@ <h2>Database Connection</h2>
     <h2>Creating the Schema</h2>
 
     <p>
-        Once a session is available you can use it to perform operations on the database.  To create corresponding tables from a mapping you can get the DDL via it's <code>TableQuery</code> and then call the <code>create</code> method, like:
+        Once a session is available you can use it to perform operations on the database.  To create corresponding tables from a mapping you can get the DDL via its <code>TableQuery</code> and then call the <code>create</code> method, like:
         <pre><code>suppliers.ddl.create</code></pre>
 
         Multiple DDLs can also be combined together and created, like in <a href="#code/src/main/scala/HelloSlick.scala" class="shortcut">HelloSlick.scala</a>:
         <pre><code>(suppliers.ddl ++ coffees.ddl).create</code></pre>
+        This will create all database entities and links (like foreign key references) in the correct order, even in the presence of cyclic dependencies between tables.
     </p>
 </div>
 
@@ -170,10 +172,10 @@ <h2>Computed Values</h2>
 </div>
 
 <div>
-    <h2>Manual SQL / String Interpolation</h2>
+    <h2>Plain SQL / String Interpolation</h2>
 
     <p>
-        Sometimes writing manual sql is the easiest and best way to go but we don't want to lose SQL injection protection that Slick includes.  SQL String Interpolation provides a nice API for doing this.  Start by importing the interpolation API:
+        Sometimes writing manual SQL is the easiest and best way to go but we don't want to lose SQL injection protection that Slick includes.  SQL String Interpolation provides a nice API for doing this.  Start by importing the interpolation API:
         <pre><code>import scala.slick.jdbc.StaticQuery.interpolation</code></pre>
 
         Then use the <code>sql</code> String Interpolator:
@@ -182,6 +184,8 @@ <h2>Manual SQL / String Interpolation</h2>
 
         This produces a query that can be run using the normal functions like <code>list</code>.
     </p>
+
+    <p>You can learn more about Slick's <em>Plain SQL</em> queries in the <a href="https://typesafe.com/activator/template/slick-plainsql" target="_blank">Slick Plain SQL Queries</a> template for Activator.</p>
 </div>
 
 <div>
@@ -199,15 +203,31 @@ <h2>Auto-Generated Primary Keys</h2>
 
     <p>
         The <code>Users</code> table mapping in <a href="#code/src/main/scala/CaseClassMapping.scala" class="shortcut">CaseClassMapping.scala</a> defines an id column which uses an auto-incrementing primary key:
-        <pre><code>def id = column[Int]("ID", O.PrimaryKey, O.AutoInc)</code></pre>
-        
+    <pre><code>def id = column[Int]("ID", O.PrimaryKey, O.AutoInc)</code></pre>
+
+    </p>
+</div>
+
+<div>
+    <h2>Running Queries</h2>
+
+    <p>So far you have seen the <code>Invoker</code> methods <code>.list</code> and <code>.foreach</code> being used to run a collection-valued query. There are several other useful methods which are shown in <a href="#code/src/main/scala/InvokerMethods.scala" class="shortcut">InvokerMethods.scala</a>. They are equally applicable to <em>Lifted Embedding</em> and <em>Plain SQL</em> queries.</p>
+
+    <p>Note the use of <code>Compiled</code> in this app. It is used to define a pre-compiled query that can be executed with different parameters without having to recompile the SQL statement each time. This is the prefered way of defining queries in real-world applications. It prevents the (possibly expensive) compilation each time and leads to the same SQL statement (or a small, fixed set of SQL statements) so that the database system can also reuse a previously computed execution plan. As a side-effect, all parameters are automatically turned into bind variables:
+
+    <pre><code>val upTo = Compiled { k: Column[Int] =>
+  ts.filter(_.k <= k).sortBy(_.k)
+}</code></pre>
     </p>
+
 </div>
 
 <div>
     <h2>Next Steps</h2>
 
-    Check out the full <a href="http://slick.typesafe.com/doc/2.0.0/" target="_blank">Slick docs</a>.
+    <p>Check out the full <a href="http://slick.typesafe.com/doc/2.0.1/" target="_blank">Slick manual and API docs</a>.</p>
+
+    <p>You can also find more Slick templates, contributed by both, the Slick team and the community, <a href="/home" class="shortcut">here in Activator</a>.</p>
 </div>
 
 </body>