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
    Definition Classes
    skunk
  • package data
    Definition Classes
    skunk
  • package exception
    Definition Classes
    skunk
  • 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.

    Definition Classes
    skunk
  • package syntax
    Definition Classes
    skunk
  • package util
    Definition Classes
    skunk
  • AppliedFragment
  • Channel
  • Codec
  • Command
  • Cursor
  • Decoder
  • Encoder
  • Fragment
  • PreparedCommand
  • PreparedQuery
  • Query
  • SSL
  • Session
  • SqlState
  • Statement
  • Transaction
  • Void
  • implicits
  • ~

trait Session[F[_]] extends AnyRef

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.

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

Abstract Value Members

  1. abstract def channel(name: Identifier): Channel[F, String, String]

    A named asynchronous channel that can be used for inter-process communication.

  2. abstract def describeCache: Cache[F]

    Each session has access to the pool-wide cache of all statements that have been checked via the Describe protocol, which allows us to skip subsequent checks.

    Each session has access to the pool-wide cache of all statements that have been checked via the Describe protocol, which allows us to skip subsequent checks. Users can inspect and clear the cache through this accessor.

  3. abstract def execute(command: Command[Void]): F[Completion]

    Execute a non-parameterized command and yield a Completion.

    Execute a non-parameterized command and yield a Completion. If you have parameters use prepare instead.

  4. abstract def execute[A](query: Query[Void, A]): F[List[A]]

    Execute a non-parameterized query and yield all results.

    Execute a non-parameterized query and yield all results. If you have parameters or wish to limit returned rows use prepare instead.

  5. abstract def option[A](query: Query[Void, A]): F[Option[A]]

    Execute a non-parameterized query and yield at most one row, raising an exception if there are more.

    Execute a non-parameterized query and yield at most one row, raising an exception if there are more. If you have parameters use prepare instead.

  6. abstract def parameter(key: String): Stream[F, String]

    Stream (possibly empty) of discrete values for the specified key, via parameters.

  7. abstract def parameters: Signal[F, Map[String, String]]

    Signal representing the current state of all Postgres configuration variables announced to this session.

    Signal representing the current state of all Postgres configuration variables announced to this session. These are sent after authentication and are updated asynchronously if the runtime environment changes. The current keys are as follows (with example values), but these may change with future releases so you should be prepared to handle unexpected ones.

    Map(
  "application_name"            -> "",
  "client_encoding"             -> "UTF8",
  "DateStyle"                   -> "ISO, MDY",
  "integer_datetimes"           -> "on",       // cannot change after startup
  "IntervalStyle"               -> "postgres",
  "is_superuser"                -> "on",
  "server_encoding"             -> "UTF8",     // cannot change after startup
  "server_version"              -> "9.5.3",    // cannot change after startup
  "session_authorization"       -> "postgres",
  "standard_conforming_strings" -> "on",
  "TimeZone"                    -> "US/Pacific",
)
  8. abstract def pipe[A](command: Command[A]): Pipe[F, A, Completion]

    Transform a Command into a Pipe from inputs to Completions.

  9. abstract def prepare[A](command: Command[A]): Resource[F, PreparedCommand[F, A]]

    Prepare an INSERT, UPDATE, or DELETE command that returns no rows.

    Prepare an INSERT, UPDATE, or DELETE command that returns no rows. The resulting PreparedCommand can be executed multiple times with different arguments.

  10. abstract def prepare[A, B](query: Query[A, B]): Resource[F, PreparedQuery[F, A, B]]

    Resource that prepares a query, yielding a PreparedQuery which can be executed multiple times with different arguments.

  11. abstract def transaction[A](isolationLevel: TransactionIsolationLevel, accessMode: TransactionAccessMode): Resource[F, Transaction[F]]

    Resource that wraps a transaction block.

    Resource that wraps a transaction block. It has the ability to specify a non-default isolation level and access mode.

    See also

    Session#transaction for more information

  12. abstract def transaction[A]: Resource[F, Transaction[F]]

    Resource that wraps a transaction block.

    Resource that wraps a transaction block. A transaction is begun before entering the use block, on success the block is executed, and on exit the following behavior holds.

    • If the block exits normally, and the session transaction status is
      • Active, then the transaction will be committed.
      • Idle, then this means the user terminated the transaction explicitly inside the block and there is nothing to be done.
      • Error then this means the user encountered and handled an error but left the transaction in a failed state, and the transaction will be rolled back.
    • If the block exits due to cancellation or an error and the session transaction status is not Idle then the transaction will be rolled back and any error will be re-raised.
  13. abstract def transactionStatus: Signal[F, TransactionStatus]

    Signal representing the current transaction status.

  14. abstract def typer: Typer
  15. abstract def unique[A](query: Query[Void, A]): F[A]

    Execute a non-parameterized query and yield exactly one row, raising an exception if there are more or fewer.

    Execute a non-parameterized query and yield exactly one row, raising an exception if there are more or fewer. If you have parameters use prepare instead.

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... ) @native()
  6. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  7. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  8. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  9. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  10. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  11. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  12. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  13. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  14. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  15. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  16. def toString(): String
    Definition Classes
    AnyRef → Any
  17. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  18. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  19. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... ) @native()

Inherited from AnyRef

Inherited from Any

Queries

A query is any SQL statement that returns rows; i.e., any SELECT or VALUES query, or an INSERT, UPDATE, or DELETE command that returns rows via RETURNING. Parameterized queries must first be prepared, then can be executed many times with different arguments. Non-parameterized queries can be executed directly.

Commands

A command is any SQL statement that cannot return rows. Parameterized commands must first be prepared, then can be executed many times with different arguments. Commands without parameters can be executed directly.

Transactions

Users can manipulate transactions directly via commands like BEGIN and COMMIT, but dealing with cancellation and error conditions can be complicated and repetitive. Skunk provides managed transaction blocks to make this easier.

Channels

Session Environment

The Postgres session has a dynamic environment that includes a configuration map with keys like TimeZone and server_version, as well as a current TransactionStatus. These can change asynchronously and are exposed as Signals. Note that any Stream based on these signals is only valid for the lifetime of the Session.

Ungrouped