diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,22 @@ +Copyright (c) 2014, Nikita Volkov + +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the "Software"), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/hasql-backend.cabal b/hasql-backend.cabal new file mode 100644 --- /dev/null +++ b/hasql-backend.cabal @@ -0,0 +1,62 @@ +name: + hasql-backend +version: + 0.1.0 +synopsis: + API for backends of "hasql" +description: + An API for implementation of backends for the + + library. +category: + Database +homepage: + https://github.com/nikita-volkov/hasql-backend +bug-reports: + https://github.com/nikita-volkov/hasql-backend/issues +author: + Nikita Volkov +maintainer: + Nikita Volkov +copyright: + (c) 2014, Nikita Volkov +license: + MIT +license-file: + LICENSE +build-type: + Simple +cabal-version: + >=1.10 + + +source-repository head + type: + git + location: + git://github.com/nikita-volkov/hasql-backend.git + + +library + hs-source-dirs: + library + other-modules: + Hasql.Backend.Prelude + exposed-modules: + Hasql.Backend + build-depends: + -- data: + bytestring < 0.11, + text < 1.3, + vector < 0.11, + -- control: + list-t >= 0.2 && < 0.3, + -- general: + base-prelude < 0.2, + base >= 4.5 && < 4.8 + ghc-options: + -funbox-strict-fields + default-extensions: + Arrows, BangPatterns, ConstraintKinds, DataKinds, DefaultSignatures, DeriveDataTypeable, DeriveFunctor, DeriveGeneric, EmptyDataDecls, FlexibleContexts, FlexibleInstances, FunctionalDependencies, GADTs, GeneralizedNewtypeDeriving, ImpredicativeTypes, LambdaCase, LiberalTypeSynonyms, MagicHash, MultiParamTypeClasses, MultiWayIf, NoImplicitPrelude, NoMonomorphismRestriction, OverloadedStrings, PatternGuards, ParallelListComp, QuasiQuotes, RankNTypes, RecordWildCards, ScopedTypeVariables, StandaloneDeriving, TemplateHaskell, TupleSections, TypeFamilies, TypeOperators, UnboxedTuples + default-language: + Haskell2010 diff --git a/library/Hasql/Backend.hs b/library/Hasql/Backend.hs new file mode 100644 --- /dev/null +++ b/library/Hasql/Backend.hs @@ -0,0 +1,122 @@ +-- | +-- An open API for implementation of specific backend drivers. +module Hasql.Backend where + +import Hasql.Backend.Prelude + + +data Error = + -- | + -- Cannot connect to a server. + CantConnect Text | + -- | + -- The connection got interrupted. + ConnectionLost Text | + -- | + -- Some kind of error on backend. + ErroneousResult Text | + -- | + -- An unexpected or an unparsable result. + UnexpectedResult Text | + -- | + -- An unparsable statement template. + UnparsableTemplate Text | + -- | + -- A transaction concurrency conflict, + -- which indicates that it should be retried. + TransactionConflict | + -- | + -- An operation, + -- which requires a database transaction was executed without one. + NotInTransaction + deriving (Show, Typeable) + +instance Exception Error + + +-- | +-- For reference see +-- . +data IsolationLevel = + Serializable | + RepeatableReads | + ReadCommitted | + ReadUncommitted + + +-- | +-- An isolation level and a boolean, +-- defining, whether the transaction will perform the "write" operations. +type TransactionMode = + (IsolationLevel, Bool) + + +-- | +-- A stream of rows of a result. +type Stream b = + ListT IO (Vector (Result b)) + +-- | +-- A matrix of a result. +type Matrix b = + Vector (Vector (Result b)) + + +-- | +-- A template statement with values for placeholders. +type Statement b = + (ByteString, [StatementArgument b]) + + +class Backend b where + -- | + -- An argument prepared for a statement. + data StatementArgument b + -- | + -- A raw value returned from the database. + data Result b + -- | + -- A backend-specific connection. + data Connection b + -- | + -- Open a connection using the backend's settings. + connect :: b -> IO (Connection b) + -- | + -- Close the connection. + disconnect :: Connection b -> IO () + -- | + -- Execute a statement. + execute :: Statement b -> Connection b -> IO () + -- | + -- Execute a statement + -- and get a matrix of results. + executeAndGetMatrix :: Statement b -> Connection b -> IO (Matrix b) + -- | + -- Execute a statement + -- and stream the results using a cursor. + -- This function will only be used from inside of transactions. + executeAndStream :: Statement b -> Connection b -> IO (Stream b) + -- | + -- Execute a statement, + -- returning the amount of affected rows. + executeAndCountEffects :: Statement b -> Connection b -> IO Word64 + -- | + -- Start a transaction in the specified mode. + beginTransaction :: TransactionMode -> Connection b -> IO () + -- | + -- Finish the transaction, + -- while releasing all the resources acquired with 'executeAndStream'. + -- + -- The boolean defines whether to commit the updates, + -- otherwise it rolls back. + finishTransaction :: Bool -> Connection b -> IO () + + +-- | +-- Support by a backend of a specific data type. +class Mapping b v where + renderValue :: v -> StatementArgument b + parseResult :: Result b -> Either Text v + + + diff --git a/library/Hasql/Backend/Prelude.hs b/library/Hasql/Backend/Prelude.hs new file mode 100644 --- /dev/null +++ b/library/Hasql/Backend/Prelude.hs @@ -0,0 +1,26 @@ +module Hasql.Backend.Prelude +( + module Exports, +) +where + + +-- base-prelude +------------------------- +import BasePrelude as Exports + +-- list-t +------------------------- +import ListT as Exports (ListT) + +-- text +------------------------- +import Data.Text as Exports (Text) + +-- bytestring +------------------------- +import Data.ByteString as Exports (ByteString) + +-- vector +------------------------- +import Data.Vector as Exports (Vector)