Persistent

https://github.com/yesodweb/persistent
Admin
Persistent is a type-safe Haskell ORM library that eliminates boilerplate serialization and provides...
Tokens:6,859
Snippets:103
Trust Score:6.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup MySQL test database

Source: https://github.com/yesodweb/persistent/blob/master/persistent-mysql/README.md

Commands to create the 'test' database and user required by the test suite.

```bash
mysql -u root # MySQL root username and password may vary
CREATE DATABASE test;
CREATE USER 'test'@'localhost' IDENTIFIED BY 'test';
GRANT ALL on test.* TO 'test'@'localhost';
```

--------------------------------

### SQLite connection string examples

Source: https://github.com/yesodweb/persistent/blob/master/docs/Database-Configuration.md

Comparison between conventional filename style and URI filename style for SQLite connections.

```text
Conventional style: "sqlite3.db"
URI filename style, relative path, read-only: "file:sqlite3.db?mode=ro"
```

--------------------------------

### Handle missing backend dependencies

Source: https://github.com/yesodweb/persistent/blob/master/development.md

Examples of build failures when required system dependencies like mysql_config or pg_config are missing.

```bash
> stack build persistent-mysql
...
    Process exited with code: ExitFailure 1
    Configuring mysql-0.1.4...
    setup: The program 'mysql_config' is required but it could not be found

> stack build persistent-postgresql
...
    Process exited with code: ExitFailure 1
    Configuring postgresql-libpq-0.9.4.0...
    setup: The program 'pg_config' is required but it could not be found.
```

--------------------------------

### Document public APIs with Haddock

Source: https://github.com/yesodweb/persistent/blob/master/CONTRIBUTING.md

Example of documenting a public function using Haddock syntax, including examples and the @since tag.

```haskell
-- | Retrieve a list of a certain 'Entity' from the database
--
-- ==== __Examples__
--
-- @
-- selectUsers :: 'MonadIO' m => 'ReaderT' 'SqlBackend' m ['Entity' User]
-- selectUsers = 'selectList' [UserAge <-. [40, 41]] []
-- @
--
-- @since 1.5.4
selectList :: (MonadIO m, PersistQueryRead backend, PersistRecordBackend record backend)
           => [Filter record] -- ^ Options to filter the query result; see "Query filter combinators" in the Database.Persist documetation
           -> [SelectOpt record] -- ^ Options to limit and sort the returned records.
           -> ReaderT backend m [Entity record]
selectList = ...
```

--------------------------------

### Schema definition for key derivation example

Source: https://github.com/yesodweb/persistent/blob/master/persistent-template/ChangeLog.md

Example schema used to demonstrate the Show/Read strategy for keys in Persistent versions 2.8.0–2.8.3.1 versus other versions.

```text
Person
	name Text
CustomPrimary
	anInt Int
	Primary anInt
	name Text
```

--------------------------------

### Define schema and perform database operations

Source: https://github.com/yesodweb/persistent/blob/master/README.md

A complete example showing schema definition using Template Haskell, database migration, and basic CRUD operations in SQLite.

```haskell
{-# 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]
```

--------------------------------

### Migrate SqlBackend construction to mkSqlBackend

Source: https://github.com/yesodweb/persistent/blob/master/persistent/ChangeLog.md

Shows the transition from using the SqlBackend constructor directly to using the mkSqlBackend smart constructor with MkSqlBackendArgs.

```diff
- SqlBackend
+ mkSqlBackend MkSqlBackendArgs
    { connInsertSql = ...
    , connCommit = ...
    , connEscapeFieldName = ...
    , connEscapeTableName = ...
    , etc
    }
```

--------------------------------

### Build all packages with stack

Source: https://github.com/yesodweb/persistent/blob/master/development.md

Build all packages listed in stack.yaml using the stack build command.

```bash
> stack build persistent persistent-template persistent-sqlite persistent-test
persistent-mongoDB persistent-mysql persistent-postgresql persistent-redis
```

--------------------------------

### Create test database via CLI

Source: https://github.com/yesodweb/persistent/blob/master/persistent-postgresql/README.md

Commands to create the required 'test' database for running library tests using either the psql shell or the createdb utility.

```bash
$ psql -d postgres
postgres=# CREATE DATABASE test;
CREATE DATABASE

-- or,
$ createdb test
```

--------------------------------

### Configure Stack for local development

Source: https://github.com/yesodweb/persistent/blob/master/CONTRIBUTING.md

Add a local path to your Stack configuration to test changes against a full-fledged application.

```yaml
packages:
- '/path/to/this/repo/persistent-postgresql'
```

--------------------------------

### Run tests with stack

Source: https://github.com/yesodweb/persistent/blob/master/development.md

Commands to run all repository tests or tests for a specific package like persistent-sqlite.

```bash
> stack test

> stack test persistent-sqlite
```

--------------------------------

### Run tests with cabal

Source: https://github.com/yesodweb/persistent/blob/master/development.md

Command to run all tests using cabal.

```bash
> cabal new-test all
```

--------------------------------

### Build excluding failing packages

Source: https://github.com/yesodweb/persistent/blob/master/development.md

Build all packages except those that fail due to missing system dependencies.

```bash
> stack build persistent persistent-template persistent-sqlite persistent-test
persistent-mongoDB persistent-redis
...
Completed 6 action(s).
```

--------------------------------

### Configure package.yaml dependencies

Source: https://github.com/yesodweb/persistent/blob/master/README.md

Required dependencies for a project using Persistent with SQLite.

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

--------------------------------

### Enable MySQL strict mode via my.cnf

Source: https://github.com/yesodweb/persistent/blob/master/docs/Database-Configuration.md

Configure MySQL to raise errors on data truncation by setting the sql_mode in the my.cnf file.

```text
sql_mode="STRICT_ALL_TABLES"
```

--------------------------------

### Locate generated .dump-splices files

Source: https://github.com/yesodweb/persistent/blob/master/persistent-template/README.md

Use the find command to locate the generated .dump-splices files within the .stack-work directory after running the build with the appropriate GHC options.

```bash
find .stack-work -type f -name '*.dump-splices'
```

--------------------------------

### Output Template Haskell splices to files

Source: https://github.com/yesodweb/persistent/blob/master/persistent-template/README.md

Use these GHC options during testing to output the content of generated Template Haskell expressions to .dump-splices files within the .stack-work directory.

```bash
stack test persistent-template --ghc-options='-ddump-splices -ddump-to-file'
```

--------------------------------

### SQLite URI filename modes

Source: https://github.com/yesodweb/persistent/blob/master/docs/Database-Configuration.md

Available mode query parameters for SQLite URI filenames to control database access levels.

```text
mode=ro
mode=rw
mode=rwc
mode=memory
```

--------------------------------

### Enable MySQL strict mode via console

Source: https://github.com/yesodweb/persistent/blob/master/docs/Database-Configuration.md

Set the SQL mode to strict using the MySQL console command.

```sql
SET GLOBAL sql_mode = 'STRICT_ALL_TABLES';
```

--------------------------------

### Standalone Show instance for Unique

Source: https://github.com/yesodweb/persistent/blob/master/persistent/ChangeLog.md

Users who require a Show instance for Uniques after the removal of the automatic deriving can use this standalone deriving instance.

```haskell
deriving stock instance Show (Unique User)
```

--------------------------------

### Core function signature for backend operations

Source: https://github.com/yesodweb/persistent/blob/master/docs/Persistent-brainstorms.md

Proposed core signature for database functions to simplify monad stacks by passing the backend connection explicitly.

```haskell
getImpl :: Key entity -> backend -> IO (Maybe entity)
```

--------------------------------

### PersistField instance for Scientific

Source: https://github.com/yesodweb/persistent/blob/master/docs/PersistValue instances.md

Implements PersistField and PersistFieldSql for the Scientific type, commonly used for financial or scientific data.

```haskell
-- The Scientific type, in widespread use by aeson users and useful for financial, scientific data
instance PersistField Scientific where
  toPersistValue = PersistRational . toRational
  fromPersistValue (PersistRational r) = Right $ fromRational r
  fromPersistValue (PersistDouble d) = Right $ fromFloatDigits d
  fromPersistValue (PersistInt64 i) = Right $ fromIntegral i
  fromPersistValue x = Left $ T.pack "PersistField Scientific: Expected Scientific, received: " <> T.pack (show x)

instance PersistFieldSql Scientific where
  sqlType _ = SqlNumeric 32 20  -- Use your own judgement here
```

--------------------------------

### PersistField instance for Integer with fixed-length hexadecimal

Source: https://github.com/yesodweb/persistent/blob/master/docs/PersistValue instances.md

Pads hexadecimal values with zeros to a fixed length of 30 characters.

```haskell
-- Alternatively, for a fixed length integer, pad the hexadecimal with zeros
showHexFixed :: (Integral a, Show a) => Int -> a -> String  
showHexFixed len val = padZeros $ showHex val ""
    where padZeros s = if length s >= len then s else padZeros ('0' : s)

instance PersistField Integer where
  toPersistValue i = PersistText . T.pack $ showHexFixed 30 i
  fromPersistValue (PersistText s) = read $ "0x" <> T.unpack s
  fromPersistValue x = Left $ T.pack "PersistField Integer: Expected hexadecimal char(30), received: " <> T.pack (show x)
instance PersistFieldSql Integer where
  sqlType _ = SqlOther $ T.pack "char(30)" -- fixed length character string, stored inline
```

--------------------------------

### Define Generated Columns in Persistent DSL

Source: https://github.com/yesodweb/persistent/blob/master/persistent/ChangeLog.md

Use the generated keyword in the Persistent DSL to define columns that are computed by the database. This feature requires specific minimum versions for MySQL, PostgreSQL, and SQLite.

```haskell
GeneratedColumnExample
    fieldOne Text Maybe
    fieldTwo Text Maybe
    fieldThree Text Maybe generated=COALESCE(field_one,field_two)
```

--------------------------------

### PersistField instance for Integer as hexadecimal

Source: https://github.com/yesodweb/persistent/blob/master/docs/PersistValue instances.md

Stores a large integer in hexadecimal format for easier database inspection.

```haskell
import Numeric (showHex)

-- Store a large integer in hexadecimal format (which is easier to inspect in the database)
instance PersistField Integer where
  toPersistValue i = PersistText . T.pack $ showHex i ""
  fromPersistValue (PersistText s) = read $ "0x" <> T.unpack s
  fromPersistValue x = Left $ T.pack "PersistField Integer: Expected hexadecimal text, received: " <> T.pack (show x)
instance PersistFieldSql Integer where
  sqlType _ = SqlString
```
Tokens:
Raw