da1907c · typeable/postgresql-simple

git.iko.soy/typeable/postgresql-simple

Improve documentation

commitda1907c15a4d48bf89b1ffc728d8dd98019c2be4 authorLeon P Smith <leon@melding-monads.com> dateThu 27 Mar 2014, 19:08 (13 years ago) parent7199c10

2 files changed+54−12

compare with master

unifiedsplit

src/Database/PostgreSQL/Simple.hs+21 src/Database/PostgreSQL/Simple/Types.hs+33−12

src/Database/PostgreSQL/Simple.hs+21

@@ -343,6 +343,27 @@ execute conn template qs = do

343343-- Returns the number of rows affected.

344344--

345345-- Throws 'FormatError' if the query could not be formatted correctly.

346+--

347+-- For example, here's a command that inserts two rows into a table

348+-- with two columns:

349+--

350+-- @

351+-- executeMany c [sql|

352+-- INSERT INTO sometable VALUES (?,?)

353+-- |] [(1, \"hello\"),(2, \"world\")]

354+-- @

355+--

356+-- Here's an canonical example of a multi-row update command:

357+--

358+-- @

359+-- executeMany c [sql|

360+-- UPDATE sometable

361+-- SET sometable.y = upd.y

362+-- FROM (VALUES (?,?)) as upd(x,y)

363+-- WHERE sometable.x = upd.x

364+-- |] [(1, \"hello\"),(2, \"world\")

365+-- @

366+

346367executeMany :: (ToRow q) => Connection -> Query -> [q] -> IO Int64

347368executeMany _ _ [] = return 0

348369executeMany conn q qs = do

src/Database/PostgreSQL/Simple/Types.hs+33−12

@@ -139,6 +139,13 @@ data QualifiedIdentifier = QualifiedIdentifier (Maybe Text) Text

139139instance Hashable QualifiedIdentifier where

140140 hashWithSalt i (QualifiedIdentifier q t) = hashWithSalt i (q, t)

141141

142+-- | @\"foo.bar\"@ will get turned into

143+-- @QualifiedIdentifier (Just \"foo\") \"bar\"@, while @\"foo\"@ will get

144+-- turned into @QualifiedIdentifier Nothing \"foo\"@. Note this instance

145+-- is for convenience, and does not match postgres syntax. It

146+-- only examines the first period character, and thus cannot be used if the

147+-- qualifying identifier contains a period for example.

148+

142149instance IsString QualifiedIdentifier where

143150 fromString str = let (x,y) = T.break (== '.') (fromString str)

144151 in if T.null y

@@ -173,26 +180,40 @@ newtype Savepoint = Savepoint Query

173180 deriving (Eq, Ord, Show, Read, Typeable)

174181

175182-- | Represents a @VALUES@ table literal, usable as an alternative

176−-- to @executeMany@ and @returning@. For example:

183+-- to @executeMany@ and @returning@. The main advantage is that

184+-- you can parametrize more than just a single @VALUES@ expression.

185+-- For example, here's a query to insert a thing into one table

186+-- and some attributes of that thing into another, returning the

187+-- new id generated by the database:

188+--

177189--

178−-- > execute c "INSERT INTO table (key,val) ?"

179−-- > (Only (Values ["int4","text"]

180−-- > [(1,"hello"),(2,"world")]))

190+-- > query c [sql|

191+-- > WITH new_thing AS (

192+-- > INSERT INTO thing (name) VALUES (?) RETURNING id

193+-- > ), new_attributes AS (

194+-- > INSERT INTO thing_attributes

195+-- > SELECT new_thing.id, attrs.*

196+-- > FROM new_thing JOIN ? attrs

197+-- > ) SELECT * FROM new_thing

198+-- > |] ("foo", Values [ "int4", "text" ]

199+-- > [ ( 1 , "hello" )

200+-- > , ( 2 , "world" ) ])

181201--

182−-- Issues the following query:

202+-- (Note this example uses writable common table expressions,

203+-- which were added in PostgreSQL 9.1)

183204--

184−-- > INSERT INTO table (key,val) (VALUES (1::"int4",'hello'::"text"),(2,'world'))

205+-- The second parameter gets expanded into the following SQL syntax:

185206--

186−-- When the list of values is empty, the following query will be issued:

207+-- > (VALUES (1::"int4",'hello'::"text"),(2,'world'))

187208--

188−-- > INSERT INTO table (key,val) (VALUES (null::"int4",null::"text") LIMIT 0)

209+-- When the list of attributes is empty, the second parameter expands to:

210+--

211+-- > (VALUES (null::"int4",null::"text") LIMIT 0)

189212--

190213-- By contrast, @executeMany@ and @returning@ don't issue the query

191214-- in the empty case, and simply return @0@ and @[]@ respectively.

192−--

193−-- The advantage over @executeMany@ is in cases when you want to

194−-- parameterize table literals in addition to other parameters, as can

195−-- occur with writable common table expressions, for example.

215+-- This behavior is usually correct given their intended use cases,

216+-- but would certainly be wrong in the example above.

196217--

197218-- The first argument is a list of postgresql type names. Because this

198219-- is turned into a properly quoted identifier, the type name is case