@@ -139,6 +139,13 @@ data QualifiedIdentifier = QualifiedIdentifier (Maybe Text) Text
139instance Hashable QualifiedIdentifier where
139instance Hashable QualifiedIdentifier where
140 hashWithSalt i (QualifiedIdentifier q t) = hashWithSalt i (q, t)
140 hashWithSalt i (QualifiedIdentifier q t) = hashWithSalt i (q, t)
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.
142instance IsString QualifiedIdentifier where
149instance IsString QualifiedIdentifier where
143 fromString str = let (x,y) = T.break (== '.') (fromString str)
150 fromString str = let (x,y) = T.break (== '.') (fromString str)
144 in if T.null y
151 in if T.null y
@@ -173,26 +180,40 @@ newtype Savepoint = Savepoint Query
173 deriving (Eq, Ord, Show, Read, Typeable)
180 deriving (Eq, Ord, Show, Read, Typeable)
175-- | Represents a @VALUES@ table literal, usable as an alternative
182-- | 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:
178−-- > execute c "INSERT INTO table (key,val) ?"
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
179−-- > (Only (Values ["int4","text"]
198+-- > |] ("foo", Values [ "int4", "text" ]
180−-- > [(1,"hello"),(2,"world")]))
199+-- > [ ( 1 , "hello" )
200+-- > , ( 2 , "world" ) ])
182−-- Issues the following query:
202+-- (Note this example uses writable common table expressions,
203+-- which were added in PostgreSQL 9.1)
184−-- > INSERT INTO table (key,val) (VALUES (1::"int4",'hello'::"text"),(2,'world'))
205+-- The second parameter gets expanded into the following SQL syntax:
186−-- When the list of values is empty, the following query will be issued:
207+-- > (VALUES (1::"int4",'hello'::"text"),(2,'world'))
209+-- When the list of attributes is empty, the second parameter expands to:
188−-- > INSERT INTO table (key,val) (VALUES (null::"int4",null::"text") LIMIT 0)
211+-- > (VALUES (null::"int4",null::"text") LIMIT 0)
190-- By contrast, @executeMany@ and @returning@ don't issue the query
213-- By contrast, @executeMany@ and @returning@ don't issue the query
191-- in the empty case, and simply return @0@ and @[]@ respectively.
214-- in the empty case, and simply return @0@ and @[]@ respectively.
192−--
215+-- This behavior is usually correct given their intended use cases,
193−-- The advantage over @executeMany@ is in cases when you want to
216+-- but would certainly be wrong in the example above.
194−-- parameterize table literals in addition to other parameters, as can
195−-- occur with writable common table expressions, for example.
197-- The first argument is a list of postgresql type names. Because this
218-- The first argument is a list of postgresql type names. Because this
198-- is turned into a properly quoted identifier, the type name is case
219-- is turned into a properly quoted identifier, the type name is case