Persistent

Persistent is designed to be adaptable to various datastores, allowing multiple backends to be used simultaneously. It separates the serialization layer from the query layer.

Supported Backends

• SQL Databases: PostgreSQL, SQLite, and others via persistent-odbc.
• Key-Value Stores: Redis and ZooKeeper (Note: Key-value stores typically only implement the PersistStore API for basic operations, rather than the full PersistQuery API).

Key Architectural Concepts

• Serialization vs. Querying: The serialization layer is adaptable to any datastore. While SQL databases support complex queries, Persistent's universal query layer has limitations, such as not providing direct joins.
• Extending SQL Queries: For complex SQL operations like joins, it is recommended to use Esqueleto alongside Persistent's serialization to maintain type safety.
• Fallback Mechanism: If Persistent's abstraction is too limiting for a specific task, you can fall back to using raw database drivers or lower-level libraries, using Persistent specifically for un-serializing database responses into Haskell records.

To use Persistent, you need to define your data models using Template Haskell quasi-quotes and then run migrations to set up your schema. Persistent provides type-safe interactions for inserting, reading, and deleting data.

Dependencies

Add the following to your package.yaml:

dependencies:
- base ^>= 4.17
- text ^>= 2
- persistent ^>= 2.14
- persistent-sqlite ^>= 2.13

Basic Usage Example

This example demonstrates defining a Person model, running a migration on an in-memory SQLite database, inserting records, querying them, and deleting them.

{-# LANGUAGE EmptyDataDecls             #-}
{-# LANGUAGE FlexibleContexts           #-}
{-# LANGUAGE GADTs                      #-}
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
{-# LANGUAGE MultiParamTypeClasses      #-}
{-# LANGUAGE OverloadedStrings          #-}
{-# LANGUAGE QuasiQuotes                #-}
{-# LANGUAGE TemplateHaskell            #-}
{-# LANGUAGE TypeFamilies               #-}
import           Control.Monad.IO.Class  (liftIO)
import           Database.Persist
import           Database.Persist.Sqlite
import           Database.Persist.TH
import           Data.Text

share [mkPersist sqlSettings, mkMigrate "migrateAll"] [persistLowerCase|
Person
    name Text
    age Int Maybe
    deriving Show
|]

main :: IO ()
main = runSqlite ":memory:" $ do
    -- setup db schema
    runMigration migrateAll
    
    -- write to db
    insert $ Person "Jane Doe" Nothing
    johnId <- insert $ Person "John Doe" $ Just 35

    -- read from db
    john1 <- selectList [PersonId ==. johnId] [LimitTo 1]
    john2 <- get johnId

    liftIO $ print (john1 :: [Entity Person])
    liftIO $ print (john2 :: Maybe Person)
    
    -- delete from db
    delete johnId
    deleteWhere [PersonId ==. johnId]