| Safe Haskell | None |
|---|
Snap.Snaplet.SqliteSimple
Contents
Description
This snaplet makes it simple to use a SQLite database from your Snap application and is based on the sqlite-simple library (http://hackage.haskell.org/package/sqlite-simple). Now, adding a database to your web app takes just two simple steps.
First, include this snaplet in your application's state.
data App = App { ... -- Other state needed in your app , _db :: Snaplet Sqlite } Next, call the sqliteInit from your application's initializer.
appInit = makeSnaplet ... $ do ... d <- nestSnaplet "db" db sqliteInit return $ App ... d
Now you can use any of the sqlite-simple wrapper functions defined in this module anywhere in your application handlers. For instance:
postHandler :: Handler App App () postHandler = do posts <- with db $ query_ "select * from blog_post" ...
Optionally, if you find yourself doing many database queries, you can eliminate some of the boilerplate by defining a HasSqlite instance for your application.
instance HasSqlite (Handler b App) where getSqliteState = with db get
With this code, our postHandler example no longer requires the with function:
postHandler :: Handler App App () postHandler = do posts <- query_ "select * from blog_post" ...
The first time you run an application with the sqlite-simple snaplet, a configuration file devel.cfg is created in the snaplets/sqlite-simple directory underneath your project root. It specifies how to connect to your Sqlite database. Edit this file and modify the values appropriately and you'll be off and running.
If you want to have out-of-the-box authentication, look at the documentation for the Snap.Snaplet.Auth.Backends.Sqlite module.
- data Sqlite = Sqlite {}
- class MonadCatchIO m => HasSqlite m where
- getSqliteState :: m Sqlite
- sqliteInit :: SnapletInit b Sqlite
- query :: (HasSqlite m, ToRow q, FromRow r) => Query -> q -> m [r]
- query_ :: (HasSqlite m, FromRow r) => Query -> m [r]
- execute :: (HasSqlite m, ToRow q, MonadCatchIO m) => Query -> q -> m ()
- execute_ :: (HasSqlite m, MonadCatchIO m) => Query -> m ()
- data Connection
- data Query
- newtype Only a = Only {
- fromOnly :: a
- data FormatError
- data ResultError
- data h :. t = h :. t
- class ToRow a where
- class FromRow a where
- field :: FromField a => RowParser a
The Snaplet
The state for the sqlite-simple snaplet. To use it in your app include this in your application state and use sqliteInit to initialize it.
Constructors
| Sqlite | |
Fields
| |
Instances
| (MonadCatchIO (ReaderT (Snaplet Sqlite) m), MonadCatchIO m) => HasSqlite (ReaderT (Snaplet Sqlite) m) | A convenience instance to make it easier to use this snaplet in the Initializer monad like this: d <- nestSnaplet "db" db pgsInit count <- liftIO $ runReaderT (execute "INSERT ..." params) d |
| (MonadCatchIO (ReaderT Sqlite m), MonadCatchIO m) => HasSqlite (ReaderT Sqlite m) | A convenience instance to make it easier to use functions written for this snaplet in non-snaplet contexts. |
| MonadCatchIO (Handler b Sqlite) => HasSqlite (Handler b Sqlite) | Default instance |
class MonadCatchIO m => HasSqlite m whereSource
Instantiate this typeclass on 'Handler b YourAppState' so this snaplet can find the connection source. If you need to have multiple instances of the sqlite snaplet in your application, then don't provide this instance and leverage the default instance by using "with dbLens" in front of calls to snaplet-sqlite-simple functions.
Methods
Instances
| (MonadCatchIO (ReaderT (Snaplet Sqlite) m), MonadCatchIO m) => HasSqlite (ReaderT (Snaplet Sqlite) m) | A convenience instance to make it easier to use this snaplet in the Initializer monad like this: d <- nestSnaplet "db" db pgsInit count <- liftIO $ runReaderT (execute "INSERT ..." params) d |
| (MonadCatchIO (ReaderT Sqlite m), MonadCatchIO m) => HasSqlite (ReaderT Sqlite m) | A convenience instance to make it easier to use functions written for this snaplet in non-snaplet contexts. |
| MonadCatchIO (Handler b Sqlite) => HasSqlite (Handler b Sqlite) | Default instance |
sqliteInit :: SnapletInit b SqliteSource
Initialize the snaplet
Wrappers and re-exports
execute_ :: (HasSqlite m, MonadCatchIO m) => Query -> m ()Source
data Connection
Connection to an open database.
data Query
A query string. This type is intended to make it difficult to construct a SQL query by concatenating string fragments, as that is an extremely common way to accidentally introduce SQL injection vulnerabilities into an application.
This type is an instance of IsString, so the easiest way to construct a query is to enable the OverloadedStrings language extension and then simply write the query in double quotes.
{-# LANGUAGE OverloadedStrings #-} import Database.PostgreSQL.Simple q :: Query q = "select ?" The underlying type is a Text, and literal Haskell strings that contain Unicode characters will be correctly transformed to UTF-8.
newtype Only a
A single-value "collection".
This is useful if you need to supply a single parameter to a SQL query, or extract a single column from a SQL result.
Parameter example:
query c "select x from scores where x > ?" (Only (42::Int))Result example:
xs <- query_ c "select id from users" forM_ xs $ \(Only id) -> {- ... -}data FormatError
Exception thrown if a Query was malformed. This may occur if the number of '?' characters in the query string does not match the number of parameters provided.
data ResultError
Exception thrown if conversion from a SQL value to a Haskell value fails.
data h :. t
A composite type to parse your custom data structures without having to define dummy newtype wrappers every time.
instance FromRow MyData where ...
instance FromRow MyData2 where ...
then I can do the following for free:
res <- query' c ... forM res $ \(MyData{..} :. MyData2{..}) -> do ....
Constructors
| h :. t |
class ToRow a where
A collection type that can be turned into a list of SQLData elements.
Instances
| ToRow () | |
| ToField a => ToRow [a] | |
| ToField a => ToRow (Only a) | |
| (ToField a, ToField b) => ToRow (a, b) | |
| (ToRow a, ToRow b) => ToRow (:. a b) | |
| (ToField a, ToField b, ToField c) => ToRow (a, b, c) | |
| (ToField a, ToField b, ToField c, ToField d) => ToRow (a, b, c, d) | |
| (ToField a, ToField b, ToField c, ToField d, ToField e) => ToRow (a, b, c, d, e) | |
| (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f) => ToRow (a, b, c, d, e, f) | |
| (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g) => ToRow (a, b, c, d, e, f, g) | |
| (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h) => ToRow (a, b, c, d, e, f, g, h) | |
| (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i) => ToRow (a, b, c, d, e, f, g, h, i) | |
| (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i, ToField j) => ToRow (a, b, c, d, e, f, g, h, i, j) |
class FromRow a where
A collection type that can be converted from a sequence of fields. Instances are provided for tuples up to 10 elements and lists of any length.
Note that instances can defined outside of sqlite-simple, which is often useful. For example, here's an instance for a user-defined pair:
data User = User { name :: String, fileQuota :: Int } instance FromRow User where fromRow = User <$> field <*> field The number of calls to field must match the number of fields returned in a single row of the query result. Otherwise, a ConversionFailed exception will be thrown.
Note the caveats associated with user-defined implementations of fromRow.
Instances