63e8820 · squeal · git.iko.soy

git.iko.soy/squeal

migration and pq docs

commit63e8820e66cbe9788d69c456212c55d7aa122552 authorEitan Chatav <eitan.chatav@gmail.com> dateMon 26 Mar 2018, 12:00 (9 years ago) parent630c15a

2 files changed+33−28

compare with dev

unifiedsplit

squeal-postgresql/src/Squeal/PostgreSQL/Migration.hs+5−11 squeal-postgresql/src/Squeal/PostgreSQL/PQ.hs+28−17

squeal-postgresql/src/Squeal/PostgreSQL/Migration.hs+5−11

@@ -76,16 +76,10 @@ let

7676 liftBase $ print num

7777:}

7878

79−>>> :{

80−let

81− suppressNotices :: PQ schema schema IO ()

82− suppressNotices = void . manipulate $ UnsafeManipulation

83− "SET client_min_messages TO WARNING;"

84−:}

85−

8679>>> :{

8780withConnection "host=localhost port=5432 dbname=exampledb" $

88− suppressNotices

81+ manipulate (UnsafeManipulation "SET client_min_messages TO WARNING;")

82+ -- suppress notices

8983 & pqThen (migrateUp migrations)

9084 & pqThen numMigrations

9185 & pqThen (migrateDown migrations)

@@ -136,7 +130,7 @@ import Prelude hiding (id, (.))

136130

137131import Squeal.PostgreSQL

138132

139−-- | A `Migration` of a `Migrations`, should contain an inverse pair of

133+-- | A `Migration` should contain an inverse pair of

140134-- `up` and `down` instructions and a unique `name`.

141135data Migration io schema0 schema1 = Migration

142136 { name :: Text -- ^ The `name` of a `Migration`.

@@ -163,7 +157,7 @@ single step = step :>> Done

163157-- | Run `Migration`s by creating the `MigrationsTable`

164158-- if it does not exist and then in a transaction, for each each `Migration`

165159-- query to see if the `Migration` is executed. If not, then

166−-- execute the `Migration` and insert its row in `MigrationsTable`.

160+-- execute the `Migration` and insert its row in the `MigrationsTable`.

167161migrateUp

168162 :: MonadBaseControl IO io

169163 => AlignedList (Migration io) schema0 schema1 -- ^ migrations to run

@@ -219,7 +213,7 @@ migrateUp migration =

219213-- | Rewind `Migration`s by creating the `MigrationsTable`

220214-- if it does not exist and then in a transaction, for each each `Migration`

221215-- query to see if the `Migration` is executed. If it is, then

222−-- rewind the `Migration` and delete its row in `MigrationsTable`.

216+-- rewind the `Migration` and delete its row in the `MigrationsTable`.

223217migrateDown

224218 :: MonadBaseControl IO io

225219 => AlignedList (Migration io) schema0 schema1 -- ^ migrations to rewind

squeal-postgresql/src/Squeal/PostgreSQL/PQ.hs+28−17

@@ -5,9 +5,17 @@ Copyright: (c) Eitan Chatav, 2017

55Maintainer: eitan@morphism.tech

66Stability: experimental

8−`Squeal.PostgreSQL.PQ` is where Squeal statements come to actually get run by

9−`LibPQ`. It contains a `PQ` indexed monad transformer to run `Definition`s and

10−a `MonadPQ` constraint for running a `Manipulation` or `Query`.

8+This module is where Squeal commands actually get executed by

9+`LibPQ`. It containts two typeclasses, `IndexedMonadTransPQ` for executing

10+a `Definition` and `MonadPQ` for executing a `Manipulation` or `Query`,

11+and a `PQ` type with instances for them.

12+

13+Using Squeal in your application will come down to defining

14+the @schema@ of your database and including @PQ schema schema@ in your

15+application's monad transformer stack, giving it an instance of `MonadPQ`.

16+

17+This module also provides functions for retrieving rows from the `LibPQ.Result`

18+of executing Squeal commands.

1119-}

1220

1321{-# OPTIONS_GHC -fno-warn-redundant-constraints #-}

@@ -50,12 +58,12 @@ module Squeal.PostgreSQL.PQ

5058 -- * Result

5159 , LibPQ.Result

5260 , LibPQ.Row

61+ , ntuples

5362 , getRow

5463 , getRows

5564 , nextRow

5665 , firstRow

5766 , liftResult

58− , ntuples

5967 , LibPQ.ExecStatus (..)

6068 , resultStatus

6169 , resultErrorMessage

@@ -275,6 +283,8 @@ instance IndexedMonadTransPQ PQ where

275283

276284* `runQueryParams` is like `manipulateParams` for query statements.

277285

286+* `runQuery` is like `runQueryParams` for a parameter-free statement.

287+

278288* `traversePrepared` has the same type signature as a composition of

279289 `traverse` and `manipulateParams` but provides an optimization by

280290 preparing the statement with `LibPQ.prepare` and then traversing a

@@ -300,13 +310,13 @@ class Monad pq => MonadPQ schema pq | pq -> schema where

300310 manipulateParams

301311 :: ToParams x params

302312 => Manipulation schema params ys

303− -- ^ `insertInto`, `update` or `deleteFrom`

313+ -- ^ `insertRows`, `update` or `deleteFrom`

304314 -> x -> pq (K LibPQ.Result ys)

305315 default manipulateParams

306316 :: (MonadTrans t, MonadPQ schema pq1, pq ~ t pq1)

307317 => ToParams x params

308318 => Manipulation schema params ys

309− -- ^ `insertInto`, `update` or `deleteFrom`

319+ -- ^ `insertRows`, `update` or `deleteFrom`

310320 -> x -> pq (K LibPQ.Result ys)

311321 manipulateParams manipulation params = lift $

312322 manipulateParams manipulation params

@@ -330,7 +340,7 @@ class Monad pq => MonadPQ schema pq | pq -> schema where

330340 traversePrepared

331341 :: (ToParams x params, Traversable list)

332342 => Manipulation schema params ys

333− -- ^ `insertInto`, `update` or `deleteFrom`

343+ -- ^ `insertRows`, `update`, or `deleteFrom`, and friends

334344 -> list x -> pq (list (K LibPQ.Result ys))

335345 default traversePrepared

336346 :: (MonadTrans t, MonadPQ schema pq1, pq ~ t pq1)

@@ -343,20 +353,20 @@ class Monad pq => MonadPQ schema pq | pq -> schema where

343353 :: (ToParams x params, Traversable list)

344354 => list x

345355 -> Manipulation schema params ys

346− -- ^ `insertInto`, `update` or `deleteFrom`

356+ -- ^ `insertRows`, `update` or `deleteFrom`

347357 -> pq (list (K LibPQ.Result ys))

348358 forPrepared = flip traversePrepared

349359

350360 traversePrepared_

351361 :: (ToParams x params, Foldable list)

352362 => Manipulation schema params '[]

353− -- ^ `insertInto`, `update` or `deleteFrom`

363+ -- ^ `insertRows`, `update` or `deleteFrom`

354364 -> list x -> pq ()

355365 default traversePrepared_

356366 :: (MonadTrans t, MonadPQ schema pq1, pq ~ t pq1)

357367 => (ToParams x params, Foldable list)

358368 => Manipulation schema params '[]

359− -- ^ `insertInto`, `update` or `deleteFrom`

369+ -- ^ `insertRows`, `update` or `deleteFrom`

360370 -> list x -> pq ()

361371 traversePrepared_ manipulation params = lift $

362372 traversePrepared_ manipulation params

@@ -365,7 +375,7 @@ class Monad pq => MonadPQ schema pq | pq -> schema where

365375 :: (ToParams x params, Foldable list)

366376 => list x

367377 -> Manipulation schema params '[]

368− -- ^ `insertInto`, `update` or `deleteFrom`

378+ -- ^ `insertRows`, `update` or `deleteFrom`

369379 -> pq ()

370380 forPrepared_ = flip traversePrepared_

371381

@@ -511,11 +521,12 @@ instance (MonadBaseControl b m, schema0 ~ schema1)

511521 pqliftWith $ \ run -> liftBaseWith $ \ runInBase -> f $ runInBase . run

512522 restoreM = PQ . const . restoreM

513523

514−-- | Get a row corresponding to a given row number from a `Result`.

524+-- | Get a row corresponding to a given row number from a `LibPQ.Result`,

525+-- throwing an exception if the row number is out of bounds.

515526getRow

516527 :: (FromRow columns y, MonadBase IO io)

517528 => LibPQ.Row

518− -- ^ row

529+ -- ^ row number

519530 -> K LibPQ.Result columns

520531 -- ^ result

521532 -> io y

@@ -532,7 +543,7 @@ getRow r (K result :: K LibPQ.Result columns) = liftBase $ do

532543

533544-- | Intended to be used for unfolding in streaming libraries, `nextRow`

534545-- takes a total number of rows (which can be found with `ntuples`)

535−-- and a `Result` and given a row number if it's too large returns `Nothing`,

546+-- and a `LibPQ.Result` and given a row number if it's too large returns `Nothing`,

536547-- otherwise returning the row along with the next row number.

537548nextRow

538549 :: (FromRow columns y, MonadBase IO io)

@@ -548,7 +559,7 @@ nextRow total (K result :: K LibPQ.Result columns) r

548559 Nothing -> error "nextRow: found unexpected length"

549560 Just row -> return $ Just (r+1, fromRow @columns row)

550561

551−-- | Get all rows from a `Result`.

562+-- | Get all rows from a `LibPQ.Result`.

552563getRows

553564 :: (FromRow columns y, MonadBase IO io)

554565 => K LibPQ.Result columns -- ^ result

@@ -562,7 +573,7 @@ getRows (K result :: K LibPQ.Result columns) = liftBase $ do

562573 Nothing -> error "getRows: found unexpected length"

563574 Just row -> return $ fromRow @columns row

564575

565−-- | Get the first row if possible from a `Result`.

576+-- | Get the first row if possible from a `LibPQ.Result`.

566577firstRow

567578 :: (FromRow columns y, MonadBase IO io)

568579 => K LibPQ.Result columns -- ^ result

@@ -576,7 +587,7 @@ firstRow (K result :: K LibPQ.Result columns) = liftBase $ do

576587 Nothing -> error "firstRow: found unexpected length"

577588 Just row -> return . Just $ fromRow @columns row

578589

579−-- | Lifts actions on results from `LibPQ`.

590+-- | Lifts actions on results from @LibPQ@.

580591liftResult

581592 :: MonadBase IO io

582593 => (LibPQ.Result -> IO x)