Sq

High-level SQLite client library

import qualified Sq

Things currently supported:

• Type-safe encoding of SQL query parameters and columns (Encode, Input).
• Type-safe decoding of SQL output rows and columns (Decode, Output).
• Type-safe concurrent connections with read and write database access (Pool).
• Type-safe STM-like transactional interactions with the database, including retry-like, TVar-like, and catchSTM-like tools (Transactional, retry, Ref).
• Type-safe distinction between Read-only and read-Write things.
• Type-safe streaming and interleaving of IO with output rows (streamIO, foldIO).
• Type-safe resource management (via Acquire, see new, with, uith).
• Manual transactional migrations (migrate).
• Savepoints.
• A lot of logging.

Things not supported yet:

• Type-safe SQL.
• Probably other things.

If you have questions or suggestions, just say so at https://github.com/k0001/hs-sq/issues.

Note: This library is young and needs more testing.

Statement

data Statement (s :: Mode) i o

• A SQL statement taking a value i as input and producing rows of o values as output.
• s indicates whether the statement is Read-only or read-Write.
• Construct with readStatement or writeStatement.

Instances

Profunctor (Statement s)

Defined in Sq.Statement

Methods

dimap :: (a -> b) -> (c -> d) -> Statement s b c -> Statement s a d

lmap :: (a -> b) -> Statement s b c -> Statement s a c

rmap :: (b -> c) -> Statement s a b -> Statement s a c

(#.) :: forall a b c q. Coercible c b => q b c -> Statement s a b -> Statement s a c

(.#) :: forall a b c q. Coercible b a => Statement s b c -> q a b -> Statement s a c

Functor (Statement s i)

Defined in Sq.Statement

Methods

fmap :: (a -> b) -> Statement s i a -> Statement s i b

(<$) :: a -> Statement s i b -> Statement s i a

Show (Statement s i o)

Defined in Sq.Statement

Methods

showsPrec :: Int -> Statement s i o -> ShowS

show :: Statement s i o -> String

showList :: [Statement s i o] -> ShowS

readStatement :: Input i -> Output o -> SQL -> Statement 'Read i o

Construct a Read-only Statement.

WARNING: This library doesn't yet provide a safe way to construct Statements. You can potentially write anything in your SQL string. Don't do that.

• The SQL must be read-only.
• The SQL must contain a single statement.
• The SQL must not contain any transaction nor savepoint management statements.

writeStatement :: Input i -> Output o -> SQL -> Statement 'Write i o

Construct a Statement that can only be executed as part of a Write Transaction.

WARNING: This library doesn't yet provide a safe way to construct Statements. You can potentially write anything in your SQL string. Don't do that.

• The SQL must contain a single statement.
• The SQL must not contain any transaction nor savepoint management statements.

SQL

data SQL

Raw SQL string. Completely unchecked.

Instances

IsString SQL

Defined in Sq.Statement

Methods

fromString :: String -> SQL

Semigroup SQL

Defined in Sq.Statement

Methods

(<>) :: SQL -> SQL -> SQL

sconcat :: NonEmpty SQL -> SQL

stimes :: Integral b => b -> SQL -> SQL

Show SQL

Raw SQL string.

Defined in Sq.Statement

Methods

showsPrec :: Int -> SQL -> ShowS

show :: SQL -> String

showList :: [SQL] -> ShowS

NFData SQL

Defined in Sq.Statement

Methods

rnf :: SQL -> ()

ToMessage SQL

Defined in Sq.Statement

Methods

message :: SQL -> Message

Eq SQL

Defined in Sq.Statement

Methods

(==) :: SQL -> SQL -> Bool

(/=) :: SQL -> SQL -> Bool

Ord SQL

Defined in Sq.Statement

Methods

compare :: SQL -> SQL -> Ordering

(<) :: SQL -> SQL -> Bool

(<=) :: SQL -> SQL -> Bool

(>) :: SQL -> SQL -> Bool

(>=) :: SQL -> SQL -> Bool

max :: SQL -> SQL -> SQL

min :: SQL -> SQL -> SQL

HasField "text" SQL Text

Raw SQL string as Text.

Defined in Sq.Statement

Methods

getField :: SQL -> Text

sql :: QuasiQuoter

A QuasiQuoter for raw SQL strings.

WARNING: This doesn't check the validity of the SQL. It is offered simply because writing multi-line strings in Haskell is otherwise very annoying.

Input

data Input i

How to encode all the input to a single Statement.

• Construct with encode, IsString.
• Nest with input.
• Compose with Contravariant, Divisible, Decidable and Monoid tools.

Instances

Contravariant Input

Defined in Sq.Input

Methods

contramap :: (a' -> a) -> Input a -> Input a'

(>$) :: b -> Input b -> Input a

Decidable Input

Defined in Sq.Input

Methods

lose :: (a -> Void) -> Input a

choose :: (a -> Either b c) -> Input b -> Input c -> Input a

Divisible Input

Left-biased in case of overlapping BindingNames.

Defined in Sq.Input

Methods

divide :: (a -> (b, c)) -> Input b -> Input c -> Input a

conquer :: Input a

EncodeDefault i => IsString (Input i)

writeStatement
        "a"
        mempty
        "INSERT INTO t (x) VALUES ($a)"
   :: (EncodeDefault a)
   => Statement Write a ()

Defined in Sq.Input

Methods

fromString :: String -> Input i

Monoid (Input i)

Defined in Sq.Input

Methods

mempty :: Input i

mappend :: Input i -> Input i -> Input i

mconcat :: [Input i] -> Input i

Semigroup (Input i)

Left-biased in case of overlapping BindingNames.

Defined in Sq.Input

Methods

(<>) :: Input i -> Input i -> Input i

sconcat :: NonEmpty (Input i) -> Input i

stimes :: Integral b => b -> Input i -> Input i

NFData (Input i)

Defined in Sq.Input

Methods

rnf :: Input i -> ()

encode :: Name -> Encode i -> Input i

Encode a single input parameter. The value will be reachable from the SQL query through the specified Name, with a $ prefix.

writeStatement
        (encode "foo" encodeDefault)
        mempty
        "INSERT INTO t (a) VALUES ($foo)"
   :: (EncodeDefault x)
   => Statement Write x ()

Note that by design, this library doesn't support positional Input parameters. You must always pick a Name.

Multiple Inputs can be composed with Contravariant, Divisible, Decidable and Monoid tools.

writeStatement
        (divided (encode "foo" encodeDefault)
                 (encode "bar" encodeDefault))
        mempty
        "INSERT INTO t (a, b) VALUES ($foo, $bar)"
   :: (EncodeDefault x, EncodeDefault y)
   => Statement Write (x, y) ()

Pro-tip: Consider using the IsString instance for Input. For example, "foo" means encode "foo" encodeDefault. That is, the last example could be written as follows:

writeStatement
        (divided "foo" "bar")
        mempty
        "INSERT INTO t (a, b) VALUES ($foo, $bar)"
   :: (EncodeDefault x, EncodeDefault y)
   => Statement Write (x, y) ()

input :: Name -> Input i -> Input i

Add a prefix Name to parameters names in the given Input, separated by __

This is useful for making reusable Inputs. For example, consider the following.

data Point = Point { x :: Int, y :: Int }

pointInput :: Input Point
pointInput = contramap (\case Point x _ -> x) "x" <>
             contramap (\case Point _ y -> y) "y"

After input:

writeStatement
        (divided (input "p1" pointInput)
                 (input "p2" pointInput))
        mempty
        [sql|
          INSERT INTO vectors (ax, ay, bx, by)
          VALUES ($p1__x, $p1__y, $p2__x, $p2__y) |]
   :: Statement Write (Point, Point) ()

Encode

newtype Encode a

How to encode a single Haskell value of type a into a SQLite value.

Constructors

Encode (a -> Either ErrEncode SQLData)

Encode a value of type a as SQLData.

Ideally, the type a should be small enough that this function always returns Right. However, that can sometimes be annoying, so we allow this function to fail with ErrEncode if necessary, in which case an ErrInput exception will be eventually thrown while trying to bind the relevant Input to a Statement. Why? Because for example, not all Strings can be safely encoded as a SQLText seeing as some non-unicode characters will silently be lost in the conversion. So, we could either not have an Encoder for String at all, which would be annoying, or we could have ErrEncode as we do here in order to safely deal with those obscure corner cases.

Instances

Contravariant Encode

Defined in Sq.Encoders

Methods

contramap :: (a' -> a) -> Encode a -> Encode a'

(>$) :: b -> Encode b -> Encode a

encodeRefine :: HasCallStack => (a -> Either String b) -> Encode b -> Encode a

A convenience function for refining an Encoder through a function that may fail with a String error message. The CallStack is preserved.

If you need a more sophisticated refinement, use the Encode constructor.

class EncodeDefault a where

Default way to encode a Haskell value of type a into a single SQLite column value.

If there there exist also a DecodeDefault instance for a, then it must roundtrip with the EncodeDefault instance for a.

Methods

encodeDefault :: Encode a

Default way to encode a Haskell value of type a into a single SQLite column value.

Instances

EncodeDefault Void

This is absurd.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Void

EncodeDefault Int16

IntegerColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Int16

EncodeDefault Int32

IntegerColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Int32

EncodeDefault Int64

IntegerColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Int64

EncodeDefault Int8

IntegerColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Int8

EncodeDefault Word16

IntegerColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Word16

EncodeDefault Word32

IntegerColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Word32

EncodeDefault Word64

IntegerColumn if it fits in Int64, otherwise TextColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Word64

EncodeDefault Word8

IntegerColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Word8

EncodeDefault Builder

BlobColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Builder

EncodeDefault ByteString

BlobColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode ByteString

EncodeDefault ByteString

BlobColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode ByteString

EncodeDefault ShortByteString

BlobColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode ShortByteString

EncodeDefault SQLData

Literal SQLData Encode.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode SQLData

EncodeDefault MigrationId

Defined in Sq.Migrations

Methods

encodeDefault :: Encode MigrationId

EncodeDefault Null

NullColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Null

EncodeDefault Text

TextColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Text

EncodeDefault Builder

TextColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Builder

EncodeDefault Text

TextColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Text

EncodeDefault CalendarDiffDays

ISO8601 in a @TextColumn.

PyYmMdD

Defined in Sq.Encoders

Methods

encodeDefault :: Encode CalendarDiffDays

EncodeDefault Day

ISO-8601 in a @TextColumn.

yyyy-mm-dd

• Sorting these lexicographically in SQL corresponds to sorting them by time.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Day

EncodeDefault UTCTime

ISO8601 in a @TextColumn.

yyyy-mm-ddThh:mm:ss[.ssssssssssss]+00:00

• Sorting these lexicographically in SQL corresponds to sorting them by time.
• WARNING: SQLite date and time functions support resolution only up to milliseconds.
• WARNING: SQLite date and time functions don't support leap seconds.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode UTCTime

EncodeDefault CalendarDiffTime

ISO8601 in a @TextColumn.

PyYmMdDThHmMs[.ssssssssssss]S

• WARNING: SQLite date and time functions support resolution only up to milliseconds.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode CalendarDiffTime

EncodeDefault LocalTime

ISO8601 in a @TextColumn.

yyyy-mm-ddThh:mm:ss[.ssssssssssss]

• Sorting these lexicographically in SQL corresponds to sorting them by time.
• WARNING: SQLite date and time functions support resolution only up to milliseconds.
• WARNING: SQLite date and time functions don't support leap seconds.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode LocalTime

EncodeDefault TimeOfDay

ISO8601 in a @TextColumn.

hh:mm:ss[.ssssssssssss]

• Sorting these lexicographically in SQL corresponds to sorting them by time.
• WARNING: SQLite date and time functions support resolution only up to milliseconds.
• WARNING: SQLite date and time functions don't support leap seconds.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode TimeOfDay

EncodeDefault TimeZone

ISO8601 in a @TextColumn.

±hh:mm

Defined in Sq.Encoders

Methods

encodeDefault :: Encode TimeZone

EncodeDefault ZonedTime

ISO8601 in a @TextColumn.

yyyy-mm-ddThh:mm:ss[.ssssssssssss]±hh:mm

• WARNING: Sorting these lexicographically in SQL won't work unless the offset is always the same! Convert to UTCTime first.
• WARNING: SQLite date and time functions support resolution only up to milliseconds.
• WARNING: SQLite date and time functions don't support leap seconds.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode ZonedTime

EncodeDefault String

TextColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode String

EncodeDefault Integer

IntegerColumn if it fits in Int64, otherwise TextColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Integer

EncodeDefault Natural

IntegerColumn if it fits in Int64, otherwise TextColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Natural

EncodeDefault Bool

IntegerColumn. Encodes False as 0 and True as 1.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Bool

EncodeDefault Char

TextColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Char

EncodeDefault Double

FloatColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Double

EncodeDefault Float

FloatColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Float

EncodeDefault Int

IntegerColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Int

EncodeDefault Word

IntegerColumn if it fits in Int64, otherwise TextColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Word

EncodeDefault a => EncodeDefault (Maybe a)

See encodeMaybe.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode (Maybe a)

(EncodeDefault a, EncodeDefault b) => EncodeDefault (Either a b)

See encodeEither.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode (Either a b)

encodeMaybe :: Encode a -> Encode (Maybe a)

a's ColumnType if Just, otherwise NullColumn.

encodeEither :: Encode a -> Encode b -> Encode (Either a b)

a's ColumnType if Left, otherwise b's ColumnType.

encodeSizedIntegral :: (Integral a, Bits a, HasCallStack) => Encode a

IntegerColumn if it fits in Int64, otherwise TextColumn.

encodeAeson :: (a -> Value) -> Encode a

Encodes as TextColumn.

encodeBinary :: (a -> Put) -> Encode a

BlobColumn.

encodeShow :: Show a => Encode a

TextColumn.

Output

data Output o

How to decode an output row from a single Statement.

• Construct with decode, IsString.
• Nest with output.
• Compose with Monoid, Functor, Applicative, Alternative, Monad, MonadPlus, MonadFail and MonadThrow tools.

Instances

MonadFail Output

Defined in Sq.Output

Methods

fail :: String -> Output a

Alternative Output

Defined in Sq.Output

Methods

empty :: Output a

(<|>) :: Output a -> Output a -> Output a

some :: Output a -> Output [a]

many :: Output a -> Output [a]

Applicative Output

Defined in Sq.Output

Methods

pure :: a -> Output a

(<*>) :: Output (a -> b) -> Output a -> Output b

liftA2 :: (a -> b -> c) -> Output a -> Output b -> Output c

(*>) :: Output a -> Output b -> Output b

(<*) :: Output a -> Output b -> Output a

Functor Output

Defined in Sq.Output

Methods

fmap :: (a -> b) -> Output a -> Output b

(<$) :: a -> Output b -> Output a

Monad Output

Defined in Sq.Output

Methods

(>>=) :: Output a -> (a -> Output b) -> Output b

(>>) :: Output a -> Output b -> Output b

return :: a -> Output a

MonadPlus Output

Defined in Sq.Output

Methods

mzero :: Output a

mplus :: Output a -> Output a -> Output a

MonadThrow Output

Defined in Sq.Output

Methods

throwM :: (HasCallStack, Exception e) => e -> Output a

DecodeDefault i => IsString (Output i)

Defined in Sq.Output

Methods

fromString :: String -> Output i

Monoid o => Monoid (Output o)

Defined in Sq.Output

Methods

mempty :: Output o

mappend :: Output o -> Output o -> Output o

mconcat :: [Output o] -> Output o

Semigroup o => Semigroup (Output o)

Defined in Sq.Output

Methods

(<>) :: Output o -> Output o -> Output o

sconcat :: NonEmpty (Output o) -> Output o

stimes :: Integral b => b -> Output o -> Output o

decode :: Name -> Decode o -> Output o

Decode the column with the given Name.

readStatement
        mempty
        (decode "foo" decodeDefault)
        "SELECT foo FROM t"
   :: (DecodeDefault x)
   => Statement Read () x

Note that by design, this library doesn't support positional Output parameters. You must always pick a Name. In the raw SQL, you can use AS to rename your output columns as necessary.

readStatement
        mempty
        (decode "abc" decodeDefault)
        "SELECT foo AS abc FROM t"
   :: (DecodeDefault x)
   => Statement Read () x

Multiple Outputss can be composed with Monoid, Functor, Applicative, Alternative, Monad, MonadPlus, MonadFail and MonadThrow tools.

readStatement
        mempty
        (do foo <- decode "foo" decodeDefault
            when (foo > 10) do
               fail "Oh no!"
            bar <- decode "bar" decodeDefault
            pure (foo, bar))
        "SELECT foo, bar FROM t"
   :: (DecodeDefault y)
   => Statement Read () (Int, y)

Pro-tip: Consider using the IsString instance for Output, where for example "foo" means decode "foo" decodeDefault:

readStatement
        (liftA2 (,) "foo" "bar")
        mempty
        "SELECT foo, bar FROM t"
   :: (DecodeDefault x, DecodeDefault y)
   => Statement Read () (x, y)

output :: Name -> Output o -> Output o

Add a prefix Name to column names in the given Output, separated by __

This is useful for making reusable Outputs. For example, consider the following.

data Point = Point { x :: Int, y :: Int }

pointOutput :: Output Point
pointOutput = Point <$> "x" <*> "y"

After using output:

readStatement
        mempty
        (liftA2 (output "p1" pointInput)
                (output "p2" pointInput))
        [sql|
          SELECT ax AS p1__x, ay AS p1__y,
                 bx AS p2__x, by AS p2__y
          FROM vectors|]
   :: Statement Read () (Point, Point)

Decode

newtype Decode a

How to decode a single SQLite column value into a Haskell value of type a.

Constructors

Decode (SQLData -> Either ErrDecode a)

Decode a SQLData value into a value of type a.

Instances

MonadFail Decode

Defined in Sq.Decoders

Methods

fail :: String -> Decode a

Alternative Decode

Leftmost result on success, rightmost error on failure.

Defined in Sq.Decoders

Methods

empty :: Decode a

(<|>) :: Decode a -> Decode a -> Decode a

some :: Decode a -> Decode [a]

many :: Decode a -> Decode [a]

Applicative Decode

Defined in Sq.Decoders

Methods

pure :: a -> Decode a

(<*>) :: Decode (a -> b) -> Decode a -> Decode b

liftA2 :: (a -> b -> c) -> Decode a -> Decode b -> Decode c

(*>) :: Decode a -> Decode b -> Decode b

(<*) :: Decode a -> Decode b -> Decode a

Functor Decode

Defined in Sq.Decoders

Methods

fmap :: (a -> b) -> Decode a -> Decode b

(<$) :: a -> Decode b -> Decode a

Monad Decode

Defined in Sq.Decoders

Methods

(>>=) :: Decode a -> (a -> Decode b) -> Decode b

(>>) :: Decode a -> Decode b -> Decode b

return :: a -> Decode a

MonadPlus Decode

Leftmost result on success, rightmost error on failure.

Defined in Sq.Decoders

Methods

mzero :: Decode a

mplus :: Decode a -> Decode a -> Decode a

MonadThrow Decode

Defined in Sq.Decoders

Methods

throwM :: (HasCallStack, Exception e) => e -> Decode a

Monoid a => Monoid (Decode a)

mempty = pure mempty

Defined in Sq.Decoders

Methods

mempty :: Decode a

mappend :: Decode a -> Decode a -> Decode a

mconcat :: [Decode a] -> Decode a

Semigroup a => Semigroup (Decode a)

(<>) == liftA2 (<>)

Defined in Sq.Decoders

Methods

(<>) :: Decode a -> Decode a -> Decode a

sconcat :: NonEmpty (Decode a) -> Decode a

stimes :: Integral b => b -> Decode a -> Decode a

decodeRefine :: HasCallStack => (a -> Either String b) -> Decode a -> Decode b

A convenience function for refining a Decoder through a function that may fail with a String error message. The CallStack is preserved.

If you need a more sophisticated refinement, use the Decode constructor.

class DecodeDefault a where

Default way to decode a SQLite value into a Haskell value of type a.

If there there exist also a EncodeDefault instance for a, then it must roundtrip with the DecodeDefault instance for a.

Methods

decodeDefault :: Decode a

Default way to decode a SQLite value into a Haskell value of type a.

Instances

DecodeDefault Int16

IntegerColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Int16

DecodeDefault Int32

IntegerColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Int32

DecodeDefault Int64

IntegerColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Int64

DecodeDefault Int8

IntegerColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Int8

DecodeDefault Word16

IntegerColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Word16

DecodeDefault Word32

IntegerColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Word32

DecodeDefault Word64

IntegerColumn if it fits in Int64, otherwise TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Word64

DecodeDefault Word8

IntegerColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Word8

DecodeDefault ByteString

BlobColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode ByteString

DecodeDefault ByteString

BlobColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode ByteString

DecodeDefault SQLData

Literal SQLData Decode.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode SQLData

DecodeDefault MigrationId

Defined in Sq.Migrations

Methods

decodeDefault :: Decode MigrationId

DecodeDefault Null

NullColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Null

DecodeDefault Text

TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Text

DecodeDefault Text

TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Text

DecodeDefault CalendarDiffDays

ISO8601 in a @TextColumn.

TODO: Currently precission over picoseconds is successfully parsed but silently floored. This is an issue in Data.Time.Format.ISO8601. Fix.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode CalendarDiffDays

DecodeDefault Day

ISO8601 in a @TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Day

DecodeDefault UTCTime

Like for ZonedTime.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode UTCTime

DecodeDefault CalendarDiffTime

ISO8601 in a @TextColumn.

TODO: Currently precission over picoseconds is successfully parsed but silently floored. This is an issue in Data.Time.Format.ISO8601. Fix.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode CalendarDiffTime

DecodeDefault LocalTime

ISO8601 in a @TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode LocalTime

DecodeDefault TimeOfDay

ISO8601 in a @TextColumn.

TODO: Currently precission over picoseconds is successfully parsed but silently floored. This is an issue in Data.Time.Format.ISO8601. Fix.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode TimeOfDay

DecodeDefault TimeZone

ISO8601 in a @TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode TimeZone

DecodeDefault ZonedTime

TextColumn (ISO8601, or seconds since Epoch with optional decimal part of up to picosecond precission), or Integer (seconds since Epoch).

TODO: Currently precission over picoseconds is successfully parsed but silently floored. This is an issue in Data.Time.Format.ISO8601. Fix.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode ZonedTime

DecodeDefault String

TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode String

DecodeDefault Integer

IntegerColumn, FloatColumn, TextColumn depicting a literal integer.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Integer

DecodeDefault Natural

IntegerColumn if it fits in Int64, otherwise TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Natural

DecodeDefault Bool

IntegerColumn and FloatColumn only.

0 is False, every other number is True.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Bool

DecodeDefault Char

TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Char

DecodeDefault Double

FloatColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Double

DecodeDefault Float

FloatColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Float

DecodeDefault Int

IntegerColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Int

DecodeDefault Word

IntegerColumn if it fits in Int64, otherwise TextColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Word

DecodeDefault a => DecodeDefault (Maybe a)

See decodeMaybe.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode (Maybe a)

(DecodeDefault a, DecodeDefault b) => DecodeDefault (Either a b)

See decodeEither.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode (Either a b)

decodeMaybe :: Decode a -> Decode (Maybe a)

Attempt to decode a first, otherwise attempt decode a NullColumn as Nothing.

decodeEither :: Decode a -> Decode b -> Decode (Either a b)

decodeEither da db = fmap Left da <|> fmap Right db

decodeSizedIntegral :: (Integral a, Bits a) => Decode a

IntegerColumn.

decodeAeson :: (Value -> Parser a) -> Decode a

TextColumn.

decodeBinary :: Get a -> Decode a

BlobColumn.

decodeRead :: Read a => Decode a

TextColumn.

Name

data Name

Part of a binding name suitable to use with encode, decode, input and output.

Construct with name or IsString.

Instances

FromJSON Name

Defined in Sq.Names

Methods

parseJSON :: Value -> Parser Name

parseJSONList :: Value -> Parser [Name]

omittedField :: Maybe Name

ToJSON Name

Defined in Sq.Names

Methods

toJSON :: Name -> Value

toEncoding :: Name -> Encoding

toJSONList :: [Name] -> Value

toEncodingList :: [Name] -> Encoding

omitField :: Name -> Bool

IsString Name

Defined in Sq.Names

Methods

fromString :: String -> Name

Show Name

Defined in Sq.Names

Methods

showsPrec :: Int -> Name -> ShowS

show :: Name -> String

showList :: [Name] -> ShowS

NFData Name

Defined in Sq.Names

Methods

rnf :: Name -> ()

Eq Name

Defined in Sq.Names

Methods

(==) :: Name -> Name -> Bool

(/=) :: Name -> Name -> Bool

Ord Name

Defined in Sq.Names

Methods

compare :: Name -> Name -> Ordering

(<) :: Name -> Name -> Bool

(<=) :: Name -> Name -> Bool

(>) :: Name -> Name -> Bool

(>=) :: Name -> Name -> Bool

max :: Name -> Name -> Name

min :: Name -> Name -> Name

HasField "text" Name Text

Defined in Sq.Names

Methods

getField :: Name -> Text

name :: Text -> Either String Name

• First character must be ASCII letter.
• Last character, if any, must be ASCII letter or ASCII digit.
• Characters between the first and last, if any, must be ASCII letters, ASCII digits, or underscore.

Transactional

data Transactional (g :: k) (r :: Retry) (t :: Mode) a

Transactional g r t a groups together multiple interactions with a same Transaction t that finally produce a value of type a. Think of Transactional as if it was STM.

• g is an ephemeral tag for the whole inteaction group that prevents Refs and streams from escaping its intended scope (like ST does it). Just ignore it, it will always be polymorphic.
• r says whether the Transactional could potentially be retried from scratch in order to observe a new snapshot of the database (like STM does it). Learn more about this in Retry.
• t says whether the Transactional could potentially perform Write or Read-only operations.
• a is the Haskell value finally produced by a successfu execution of the Transactional.

To execute a Transactional you will normally use one of read or commit (or rollback or embed, but those are less common).

-- We are using commit to execute the Transactional. This means
-- that the Transactional will have read and Write capabilities, that
-- it can retry, and that ultimately, unless there are unhandled
-- exceptions, the changes will be commited to the database.
Sq.commit pool do

   -- We can execute Write Statements:
   userId1 <- Sq.one insertUser "[e-mail]"

   -- And Read Statements:
   userId2 <- Sq.one getUserIdByEmail "[e-mail]"

   -- We have MonadFail too:
   when (userId1 /= userId2) do
       fail "Something unexpected happened!"

   -- We also have Refs, which work just like TVars:
   ref <- newRef (0 :: Int)

   -- catch behaves like catchSTM, undoing changes to Refs
   -- and to the database itself when the original action fails:
   userId3 <- catch
       -- Something will fail ...
       (do modifyRef ref (+ 1)
           _ <- Sq.one insertUser "[e-mail]"
           throwM FakeException123)
       -- ... but there is a catch!
       (\FakeException123 -> do
           -- The observable universe has been reset to what it
           -- was before the catch:
           Sq.zero getUserIdByEmail "[e-mail]"
           modifyRef ref (+ 10))

   -- Only the effects from the exception handling function were preserved:
   Sq.zero getUserIdByEmail "[e-mail]"
   10 <- readRef ref

   -- retry and its synonyms mzero and empty not only discard changes as
   -- catch does, but they also cause the ongoing Transaction to be
   -- discarded, and the entire Transactional to be executed again on a
   -- brand new Transaction observing a new snapshot of the database. For
   -- example, the following code will keep retrying the whole Transactional
   -- until the user with the specified email exists.
   userId4 <- Sq.maybe getUserIdByEmail "[e-mail]" >>= \case
       Just x -> pure x
       Nothing -> retry

   -- Presumably, this example was waiting for a concurrent connection to
   -- insert said user. If we got here, it is because that happened.

   -- As usual, mzero and empty can be handled by means of <|> and mplus,
   -- or its synonym orElse.
   False <- mplus (writeRef ref 8 >> mzero >> pure True)
                  (pure False)

   -- The recent writeRef to 8 on the retryied Transactional was discarded:
   10 <- readRef ref

   pure ()

Instances

MonadFail (Transactional g r t)

Defined in Sq.Transactional

Methods

fail :: String -> Transactional g r t a

Alternative (Transactional g 'Retry t)

empty = retry
(<|>) = orElse

Defined in Sq.Transactional

Methods

empty :: Transactional g 'Retry t a

(<|>) :: Transactional g 'Retry t a -> Transactional g 'Retry t a -> Transactional g 'Retry t a

some :: Transactional g 'Retry t a -> Transactional g 'Retry t [a]

many :: Transactional g 'Retry t a -> Transactional g 'Retry t [a]

Applicative (Transactional g r t)

Defined in Sq.Transactional

Methods

pure :: a -> Transactional g r t a

(<*>) :: Transactional g r t (a -> b) -> Transactional g r t a -> Transactional g r t b

liftA2 :: (a -> b -> c) -> Transactional g r t a -> Transactional g r t b -> Transactional g r t c

(*>) :: Transactional g r t a -> Transactional g r t b -> Transactional g r t b

(<*) :: Transactional g r t a -> Transactional g r t b -> Transactional g r t a

Functor (Transactional g r t)

Defined in Sq.Transactional

Methods

fmap :: (a -> b) -> Transactional g r t a -> Transactional g r t b

(<$) :: a -> Transactional g r t b -> Transactional g r t a

Monad (Transactional g r t)

Defined in Sq.Transactional

Methods

(>>=) :: Transactional g r t a -> (a -> Transactional g r t b) -> Transactional g r t b

(>>) :: Transactional g r t a -> Transactional g r t b -> Transactional g r t b

return :: a -> Transactional g r t a

MonadPlus (Transactional g 'Retry t)

mzero = retry
mplus = orElse

Defined in Sq.Transactional

Methods

mzero :: Transactional g 'Retry t a

mplus :: Transactional g 'Retry t a -> Transactional g 'Retry t a -> Transactional g 'Retry t a

MonadCatch (Transactional g r t)

catch behaves like STM's catchSTM.

In catch ma f, if an exception is thrown by ma, then any database or Ref changes made by ma will be discarded. Furthermore, if f can handle said exception, then the action resulting from applying f will be executed. Otherwise, if f can't handle the exception, it will bubble up.

Note: This instance's catch catches async exceptions because that's what MonadCatch instances normaly do. As a user of this instance, you probably want to use Control.Exceptions.Safe to make sure you don't catch async exceptions unless you really want to.

Defined in Sq.Transactional

Methods

catch :: (HasCallStack, Exception e) => Transactional g r t a -> (e -> Transactional g r t a) -> Transactional g r t a

MonadMask (Transactional g r t)

Defined in Sq.Transactional

Methods

mask :: HasCallStack => ((forall a. Transactional g r t a -> Transactional g r t a) -> Transactional g r t b) -> Transactional g r t b

uninterruptibleMask :: HasCallStack => ((forall a. Transactional g r t a -> Transactional g r t a) -> Transactional g r t b) -> Transactional g r t b

generalBracket :: HasCallStack => Transactional g r t a -> (a -> ExitCase b -> Transactional g r t c) -> (a -> Transactional g r t b) -> Transactional g r t (b, c)

MonadThrow (Transactional g r t)

Defined in Sq.Transactional

Methods

throwM :: (HasCallStack, Exception e) => e -> Transactional g r t a

MonadAtomicRef (Transactional g r t)

Defined in Sq.Transactional

Methods

atomicModifyRef :: Ref (Transactional g r t) a -> (a -> (a, b)) -> Transactional g r t b

atomicModifyRef' :: Ref (Transactional g r t) a -> (a -> (a, b)) -> Transactional g r t b

MonadRef (Transactional g r t)

All operations are atomic.

Defined in Sq.Transactional

Associated Types

type Ref (Transactional g r t)

Defined in Sq.Transactional

type Ref (Transactional g r t) = Ref g

Methods

newRef :: a -> Transactional g r t (Ref (Transactional g r t) a)

readRef :: Ref (Transactional g r t) a -> Transactional g r t a

writeRef :: Ref (Transactional g r t) a -> a -> Transactional g r t ()

modifyRef :: Ref (Transactional g r t) a -> (a -> a) -> Transactional g r t ()

modifyRef' :: Ref (Transactional g r t) a -> (a -> a) -> Transactional g r t ()

type Ref (Transactional g r t)

Defined in Sq.Transactional

type Ref (Transactional g r t) = Ref g

read :: forall {k} m (p :: Mode) a. (MonadIO m, SubMode p 'Read) => Pool p -> (forall (g :: k). Transactional g 'Retry 'Read a) -> m a

Execute a Read-only Transactional in a fresh Transaction that will be automatically released when done.

commit :: forall {k} m a. MonadIO m => Pool 'Write -> (forall (g :: k). Transactional g 'Retry 'Write a) -> m a

Execute a read-Write Transactional in a fresh Transaction that will be automatically committed when done.

rollback :: forall {k} m a. MonadIO m => Pool 'Write -> (forall (g :: k). Transactional g 'Retry 'Write a) -> m a

Execute a read-Write Transactional in a fresh Transaction that will be automatically rolled-back when done.

This is mostly useful for testing.

embed

Arguments

:: forall {k} m (t :: Mode) a. MonadIO m

=> Transaction t

Ongoing transaction.

-> (forall (g :: k). Transactional g 'NoRetry t a)

-> m a

Embeds all the actions in a Transactional as part of an ongoing Transaction.

• NOTICE Contrary to read, commit or rollback, this Transactional cannot retry, as doing so would require cancelling the ongoing Transaction.

data Ref (g :: k) a

Like TVar, but you can use it inside Transactional through the MonadRef and MonadAtomicRef vocabulary.

Instances

Eq (Ref g a)

Pointer equality

Defined in Sq.Transactional

Methods

(==) :: Ref g a -> Ref g a -> Bool

(/=) :: Ref g a -> Ref g a -> Bool

retry :: forall {k} (g :: k) (t :: Mode) a. Transactional g 'Retry t a

retry behaves like STM's retry. It causes the current Transaction to be cancelled so that a new one can take its place and the entire Transactional is executed again. This allows the Transactional to observe a new snapshot of the database.

• retry, empty and mzero all do fundamentally the same thing, however retry leads to better type inferrence because it forces the r type-parameter to be Retry.
• NOTICE You only need to use mzero if you need access to a newer database snapshot. If all you want to do is undo some Ref transformation effects, or undo database changes, then use catch which doesn't abandon the Transaction.
• WARNING If we keep retrying and the database never changes, then we will be stuck in a loop forever. To mitigate this, when executing the Transactional through read, commit or rollback, you may want to use timeout to abort at some point in the future.

orElse :: forall {k} (g :: k) (r :: Retry) (t :: Mode) a. Transactional g r t a -> Transactional g r t a -> Transactional g r t a

orElse ma mb behaves like STM's orElse ma mb. If ma completes without executing retry, then that constitutes the entirety of orElse ma mb. Otherwise, if ma executed retry, then all the effects from ma are discared and mb is tried in its place.

• orElse, <|> and mplus all do the same thing, but orElse has a more general type because it doesn't force the r type-parameter to be Retry.

Querying

one :: forall {k} o i (t :: Mode) (s :: Mode) (g :: k) (r :: Retry). SubMode t s => Statement s i o -> i -> Transactional g r t o

Executes a Statement expected to return exactly one row.

• Throws ErrRows_TooFew if zero rows, ErrRows_TooMany if more than one row.

maybe :: forall {k} o i (t :: Mode) (s :: Mode) (g :: k) (r :: Retry). SubMode t s => Statement s i o -> i -> Transactional g r t (Maybe o)

Executes a Statement expected to return zero or one rows.

• Throws ErrRows_TooMany if more than one row.

zero :: forall {k} o i (t :: Mode) (s :: Mode) (g :: k) (r :: Retry). SubMode t s => Statement s i o -> i -> Transactional g r t ()

Executes a Statement expected to return exactly zero rows.

• Throws ErrRows_TooMany if more than zero rows.

some :: forall {k} o i (t :: Mode) (s :: Mode) (g :: k) (r :: Retry). SubMode t s => Statement s i o -> i -> Transactional g r t (Int64, NonEmpty o)

Executes a Statement expected to return one or more rows.

• Returns the length of the NonEmpty list, too.
• Throws ErrRows_TooFew if zero rows.

list :: forall {k} o i (t :: Mode) (s :: Mode) (g :: k) (r :: Retry). SubMode t s => Statement s i o -> i -> Transactional g r t (Int64, [o])

Executes a Statement expected to return zero or more rows.

• Returns the length of the list, too.

fold :: forall {k} o z i (t :: Mode) (s :: Mode) (g :: k) (r :: Retry). SubMode t s => Fold o z -> Statement s i o -> i -> Transactional g r t z

Purely fold all the output rows.

foldM :: forall {k} o z i (t :: Mode) (s :: Mode) (g :: k) (r :: Retry). SubMode t s => FoldM (Transactional g r t) o z -> Statement s i o -> i -> Transactional g r t z

Impurely fold the output rows.

• For a non-Transactional version of this function, see foldIO.

Interleaving

streamIO

Arguments

:: forall o i (t :: Mode) (s :: Mode) (m :: Type -> Type). (MonadResource m, SubMode t s)

=> Acquire (Transaction t)

How to acquire the Transaction once the Stream starts being consumed, and how to release it when it's not needed anymore.

If you want this Statement to be the only one in the Transaction, then use one of readTransaction, 'Sq.commitTransaction or rollbackTransaction.

Otherwise, if you already obtained a Transaction by other means, then simply use pure to wrap a Transaction in Acquire.

-> Statement s i o

-> i

-> Stream (Of o) m ()

A Stream from the streaming library.

We use the streaming library because it is fast and doesn't add any transitive dependencies to this project.

Stream the output rows from a Statement in a way that allows interleaving IO actions.

• An exclusive lock will be held on the Transaction while the Stream is producing rows.
• The Transaction lock is released automatically if the Stream is consumed until exhaustion.
• If you won't consume the Stream until exhaustion, then be sure to exit m by means of runResourceT or similar as soon as possible in order to release the Transaction lock.

foldIO

Arguments

:: forall o z i (t :: Mode) (s :: Mode) m. (MonadIO m, MonadMask m, SubMode t s)

=> FoldM m o z

-> Acquire (Transaction t)

How to acquire the Transaction once the m is executed, and how to release it when it's not needed anymore.

If you want this Statement to be the only one in the Transaction, then use one of readTransaction, commitTransaction or rollbackTransaction.

Otherwise, if you already obtained a Transaction by other means, then simply use pure to wrap a Transaction in Acquire.

-> Statement s i o

-> i

-> m z

Fold the output rows from a Statement in a way that allows interleaving IO actions.

• This is simpler alternative to streamIO for when all you need to do is fold.
• If you don't need to interleave IO actions, then consider using fold.

Pool

data Pool (p :: Mode)

Pool of connections to a SQLite database.

• p indicates whether Read-only or read-Write Statements are supported by this Pool.
• Obtain with readPool, writePool or tempPool.
• It's safe and efficient to use a Pool concurrently as is. Concurrency is handled internally.

Instances

NFData (Pool p)

Defined in Sq.Pool

Methods

rnf :: Pool p -> ()

readPool :: Df1 -> Settings -> Acquire (Pool 'Read)

Acquire a Read-only Pool according to the given Settings.

• Use Di.new to obtain the Df1 parameter. Consider using Di.Core.filter to filter-out excessive logging. For example:

  Di.Core.filter \l _ _ -> l >= Df1.Info

writePool :: Df1 -> Settings -> Acquire (Pool 'Write)

Acquire a read-Write Pool according to the given Settings.

• Use Di.new to obtain the Df1 parameter. Consider using Di.Core.filter to filter-out excessive logging. For example:

  Di.Core.filter \l _ _ -> l >= Df1.Info

tempPool :: Df1 -> Acquire (Pool 'Write)

Acquire a read-Write Pool temporarily persisted in the file-system. It will be deleted once released. This can be useful for testing.

• Use Di.new to obtain the Df1 parameter. Consider using Di.Core.filter to filter-out excessive logging. For example:

  Di.Core.filter \l _ _ -> l >= Df1.Info

subPool :: Pool 'Write -> Pool 'Read

Use subPool to obtain the Read-only subset from a read-Write Pool.

• Useful if you are passing the Pool as an argument to some code, and you want to ensure that it can't performs Write operations on it.
• The “new” Pool is not new. It shares all the underlying resources with the original one, including their lifetime.

Settings

data Settings

SQLite connection settings.

Constructors

Settings

Fields

• file :: FilePath

  Database file path. Not an URI.

  Note: To keep things simple, native :memory: SQLite databases are not supported. Maybe use poolTemp or tmpfs if you need that?

• vfs :: SQLVFS
• timeout :: Word32

  SQLite busy Timeout in milliseconds.

Instances

Show Settings

Defined in Sq.Connection

Methods

showsPrec :: Int -> Settings -> ShowS

show :: Settings -> String

showList :: [Settings] -> ShowS

NFData Settings

Defined in Sq.Connection

Methods

rnf :: Settings -> ()

Eq Settings

Defined in Sq.Connection

Methods

(==) :: Settings -> Settings -> Bool

(/=) :: Settings -> Settings -> Bool

settings

Arguments

:: FilePath

Database file path. Not an URI, not :memory:

-> Settings

Default connection settings.

Transaction

data Transaction (t :: Mode)

A database transaction handle.

• t indicates whether Read-only or read-Write Statements are supported.
• Prefer to use a Read-only Transaction if you are solely performing Read-only Statements. It will be more efficient in concurrent settings.
• Obtain with readTransaction or commitTransaction. Or, if you are testing, with rollbackTransaction.
• If you have access to a Transaction within its intended scope, then you can assume that a database transaction has started, and will eventually be automatically commited or rolled back as requested when it was obtained.
• It's safe and efficient to use a Transaction concurrently as is. Concurrency is handled internally.

Instances

Show (Transaction t)

Defined in Sq.Connection

Methods

showsPrec :: Int -> Transaction t -> ShowS

show :: Transaction t -> String

showList :: [Transaction t] -> ShowS

NFData (Transaction t)

Defined in Sq.Connection

Methods

rnf :: Transaction t -> ()

readTransaction :: forall (mode :: Mode). Pool mode -> Acquire (Transaction 'Read)

Acquire a read-only transaction.

• You may need this function if you are using one of embed, foldIO or streamIO. Otherwise, just use read.

commitTransaction :: Pool 'Write -> Acquire (Transaction 'Write)

Acquire a read-write transaction where changes are finally commited to the database unless there is an unhandled exception during the transaction, in which case they are rolled back.

• You may need this function if you are using one of embed, foldIO or streamIO. Otherwise, just use commit.

rollbackTransaction :: Pool 'Write -> Acquire (Transaction 'Write)

Acquire a read-write transaction where changes are always rolled back. This is mostly useful for testing purposes.

• You may need this function if you are using one of embed, foldIO or streamIO. Otherwise, just use commit.
• An equivalent behavior can be achieved by bracketing changes between savepoint and rollbackTo in a commitTransactionting transaction. Or by using throwM and catch within Transactional. However, using a rollbackTransaction is much faster than using Savepoints.

Resources

Sq relies heavily on Acquire for safe resource management in light of concurrency and dependencies between resources.

As a user of Sq, you mostly just have to figure out how to obtain a Pool. For that, you will probably benefit use one of these functions:

• with for integrating with MonadMask from the exceptions library.
• new for integrating with MonadResource from the resourcet library.
• uith for integrating with MonadUnliftIO from the unliftio library.

If you have no idea what I'm talking about, just use with. Here is an example:

with tempPool \(pool :: Pool 'Write) ->
    -- Here use pool as necessary.
    -- The resources associated with it will be
    -- automatically released after leaving this scope.

Now that you have a Pool, try to solve your problems within Transactional by means of read, commit or rollback.

However, if you need to interleave IO actions while streaming result rows out of the database, Transactional won't be enough. You will need to use foldIO or streamIO.

new :: MonadResource m => Acquire a -> m a

Acquire through MonadResource.

new = fmap snd . Data.Acquire.allocateAcquire

with :: (MonadMask m, MonadIO m) => Acquire a -> (a -> m b) -> m b

Acquire through MonadMask.

with = Control.Monad.Trans.Resource.Extra.withAcquire.

uith :: MonadUnliftIO m => Acquire a -> (a -> m b) -> m b

Acquire through MonadUnliftIO.

uith = Data.Acquire.with

Savepoint

data Savepoint

See savepoint, savepointRollback and savepointRelease.

• WARNING safely dealing with Savepoints can be tricky. Consider using catch on Transactional, which is implemented using Savepoint and does the right thing.

Instances

Show Savepoint

Defined in Sq.Connection

Methods

showsPrec :: Int -> Savepoint -> ShowS

show :: Savepoint -> String

showList :: [Savepoint] -> ShowS

NFData Savepoint

Defined in Sq.Connection

Methods

rnf :: Savepoint -> ()

savepoint :: MonadIO m => Transaction 'Write -> m Savepoint

Obtain savepoint to which one can later savepointRollback or savepointRelease.

savepointRollback :: MonadIO m => Savepoint -> m ()

Disregard all the changes that happened to the Transaction related to this Savepoint since the time it was obtained through savepoint.

• Trying to savepointRollback a Savepoint that isn't reachable anymore throws an exception.
• A Savepoint stops being reachable when the relevant Transaction ends, or when a savepointRollback to an earlier Savepoint on the same Transaction is performed, or when it or a later Savepoint is explicitely released through savepointRelease.

savepointRelease :: MonadIO m => Savepoint -> m ()

Release a Savepoint so that it, together with any previous Savepoints on the same Transaction, become unreachable to future uses of savepointRollback or savepointRelease.

• Trying to savepointRelease a Savepoint that isn't reachable anymore throws an exception.
• A Savepoint stops being reachable when the relevant Transaction ends, or when a savepointRollback to an earlier Savepoint on the same Transaction is performed, or when it or a later Savepoint is explicitely released through savepointRelease.

Migrations

1. List all the Migrations in chronological order. Each Migration is a Transactional action on the database, identified by a unique MigrationId. Construct with migration.

   migrations :: [Sq.Migration]
   migrations =
      [ Sq.migration "create users table" createUsersTable
      , Sq.migration "add email column to users" addUserEmailColumn
      , Sq.migration "create articles table" createArticlesTable
      ,  ... more migrations ... 
      ]
   

2. Run any Migrations that haven't been run yet, if necessary, by performing migrate once as soon as you obtain your Write connection Pool. migrate will enforce that the MigrationIds, be unique, and will make sure that any migration history in the MigrationsTable is compatible with the specified Migrations.

   Sq.migrate pool "migrations" migrations \case
      []   -> ... No migrations will run. ...
      mIds -> ... Some migrations will run. Maybe backup things here? ...
   

3. Don't change your MigrationIds over time. If you do, then the history in MigrationsTable will become unrecognizable by migrate. Also, avoid having the Transactional code in each Migration use your domain types and functions, as doing so may force you to alter past Transactional if your domain types and functions change. Ideally, you should write each Migration in such a way that you never have to modify them in the future.

migrate

Arguments

:: forall a m. (MonadIO m, MonadMask m)

=> Pool 'Write

Connection Pool to the database to migrate.

-> MigrationsTable

Name of the table where the registry of ran Migrations is kept.

-> [Migration]

Migrations to apply to the database, if necessary, in chronological order.

-> ([MigrationId] -> m a)

This will be performed while the write transaction is active, letting you know which MigrationIds are to be performed, and in which order.

This can be a good place to perform a backup of the database if necessary. Presumably, migrate is being run during the initialization of your program, suggesting that nobody else is trying to write to the database at this time, so it's OK if this code takes a while to run.

Don't try to acquire a Write transaction here, it will deadlock. It's OK to interact with the Pool through Read-only means.

-> m a

Run all the migrations in Migrations that haven't been run yet.

• If the MigrationIds are not compatible with the current migration history as reported by MigrationsTable, there will be an exception.
• If MigrationsTable doesn't exist, it will be created.
• All the changes are run in a single Transaction, including those to MigrationsTable.

migration

Arguments

:: MigrationId

-> (forall (g :: k). Transactional g 'NoRetry 'Write ())

Notice the NoRetry. In other words, this Transactional can't perform retry nor any Alternative nor MonadPlus features.

-> Migration

Define a single Migration that, when executed, will perform the given Transactional.

• See Migration.

data Migration

A single Migration consisting of a Transactional action uniquely identified by a MigrationId.

• Construct with migration.
• Run through migrate.

Instances

HasField "id" Migration MigrationId

Defined in Sq.Migrations

Methods

getField :: Migration -> MigrationId

data MigrationId

Unique identifier for a Migration within a MigrationsTable.

• You are supposed to type these statically, so construct a MigrationId by typing down the literal string.

Instances

IsString MigrationId

Defined in Sq.Migrations

Methods

fromString :: String -> MigrationId

Show MigrationId

Defined in Sq.Migrations

Methods

showsPrec :: Int -> MigrationId -> ShowS

show :: MigrationId -> String

showList :: [MigrationId] -> ShowS

Eq MigrationId

Defined in Sq.Migrations

Methods

(==) :: MigrationId -> MigrationId -> Bool

(/=) :: MigrationId -> MigrationId -> Bool

Ord MigrationId

Defined in Sq.Migrations

Methods

compare :: MigrationId -> MigrationId -> Ordering

(<) :: MigrationId -> MigrationId -> Bool

(<=) :: MigrationId -> MigrationId -> Bool

(>) :: MigrationId -> MigrationId -> Bool

(>=) :: MigrationId -> MigrationId -> Bool

max :: MigrationId -> MigrationId -> MigrationId

min :: MigrationId -> MigrationId -> MigrationId

DecodeDefault MigrationId

Defined in Sq.Migrations

Methods

decodeDefault :: Decode MigrationId

EncodeDefault MigrationId

Defined in Sq.Migrations

Methods

encodeDefault :: Encode MigrationId

HasField "id" Migration MigrationId

Defined in Sq.Migrations

Methods

getField :: Migration -> MigrationId

HasField "text" MigrationId Text

Defined in Sq.Migrations

Methods

getField :: MigrationId -> Text

data MigrationsTable

Name of the database table keeping a registry of executed Migrations, by their MigrationId.

• Same syntax rules as Name.
• This table will be created and updated by migrate as necessary.

Instances

FromJSON MigrationsTable

Defined in Sq.Migrations

Methods

parseJSON :: Value -> Parser MigrationsTable

parseJSONList :: Value -> Parser [MigrationsTable]

omittedField :: Maybe MigrationsTable

ToJSON MigrationsTable

Defined in Sq.Migrations

Methods

toJSON :: MigrationsTable -> Value

toEncoding :: MigrationsTable -> Encoding

toJSONList :: [MigrationsTable] -> Value

toEncodingList :: [MigrationsTable] -> Encoding

omitField :: MigrationsTable -> Bool

IsString MigrationsTable

Defined in Sq.Migrations

Methods

fromString :: String -> MigrationsTable

Show MigrationsTable

Defined in Sq.Migrations

Methods

showsPrec :: Int -> MigrationsTable -> ShowS

show :: MigrationsTable -> String

showList :: [MigrationsTable] -> ShowS

Eq MigrationsTable

Defined in Sq.Migrations

Methods

(==) :: MigrationsTable -> MigrationsTable -> Bool

(/=) :: MigrationsTable -> MigrationsTable -> Bool

Ord MigrationsTable

Defined in Sq.Migrations

Methods

compare :: MigrationsTable -> MigrationsTable -> Ordering

(<) :: MigrationsTable -> MigrationsTable -> Bool

(<=) :: MigrationsTable -> MigrationsTable -> Bool

(>) :: MigrationsTable -> MigrationsTable -> Bool

(>=) :: MigrationsTable -> MigrationsTable -> Bool

max :: MigrationsTable -> MigrationsTable -> MigrationsTable

min :: MigrationsTable -> MigrationsTable -> MigrationsTable

HasField "text" MigrationsTable Text

Defined in Sq.Migrations

Methods

getField :: MigrationsTable -> Text

Miscellaneuos

data Retry

Used as the r type-parameter in Transactional g r t a.

• If the Transactional uses any Alternative or MonadPlus feature, then r must be Retry, and the Transactional can only be executed through read, commit or rollback.
• Otherwise, r can be NoRetry. In that case, embed can also be used to execute the Transactional.

Constructors

NoRetry

Retry

Instances

Show Retry

Defined in Sq.Transactional

Methods

showsPrec :: Int -> Retry -> ShowS

show :: Retry -> String

showList :: [Retry] -> ShowS

Eq Retry

Defined in Sq.Transactional

Methods

(==) :: Retry -> Retry -> Bool

(/=) :: Retry -> Retry -> Bool

Ord Retry

Defined in Sq.Transactional

Methods

compare :: Retry -> Retry -> Ordering

(<) :: Retry -> Retry -> Bool

(<=) :: Retry -> Retry -> Bool

(>) :: Retry -> Retry -> Bool

(>=) :: Retry -> Retry -> Bool

max :: Retry -> Retry -> Retry

min :: Retry -> Retry -> Retry

data BindingName

A non-empty list of Names that can be rendered as Input or Output parameters in a Statement.

As a user of Sq, you never construct a BindingName manually. Rather, uses of input and output build one for you from its Name constituents. BindingNames are only exposed to you through ErrInput, ErrOutput and ErrStatement.

Instances

Semigroup BindingName

Defined in Sq.Names

Methods

(<>) :: BindingName -> BindingName -> BindingName

sconcat :: NonEmpty BindingName -> BindingName

stimes :: Integral b => b -> BindingName -> BindingName

Show BindingName

Defined in Sq.Names

Methods

showsPrec :: Int -> BindingName -> ShowS

show :: BindingName -> String

showList :: [BindingName] -> ShowS

NFData BindingName

Defined in Sq.Names

Methods

rnf :: BindingName -> ()

Eq BindingName

Defined in Sq.Names

Methods

(==) :: BindingName -> BindingName -> Bool

(/=) :: BindingName -> BindingName -> Bool

Ord BindingName

Defined in Sq.Names

Methods

compare :: BindingName -> BindingName -> Ordering

(<) :: BindingName -> BindingName -> Bool

(<=) :: BindingName -> BindingName -> Bool

(>) :: BindingName -> BindingName -> Bool

(>=) :: BindingName -> BindingName -> Bool

max :: BindingName -> BindingName -> BindingName

min :: BindingName -> BindingName -> BindingName

data Mode

Constructors

Read

• A Statement 'Read performs a read-only query. Obtain with readStatement.
• A Transaction 'Read can permorm 'Read Statements only. Obtain with readTransaction.
• A Pool 'Read can permorm 'Read Transactions only. Obtain with readPool or subPool.

Write

• A Statement 'Write performs a read or write query. Obtain with writeStatement.
• A Transaction 'Write can permorm both 'Read and 'Write Statements. Obtain with commitTransaction or rollbackTransaction.
• A Pool 'Write can permorm both 'Read and 'Write Transactions. Obtain with writePool or tempPool.

Instances

Show Mode

Defined in Sq.Mode

Methods

showsPrec :: Int -> Mode -> ShowS

show :: Mode -> String

showList :: [Mode] -> ShowS

ToValue Mode

Defined in Sq.Mode

Methods

value :: Mode -> Value

Eq Mode

Defined in Sq.Mode

Methods

(==) :: Mode -> Mode -> Bool

(/=) :: Mode -> Mode -> Bool

Ord Mode

Defined in Sq.Mode

Methods

compare :: Mode -> Mode -> Ordering

(<) :: Mode -> Mode -> Bool

(<=) :: Mode -> Mode -> Bool

(>) :: Mode -> Mode -> Bool

(>=) :: Mode -> Mode -> Bool

max :: Mode -> Mode -> Mode

min :: Mode -> Mode -> Mode

class SubMode (sup :: Mode) (sub :: Mode)

Instances

SubMode 'Read 'Read

Defined in Sq.Mode

(TypeError ('Text "Write mode is not a subset of Read mode") :: Constraint) => SubMode 'Read 'Write

Defined in Sq.Mode

SubMode 'Write 'Read

Defined in Sq.Mode

SubMode 'Write 'Write

Defined in Sq.Mode

data Null

The NULL SQL datatype.

Mostly useful if you want to encode or decode a literal NULL value through EncodeDefault and DecodeDefault instances.

However, often you can benefit from encodeMaybe and decodeMaybe instead.

Constructors

Null

Instances

Monoid Null

Defined in Sq.Null

Methods

mempty :: Null

mappend :: Null -> Null -> Null

mconcat :: [Null] -> Null

Semigroup Null

Defined in Sq.Null

Methods

(<>) :: Null -> Null -> Null

sconcat :: NonEmpty Null -> Null

stimes :: Integral b => b -> Null -> Null

Show Null

Defined in Sq.Null

Methods

showsPrec :: Int -> Null -> ShowS

show :: Null -> String

showList :: [Null] -> ShowS

Eq Null

Defined in Sq.Null

Methods

(==) :: Null -> Null -> Bool

(/=) :: Null -> Null -> Bool

Ord Null

Defined in Sq.Null

Methods

compare :: Null -> Null -> Ordering

(<) :: Null -> Null -> Bool

(<=) :: Null -> Null -> Bool

(>) :: Null -> Null -> Bool

(>=) :: Null -> Null -> Bool

max :: Null -> Null -> Null

min :: Null -> Null -> Null

DecodeDefault Null

NullColumn.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode Null

EncodeDefault Null

NullColumn.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode Null

Errors

newtype ErrEncode

See Encode.

Constructors

ErrEncode SomeException

Instances

Exception ErrEncode

Defined in Sq.Encoders

Methods

toException :: ErrEncode -> SomeException

fromException :: SomeException -> Maybe ErrEncode

displayException :: ErrEncode -> String

Show ErrEncode

Defined in Sq.Encoders

Methods

showsPrec :: Int -> ErrEncode -> ShowS

show :: ErrEncode -> String

showList :: [ErrEncode] -> ShowS

data ErrInput

See Encode.

Constructors

ErrInput BindingName ErrEncode

Instances

Exception ErrInput

Defined in Sq.Input

Methods

toException :: ErrInput -> SomeException

fromException :: SomeException -> Maybe ErrInput

displayException :: ErrInput -> String

Show ErrInput

Defined in Sq.Input

Methods

showsPrec :: Int -> ErrInput -> ShowS

show :: ErrInput -> String

showList :: [ErrInput] -> ShowS

data ErrDecode

See Decode.

Constructors

ErrDecode_Type ColumnType [ColumnType]

Received ColumnType, expected ColumnTypes.

ErrDecode_Fail SomeException

Instances

Exception ErrDecode

Defined in Sq.Decoders

Methods

toException :: ErrDecode -> SomeException

fromException :: SomeException -> Maybe ErrDecode

displayException :: ErrDecode -> String

Show ErrDecode

Defined in Sq.Decoders

Methods

showsPrec :: Int -> ErrDecode -> ShowS

show :: ErrDecode -> String

showList :: [ErrDecode] -> ShowS

data ErrOutput

Constructors

ErrOutput_ColumnValue BindingName ErrDecode

Error from Decode.

ErrOutput_ColumnMissing BindingName

Missing column name in the raw SQL.

ErrOutput_Fail SomeException

Error from MonadThrow.

Instances

Exception ErrOutput

Defined in Sq.Output

Methods

toException :: ErrOutput -> SomeException

fromException :: SomeException -> Maybe ErrOutput

displayException :: ErrOutput -> String

Show ErrOutput

Defined in Sq.Output

Methods

showsPrec :: Int -> ErrOutput -> ShowS

show :: ErrOutput -> String

showList :: [ErrOutput] -> ShowS

data ErrStatement

Constructors

ErrStatement_DuplicateColumnName BindingName

A same column name appears twice or more in the raw SQL.

Instances

Exception ErrStatement

Defined in Sq.Connection

Methods

toException :: ErrStatement -> SomeException

fromException :: SomeException -> Maybe ErrStatement

displayException :: ErrStatement -> String

Show ErrStatement

Defined in Sq.Connection

Methods

showsPrec :: Int -> ErrStatement -> ShowS

show :: ErrStatement -> String

showList :: [ErrStatement] -> ShowS

Eq ErrStatement

Defined in Sq.Connection

Methods

(==) :: ErrStatement -> ErrStatement -> Bool

(/=) :: ErrStatement -> ErrStatement -> Bool

data ErrRows

Constructors

ErrRows_TooFew

Fewer rows than requested were available.

ErrRows_TooMany

More rows than requested were available.

Instances

Exception ErrRows

Defined in Sq.Connection

Methods

toException :: ErrRows -> SomeException

fromException :: SomeException -> Maybe ErrRows

displayException :: ErrRows -> String

Show ErrRows

Defined in Sq.Connection

Methods

showsPrec :: Int -> ErrRows -> ShowS

show :: ErrRows -> String

showList :: [ErrRows] -> ShowS

Eq ErrRows

Defined in Sq.Connection

Methods

(==) :: ErrRows -> ErrRows -> Bool

(/=) :: ErrRows -> ErrRows -> Bool

Re-exports

data SQLData

Constructors

SQLInteger !Int64

SQLFloat !Double

SQLText !Text

SQLBlob !ByteString

SQLNull

Instances

Generic SQLData

Defined in Database.SQLite3

Associated Types

type Rep SQLData

Defined in Database.SQLite3

type Rep SQLData = D1 ('MetaData "SQLData" "Database.SQLite3" "direct-sqlite-2.3.29-Kq2aheM3Z356K3NyVAtSq7" 'False) ((C1 ('MetaCons "SQLInteger" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int64)) :+: C1 ('MetaCons "SQLFloat" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Double))) :+: (C1 ('MetaCons "SQLText" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text)) :+: (C1 ('MetaCons "SQLBlob" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString)) :+: C1 ('MetaCons "SQLNull" 'PrefixI 'False) (U1 :: Type -> Type))))

Methods

from :: SQLData -> Rep SQLData x

to :: Rep SQLData x -> SQLData

Show SQLData

Defined in Database.SQLite3

Methods

showsPrec :: Int -> SQLData -> ShowS

show :: SQLData -> String

showList :: [SQLData] -> ShowS

Eq SQLData

Defined in Database.SQLite3

Methods

(==) :: SQLData -> SQLData -> Bool

(/=) :: SQLData -> SQLData -> Bool

DecodeDefault SQLData

Literal SQLData Decode.

Defined in Sq.Decoders

Methods

decodeDefault :: Decode SQLData

EncodeDefault SQLData

Literal SQLData Encode.

Defined in Sq.Encoders

Methods

encodeDefault :: Encode SQLData

type Rep SQLData

Defined in Database.SQLite3

type Rep SQLData = D1 ('MetaData "SQLData" "Database.SQLite3" "direct-sqlite-2.3.29-Kq2aheM3Z356K3NyVAtSq7" 'False) ((C1 ('MetaCons "SQLInteger" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int64)) :+: C1 ('MetaCons "SQLFloat" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Double))) :+: (C1 ('MetaCons "SQLText" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text)) :+: (C1 ('MetaCons "SQLBlob" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString)) :+: C1 ('MetaCons "SQLNull" 'PrefixI 'False) (U1 :: Type -> Type))))

data SQLVFS

These VFS names are used when using the open2 function.

Constructors

SQLVFSDefault

SQLVFSUnix

SQLVFSUnixDotFile

SQLVFSUnixExcl

SQLVFSUnixNone

SQLVFSUnixNamedSem

SQLVFSCustom Text

Instances

Show SQLVFS

Defined in Database.SQLite3

Methods

showsPrec :: Int -> SQLVFS -> ShowS

show :: SQLVFS -> String

showList :: [SQLVFS] -> ShowS

Eq SQLVFS

Defined in Database.SQLite3

Methods

(==) :: SQLVFS -> SQLVFS -> Bool

(/=) :: SQLVFS -> SQLVFS -> Bool