Packages

  • package root
    Definition Classes
    root
  • package skunk

    Skunk is a functional data access layer for Postgres.

    Skunk is a functional data access layer for Postgres.

    Design principles:

    • Skunk doesn't use JDBC. It speaks the Postgres wire protocol. It will not work with any other database back end.
    • Skunk is asynchronous all the way down, via cats-effect, fs2, and ultimately nio. The high-level network layers (Protocol and Session) are safe to use concurrently.
    • Serialization to and from schema types is not typeclass-based, so there are no implicit derivations. Codecs are explicit, like parser combinators.
    • I'm not sweating arity abstraction that much. Pass a ~ b ~ c for three args and Void if there are no args. This may change in the future but it's fine for now.
    • Skunk uses Resource for lifetime-managed objects, which means it takes some discipline to avoid leaks, especially when working concurrently. May or may not end up being problematic.
    • I'm trying to write good Scaladoc this time.

    A minimal example follows. We construct a Resource that yields a Session, then use it.

    package example

import cats.effect._
import skunk._
import skunk.implicits._
import skunk.codec.numeric._

object Minimal extends IOApp {

  val session: Resource[IO, Session[IO]] =
    Session.single(
      host     = "localhost",
      port     = 5432,
      user     = "postgres",
      database = "world",
    )

  def run(args: List[String]): IO[ExitCode] =
    session.use { s =>
      for {
        n <- s.unique(sql"select 42".query(int4))
        _ <- IO(println(s"The answer is $n."))
      } yield ExitCode.Success
    }

}

    Continue reading for an overview of the library. It's pretty small.

    Definition Classes
    root
  • package codec
  • package data
  • package exception
  • package net

    Skunk network stack, starting with BitVectorSocket at the bottom and ending with Protocol at the top (Session delegates all its work to Protocol).

    Skunk network stack, starting with BitVectorSocket at the bottom and ending with Protocol at the top (Session delegates all its work to Protocol). Everything is non-blocking.

  • package syntax
  • package util
  • AppliedFragment
  • Channel
  • Codec
  • Command
  • Cursor
  • Decoder
  • Encoder
  • Fragment
  • PreparedCommand
  • PreparedQuery
  • Query
  • SSL
  • Session
  • SqlState
  • Statement
  • Transaction
  • Void
  • feature
  • featureFlags
  • implicits
  • ~
p

skunk

package skunk

Skunk is a functional data access layer for Postgres.

Design principles:

  • Skunk doesn't use JDBC. It speaks the Postgres wire protocol. It will not work with any other database back end.
  • Skunk is asynchronous all the way down, via cats-effect, fs2, and ultimately nio. The high-level network layers (Protocol and Session) are safe to use concurrently.
  • Serialization to and from schema types is not typeclass-based, so there are no implicit derivations. Codecs are explicit, like parser combinators.
  • I'm not sweating arity abstraction that much. Pass a ~ b ~ c for three args and Void if there are no args. This may change in the future but it's fine for now.
  • Skunk uses Resource for lifetime-managed objects, which means it takes some discipline to avoid leaks, especially when working concurrently. May or may not end up being problematic.
  • I'm trying to write good Scaladoc this time.

A minimal example follows. We construct a Resource that yields a Session, then use it.

package example

import cats.effect._
import skunk._
import skunk.implicits._
import skunk.codec.numeric._

object Minimal extends IOApp {

  val session: Resource[IO, Session[IO]] =
    Session.single(
      host     = "localhost",
      port     = 5432,
      user     = "postgres",
      database = "world",
    )

  def run(args: List[String]): IO[ExitCode] =
    session.use { s =>
      for {
        n <- s.unique(sql"select 42".query(int4))
        _ <- IO(println(s"The answer is $n."))
      } yield ExitCode.Success
    }

}

Continue reading for an overview of the library. It's pretty small.

Source
package.scala
Linear Supertypes
TwiddleCompat, AnyRef, Any
Ordering
  1. Grouped
  2. Alphabetic
  3. By Inheritance
Inherited
  1. skunk
  2. TwiddleCompat
  3. AnyRef
  4. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. type *:[A, B <: Tuple] = ::[A, B]
    Definition Classes
    TwiddleCompat
  2. sealed trait AppliedFragment extends AnyRef

    A fragment applied to its argument, yielding an existentially-typed fragment + argument pair that can be useful when constructing dynamic queries in application code.

    A fragment applied to its argument, yielding an existentially-typed fragment + argument pair that can be useful when constructing dynamic queries in application code. Applied fragments must be deconstructed in order to prepare and execute.

  3. trait Channel[F[_], A, B] extends Pipe[F, A, Unit]

    A channel that can be used for inter-process communication, implemented in terms of LISTEN and NOTIFY.

    A channel that can be used for inter-process communication, implemented in terms of LISTEN and NOTIFY. All instances start life as a Channel[F, String, Notification] but can be mapped out to different input and output types. See the linked documentation for more information on the transactional semantics of these operations.

    See also

    LISTEN

    NOTIFY

  4. trait Codec[A] extends Encoder[A] with Decoder[A]

    Symmetric encoder and decoder of Postgres text-format data to and from Scala types.

  5. final case class Command[A](sql: String, origin: Origin, encoder: Encoder[A]) extends Statement[A] with Product with Serializable

    SQL and parameter encoder for a statement that returns no rows.

    SQL and parameter encoder for a statement that returns no rows. We assume that sql has the same number of placeholders of the form $1, $2, etc., as the number of slots encoded by encoder, and that the parameter types specified by encoder are consistent with the schema. The check methods on Session provide a means to verify this assumption.

    You can construct a Command directly, although it is more typical to use the sql interpolator.

    sql"INSERT INTO foo VALUES ($int2, $varchar)".command // Command[(Short, String)]
    sql

    A SQL statement returning no rows.

    encoder

    An encoder for all parameters $1, $2, etc., in sql.

    See also

    StringContextOps for information on the sql interpolator.

    Session for information on executing a Command.

  6. trait Cursor[F[_], A] extends AnyRef

    An open cursor from which rows can be fetched, valid during the lifetime its defining Session.

    An open cursor from which rows can be fetched, valid during the lifetime its defining Session. You can use this mechanism to implement chunked reads and paged results, although it is ofen more pleasant to use a Cursor-backed Stream, as produced by PreparedQuery#stream.

  7. trait Decoder[A] extends AnyRef

    Decoder of Postgres text-format data into Scala types.

  8. type EmptyTuple = HNil
    Definition Classes
    TwiddleCompat
  9. trait Encoder[A] extends AnyRef

    Encoder of Postgres text-format data from Scala types.

  10. final case class Fragment[A](parts: List[Either[String, State[Int, String]]], encoder: Encoder[A], origin: Origin) extends (A) ⇒ AppliedFragment with Product with Serializable

    A composable, embeddable hunk of SQL and typed parameters (common precursor to Command and Query).

    A composable, embeddable hunk of SQL and typed parameters (common precursor to Command and Query). Although it is possible to construct a Fragment directly it is more typical to use the sql interpolator.

  11. trait PreparedCommand[F[_], A] extends AnyRef

    A prepared command, valid for the life of its defining Session.

  12. trait PreparedQuery[F[_], A, B] extends AnyRef

    A prepared query, valid for the life of its originating Session.

  13. final case class Query[A, B](sql: String, origin: Origin, encoder: Encoder[A], decoder: Decoder[B], isDynamic: Boolean = false) extends Statement[A] with Product with Serializable

    SQL, parameter encoder, and row decoder for a statement that returns rows.

    SQL, parameter encoder, and row decoder for a statement that returns rows. We assume that sql has the same number of placeholders of the form $1, $2, etc., as the number of slots encoded by encoder, that sql selects the same number of columns are the number of slots decoded by decoder, and that the parameter and column types specified by encoder and decoder are consistent with the schema. The check methods on Session provide a means to verify this assumption.

    You can construct a Query directly, although it is more typical to use the sql interpolator.

    sql"SELECT name, age FROM person WHERE age > $int2".query(varchar *: int2) // Query[Short, (String, Short)]
    sql

    A SQL statement returning no rows.

    origin

    The Origin where the sql was defined, if any.

    encoder

    An encoder for all parameters $1, $2, etc., in sql.

    decoder

    A decoder for selected columns.

    See also

    StringContextOps for information on the sql interpolator.

    Session for information on executing a Query.

  14. abstract class SSL extends AnyRef
  15. trait Session[F[_]] extends AnyRef

    Represents a live connection to a Postgres database.

    Represents a live connection to a Postgres database. Operations provided here are safe to use concurrently. Note that this is a lifetime-managed resource and as such is invalid outside the scope of its owning Resource, as are any streams constructed here. If you start an operation be sure to join its Fiber before releasing the resource.

    See the companion object for information on obtaining a pooled or single-use instance.

  16. type SessionPool[F[_]] = Resource[F, Resource[F, Session[F]]]
  17. sealed abstract class SqlState extends EnumEntry

    Enumerated type of Postgres error codes.

    Enumerated type of Postgres error codes. See the companion object for more information.

  18. trait Statement[A] extends AnyRef
  19. type Strategy = skunk.util.Typer.Strategy
  20. trait Transaction[F[_]] extends AnyRef

    Control methods for use within a transaction block.

    Control methods for use within a transaction block. An instance is provided when you call Session.transaction(...).use.

    See also

    Session#transaction for information on default commit/rollback behavior

  21. type Tuple = HList
    Definition Classes
    TwiddleCompat
  22. sealed trait Void extends AnyRef

    A singly-inhabited type representing arguments to a parameterless statement.

  23. type ~[+A, +B] = (A, B)

    Infix alias for (A, B) that provides convenient syntax for left-associated HLists.

Value Members

  1. val *:: ::.type
    Definition Classes
    TwiddleCompat
    Annotations
    @inline()
  2. val EmptyTuple: EmptyTuple
    Definition Classes
    TwiddleCompat
    Annotations
    @inline()
  3. val Strategy: skunk.util.Typer.Strategy.type
  4. val Tuple: HList.type
    Definition Classes
    TwiddleCompat
    Annotations
    @inline()
  5. implicit def hlistToTuple[L <: Tuple, T](l: L)(implicit tupler: shapeless.ops.hlist.Tupler.Aux[L, T]): T
    Definition Classes
    TwiddleCompat
  6. implicit def toTupleOps[T <: Tuple](t: T): TupleOps[T]
    Definition Classes
    TwiddleCompat
  7. implicit def tuple10ToHList[A, B, C, D, E, F, G, H, I, J](t: (A, B, C, D, E, F, G, H, I, J)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, EmptyTuple]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  8. implicit def tuple11ToHList[A, B, C, D, E, F, G, H, I, J, K](t: (A, B, C, D, E, F, G, H, I, J, K)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, EmptyTuple]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  9. implicit def tuple12ToHList[A, B, C, D, E, F, G, H, I, J, K, L](t: (A, B, C, D, E, F, G, H, I, J, K, L)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, EmptyTuple]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  10. implicit def tuple13ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M](t: (A, B, C, D, E, F, G, H, I, J, K, L, M)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, EmptyTuple]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  11. implicit def tuple14ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M, N](t: (A, B, C, D, E, F, G, H, I, J, K, L, M, N)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, *:[N, EmptyTuple]]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  12. implicit def tuple15ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O](t: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, *:[N, *:[O, EmptyTuple]]]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  13. implicit def tuple16ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P](t: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, *:[N, *:[O, *:[P, EmptyTuple]]]]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  14. implicit def tuple17ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q](t: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, *:[N, *:[O, *:[P, *:[Q, EmptyTuple]]]]]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  15. implicit def tuple18ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R](t: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, *:[N, *:[O, *:[P, *:[Q, *:[R, EmptyTuple]]]]]]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  16. implicit def tuple19ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S](t: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, *:[N, *:[O, *:[P, *:[Q, *:[R, *:[S, EmptyTuple]]]]]]]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  17. implicit def tuple20ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T](t: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, *:[N, *:[O, *:[P, *:[Q, *:[R, *:[S, *:[T, EmptyTuple]]]]]]]]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  18. implicit def tuple21ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U](t: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, *:[N, *:[O, *:[P, *:[Q, *:[R, *:[S, *:[T, *:[U, EmptyTuple]]]]]]]]]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  19. implicit def tuple22ToHList[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V](t: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, *:[J, *:[K, *:[L, *:[M, *:[N, *:[O, *:[P, *:[Q, *:[R, *:[S, *:[T, *:[U, *:[V, EmptyTuple]]]]]]]]]]]]]]]]]]]]]]
    Definition Classes
    TwiddleCompat
  20. implicit def tuple2ToHList[A, B](t: (A, B)): *:[A, *:[B, EmptyTuple]]
    Definition Classes
    TwiddleCompat
  21. implicit def tuple3ToHList[A, B, C](t: (A, B, C)): *:[A, *:[B, *:[C, EmptyTuple]]]
    Definition Classes
    TwiddleCompat
  22. implicit def tuple4ToHList[A, B, C, D](t: (A, B, C, D)): *:[A, *:[B, *:[C, *:[D, EmptyTuple]]]]
    Definition Classes
    TwiddleCompat
  23. implicit def tuple5ToHList[A, B, C, D, E](t: (A, B, C, D, E)): *:[A, *:[B, *:[C, *:[D, *:[E, EmptyTuple]]]]]
    Definition Classes
    TwiddleCompat
  24. implicit def tuple6ToHList[A, B, C, D, E, F](t: (A, B, C, D, E, F)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, EmptyTuple]]]]]]
    Definition Classes
    TwiddleCompat
  25. implicit def tuple7ToHList[A, B, C, D, E, F, G](t: (A, B, C, D, E, F, G)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, EmptyTuple]]]]]]]
    Definition Classes
    TwiddleCompat
  26. implicit def tuple8ToHList[A, B, C, D, E, F, G, H](t: (A, B, C, D, E, F, G, H)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, EmptyTuple]]]]]]]]
    Definition Classes
    TwiddleCompat
  27. implicit def tuple9ToHList[A, B, C, D, E, F, G, H, I](t: (A, B, C, D, E, F, G, H, I)): *:[A, *:[B, *:[C, *:[D, *:[E, *:[F, *:[G, *:[H, *:[I, EmptyTuple]]]]]]]]]
    Definition Classes
    TwiddleCompat
  28. object AppliedFragment
  29. object Channel

  30. object Codec extends TwiddleSyntax[Codec]

  31. object Command extends Serializable

  32. object Cursor

  33. object Decoder extends TwiddleSyntax[Decoder]

  34. object Encoder extends TwiddleSyntax[Encoder]

  35. object Fragment extends TwiddleSyntax[Fragment] with Serializable

  36. object PreparedCommand

  37. object PreparedQuery

  38. object Query extends Serializable

  39. object SSL extends SSLCompanionPlatform
  40. object Session

  41. object SqlState extends Enum[SqlState]

    Enumerated type of Postgres error codes.

    Enumerated type of Postgres error codes. These can be used as extractors for error handling, for example:

    doSomething.recoverWith { case SqlState.ForeignKeyViolation(ex) => ... }
    See also

    PostgreSQL Error Codes

  42. object Statement
  43. object Transaction
  44. object Void extends Void with Product with Serializable

  45. object feature
  46. object featureFlags
  47. object implicits extends ToAllOps
  48. object ~

    Companion providing unapply for ~ such that (x ~ y ~ z) match { case a ~ b ~ c => ... }.

Inherited from TwiddleCompat

Inherited from AnyRef

Inherited from Any

Queries and Commands

Skunk recognizes two classes of statements: Query, for statements that return rows; and Command, for statements that do not return rows. These values can be constructed directly but typically arise via the sql interpolator.

val q = sql"""
  SELECT id, name
  FROM   employee
  WHERE  age > $int2
""".query(int4 ~ varchar) // Query[Short, Long ~ String]

In the above example note that query parameters are specified by interpolated Encoders and column types are specified by a Decoder passed to .query. The ~ syntax constructs left-associated HLists of types and values via nested pairs. These are all described in more detail a bit further down. Commands are constructed in a similar way but have no output columns and thus no Decoder is needed.

val c = sql"""
  UPDATE employee
  SET    salary = salary * 1.05
  WHERE  id = $int8
""".command // Command[Long]

The interpolator also permits nested Fragments and interpolated constants like table names. See StringContextOps for more information on the interpolator.

Session Values

Skunk's central abstraction is the Session, which represents a connection to Postgres. From the Session we can produce prepared statements, cursors, and other resources that ultimately depend on their originating Session.

Codecs

When you construct a statement each parameter is specified via an Encoder, and row data is specified via a Decoder. In some cases encoders and decoders are symmetric and are defined together, as a Codec. There are many variants of this pattern in functional Scala libraries; this is closest in spirit to the strategy adopted by scodec.

HLists

This idea was borrowed from scodec. We use ~ to build left-associated nested pairs of values and types, and can destructure with ~ the same way.

val a: Int ~ String ~ Boolean =
  1 ~ "foo" ~ true

a match {
  case n ~ s ~ b => ...
}

Note that the ~ operation for Codec, Encoder, and Decoder is lifted. This is usually what you want. If you do need an HList of encoders you can use Tuple2.

val c: Encoder[Int ~ String ~ Boolean]
  int4 ~ bpchar ~ bit

// Unusual, but for completeness you can do it thus:
val d: Encoder[Int] ~ Encoder[String] ~ Encoder[Boolean] =
  ((int4, bpchar), bit)

It is possible that we will end up switching to shapeless.HList but this is good for now.

Companion Objects

Companion objects for the traits and classes above.

Ungrouped