orville-postgresql 1.0.0.0 → 1.1.0.0

raw patch · 176 files changed

+13233/−3119 lines, 176 filesdep +unliftiodep ~containersdep ~hedgehogdep ~postgresql-libpqPVP ok

version bump matches the API change (PVP)

Dependencies added: unliftio

Dependency ranges changed: containers, hedgehog, postgresql-libpq, resource-pool, time

API changes (from Hackage documentation)

Files

• CHANGELOG.md +15/−2
• orville-postgresql.cabal +67/−19
• src/Orville/PostgreSQL.hs +84/−1
• src/Orville/PostgreSQL/AutoMigration.hs +534/−103
• src/Orville/PostgreSQL/ErrorDetailLevel.hs +9/−17
• src/Orville/PostgreSQL/Execution/Cursor.hs +8/−16
• src/Orville/PostgreSQL/Execution/Delete.hs +7/−14
• src/Orville/PostgreSQL/Execution/EntityOperations.hs +23/−46
• src/Orville/PostgreSQL/Execution/Execute.hs +7/−14
• src/Orville/PostgreSQL/Execution/ExecutionResult.hs +10/−16
• src/Orville/PostgreSQL/Execution/Insert.hs +8/−15
• src/Orville/PostgreSQL/Execution/QueryType.hs +1/−2
• src/Orville/PostgreSQL/Execution/ReturningOption.hs +2/−2
• src/Orville/PostgreSQL/Execution/Select.hs +10/−17
• src/Orville/PostgreSQL/Execution/SelectOptions.hs +89/−33
• src/Orville/PostgreSQL/Execution/Sequence.hs +3/−6
• src/Orville/PostgreSQL/Execution/Transaction.hs +190/−30
• src/Orville/PostgreSQL/Execution/Update.hs +11/−18
• src/Orville/PostgreSQL/Expr.hs +36/−2
• src/Orville/PostgreSQL/Expr/Aggregate.hs +502/−0
• src/Orville/PostgreSQL/Expr/BinaryOperator.hs +19/−4
• src/Orville/PostgreSQL/Expr/ColumnDefinition.hs +69/−20
• src/Orville/PostgreSQL/Expr/Comment.hs +79/−0
• src/Orville/PostgreSQL/Expr/ConditionalExpr.hs +130/−0
• src/Orville/PostgreSQL/Expr/Count.hs +11/−3
• src/Orville/PostgreSQL/Expr/Cursor.hs +26/−34
• src/Orville/PostgreSQL/Expr/DataType.hs +2/−4
• src/Orville/PostgreSQL/Expr/Delete.hs +12/−15
• src/Orville/PostgreSQL/Expr/Extension.hs +116/−0
• src/Orville/PostgreSQL/Expr/FetchClause.hs +100/−0
• src/Orville/PostgreSQL/Expr/Filter.hs +43/−0
• src/Orville/PostgreSQL/Expr/Function.hs +247/−0
• src/Orville/PostgreSQL/Expr/GroupBy.hs +5/−7
• src/Orville/PostgreSQL/Expr/IfExists.hs +2/−4
• src/Orville/PostgreSQL/Expr/IfNotExists.hs +44/−0
• src/Orville/PostgreSQL/Expr/Index.hs +16/−26
• src/Orville/PostgreSQL/Expr/Insert.hs +30/−16
• src/Orville/PostgreSQL/Expr/Internal/Name/Alias.hs +46/−0
• src/Orville/PostgreSQL/Expr/Internal/Name/ColumnName.hs +2/−4
• src/Orville/PostgreSQL/Expr/Internal/Name/ConstraintName.hs +2/−4
• src/Orville/PostgreSQL/Expr/Internal/Name/CursorName.hs +2/−4
• src/Orville/PostgreSQL/Expr/Internal/Name/ExtensionName.hs +44/−0
• src/Orville/PostgreSQL/Expr/Internal/Name/FunctionName.hs +194/−4
• src/Orville/PostgreSQL/Expr/Internal/Name/Identifier.hs +3/−6
• src/Orville/PostgreSQL/Expr/Internal/Name/IndexName.hs +2/−4
• src/Orville/PostgreSQL/Expr/Internal/Name/Qualified.hs +114/−25
• src/Orville/PostgreSQL/Expr/Internal/Name/SavepointName.hs +2/−4
• src/Orville/PostgreSQL/Expr/Internal/Name/SchemaName.hs +2/−4
• src/Orville/PostgreSQL/Expr/Internal/Name/SequenceName.hs +2/−4
• src/Orville/PostgreSQL/Expr/Internal/Name/TableName.hs +2/−4
• src/Orville/PostgreSQL/Expr/Internal/Name/TriggerName.hs +46/−0
• src/Orville/PostgreSQL/Expr/Internal/Name/WindowName.hs +46/−0
• src/Orville/PostgreSQL/Expr/Join.hs +189/−0
• src/Orville/PostgreSQL/Expr/LimitExpr.hs +1/−2
• src/Orville/PostgreSQL/Expr/Name.hs +5/−1
• src/Orville/PostgreSQL/Expr/OffsetExpr.hs +1/−2
• src/Orville/PostgreSQL/Expr/OnConflict.hs +193/−0
• src/Orville/PostgreSQL/Expr/OrReplace.hs +41/−0
• src/Orville/PostgreSQL/Expr/OrderBy.hs +35/−27
• src/Orville/PostgreSQL/Expr/Query.hs +147/−34
• src/Orville/PostgreSQL/Expr/ReturningExpr.hs +6/−5
• src/Orville/PostgreSQL/Expr/RowLocking.hs +150/−0
• src/Orville/PostgreSQL/Expr/Select.hs +47/−12
• src/Orville/PostgreSQL/Expr/SequenceDefinition.hs +71/−72
• src/Orville/PostgreSQL/Expr/TableConstraint.hs +30/−30
• src/Orville/PostgreSQL/Expr/TableDefinition.hs +129/−59
• src/Orville/PostgreSQL/Expr/TableReferenceList.hs +59/−15
• src/Orville/PostgreSQL/Expr/TextSearch.hs +466/−0
• src/Orville/PostgreSQL/Expr/Time.hs +15/−23
• src/Orville/PostgreSQL/Expr/Transaction.hs +55/−57
• src/Orville/PostgreSQL/Expr/Trigger.hs +270/−0
• src/Orville/PostgreSQL/Expr/Update.hs +85/−24
• src/Orville/PostgreSQL/Expr/Vacuum.hs +117/−0
• src/Orville/PostgreSQL/Expr/ValueExpression.hs +20/−23
• src/Orville/PostgreSQL/Expr/Values.hs +137/−0
• src/Orville/PostgreSQL/Expr/WhereClause.hs +73/−61
• src/Orville/PostgreSQL/Expr/Window.hs +17/−0
• src/Orville/PostgreSQL/Expr/Window/WindowClause.hs +89/−0
• src/Orville/PostgreSQL/Expr/Window/WindowDefinitionExpr.hs +309/−0
• src/Orville/PostgreSQL/Expr/Window/WindowFunction.hs +306/−0
• src/Orville/PostgreSQL/Extension/PgTrgm.hs +182/−0
• src/Orville/PostgreSQL/Internal/Bracket.hs +14/−12
• src/Orville/PostgreSQL/Internal/Extra/NonEmpty.hs +13/−0
• src/Orville/PostgreSQL/Internal/FieldName.hs +16/−15
• src/Orville/PostgreSQL/Internal/IndexDefinition.hs +40/−41
• src/Orville/PostgreSQL/Internal/MigrationLock.hs +91/−23
• src/Orville/PostgreSQL/Internal/MonadOrville.hs +28/−20
• src/Orville/PostgreSQL/Internal/OrvilleState.hs +43/−64
• src/Orville/PostgreSQL/Internal/RowCountExpectation.hs +14/−3
• src/Orville/PostgreSQL/Marshall.hs +5/−1
• src/Orville/PostgreSQL/Marshall/AliasName.hs +86/−0
• src/Orville/PostgreSQL/Marshall/DefaultValue.hs +18/−37
• src/Orville/PostgreSQL/Marshall/FieldDefinition.hs +325/−234
• src/Orville/PostgreSQL/Marshall/MarshallError.hs +20/−28
• src/Orville/PostgreSQL/Marshall/SqlComparable.hs +305/−0
• src/Orville/PostgreSQL/Marshall/SqlMarshaller.hs +264/−117
• src/Orville/PostgreSQL/Marshall/SqlType.hs +51/−43
• src/Orville/PostgreSQL/Marshall/SyntheticField.hs +79/−35
• src/Orville/PostgreSQL/Monad/HasOrvilleState.hs +10/−11
• src/Orville/PostgreSQL/Monad/Orville.hs +3/−6
• src/Orville/PostgreSQL/PgCatalog.hs +5/−1
• src/Orville/PostgreSQL/PgCatalog/DatabaseDescription.hs +170/−51
• src/Orville/PostgreSQL/PgCatalog/OidField.hs +2/−4
• src/Orville/PostgreSQL/PgCatalog/PgAttribute.hs +92/−42
• src/Orville/PostgreSQL/PgCatalog/PgAttributeDefault.hs +8/−13
• src/Orville/PostgreSQL/PgCatalog/PgClass.hs +26/−22
• src/Orville/PostgreSQL/PgCatalog/PgConstraint.hs +33/−36
• src/Orville/PostgreSQL/PgCatalog/PgDescription.hs +103/−0
• src/Orville/PostgreSQL/PgCatalog/PgExtension.hs +74/−0
• src/Orville/PostgreSQL/PgCatalog/PgIndex.hs +8/−16
• src/Orville/PostgreSQL/PgCatalog/PgNamespace.hs +15/−11
• src/Orville/PostgreSQL/PgCatalog/PgProc.hs +106/−0
• src/Orville/PostgreSQL/PgCatalog/PgSequence.hs +10/−22
• src/Orville/PostgreSQL/PgCatalog/PgTrigger.hs +109/−0
• src/Orville/PostgreSQL/Plan.hs +307/−209
• src/Orville/PostgreSQL/Plan/Explanation.hs +7/−10
• src/Orville/PostgreSQL/Plan/Many.hs +14/−23
• src/Orville/PostgreSQL/Plan/Operation.hs +100/−47
• src/Orville/PostgreSQL/Plan/Syntax.hs +1/−2
• src/Orville/PostgreSQL/Raw/Connection.hs +170/−104
• src/Orville/PostgreSQL/Raw/PgTextFormatValue.hs +21/−12
• src/Orville/PostgreSQL/Raw/PgTime.hs +145/−80
• src/Orville/PostgreSQL/Raw/RawSql.hs +135/−73
• src/Orville/PostgreSQL/Raw/SqlValue.hs +86/−98
• src/Orville/PostgreSQL/Schema.hs +13/−1
• src/Orville/PostgreSQL/Schema/ConstraintDefinition.hs +56/−48
• src/Orville/PostgreSQL/Schema/ExtensionIdentifier.hs +61/−0
• src/Orville/PostgreSQL/Schema/FunctionDefinition.hs +115/−0
• src/Orville/PostgreSQL/Schema/FunctionIdentifier.hs +128/−0
• src/Orville/PostgreSQL/Schema/IndexDefinition.hs +4/−0
• src/Orville/PostgreSQL/Schema/PrimaryKey.hs +19/−33
• src/Orville/PostgreSQL/Schema/SequenceDefinition.hs +25/−38
• src/Orville/PostgreSQL/Schema/SequenceIdentifier.hs +26/−23
• src/Orville/PostgreSQL/Schema/TableDefinition.hs +150/−79
• src/Orville/PostgreSQL/Schema/TableIdentifier.hs +26/−23
• src/Orville/PostgreSQL/Schema/TriggerDefinition.hs +192/−0
• src/Orville/PostgreSQL/UnliftIO.hs +4/−7
• test/Main.hs +17/−1
• test/Test/AutoMigration.hs +517/−22
• test/Test/Connection.hs +18/−0
• test/Test/Entities/Bar.hs +3/−1
• test/Test/Entities/Foo.hs +29/−0
• test/Test/Expr/Aggregate.hs +163/−0
• test/Test/Expr/ConditionalExpr.hs +75/−0
• test/Test/Expr/Count.hs +15/−3
• test/Test/Expr/Cursor.hs +18/−17
• test/Test/Expr/GroupBy.hs +21/−17
• test/Test/Expr/GroupByOrderBy.hs +19/−14
• test/Test/Expr/InsertUpdateDelete.hs +204/−32
• test/Test/Expr/Join.hs +78/−0
• test/Test/Expr/OrderBy.hs +50/−10
• test/Test/Expr/SequenceDefinition.hs +2/−2
• test/Test/Expr/TableDefinition.hs +49/−7
• test/Test/Expr/TableReferenceList.hs +42/−0
• test/Test/Expr/TestSchema.hs +36/−17
• test/Test/Expr/TextSearch.hs +130/−0
• test/Test/Expr/Trigger.hs +73/−0
• test/Test/Expr/Vacuum.hs +90/−0
• test/Test/Expr/Where.hs +57/−15
• test/Test/Expr/Window.hs +60/−0
• test/Test/FieldDefinition.hs +33/−11
• test/Test/MarshallError.hs +2/−6
• test/Test/Orphans.hs +23/−0
• test/Test/PgAssert.hs +271/−3
• test/Test/PgCatalog.hs +79/−1
• test/Test/PgGen.hs +22/−19
• test/Test/Plan.hs +265/−39
• test/Test/RawSql.hs +17/−8
• test/Test/SelectOptions.hs +46/−3
• test/Test/SqlCommenter.hs +4/−3
• test/Test/SqlMarshaller.hs +82/−5
• test/Test/SqlType.hs +72/−3
• test/Test/TableDefinition.hs +37/−2
• test/Test/TestTable.hs +2/−2
• test/Test/Transaction.hs +179/−8
• test/Test/Transaction/Util.hs +21/−10

@@ -1,5 +1,18 @@-# ChangeLog+# Changelog -## v1.0.0.0+All notable changes to this project will be documented in this file.++The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).++## [Unreleased]++### Added+### Changed+### Deprecated+### Removed+### Fixed+### Security++## [v1.0.0.0] - 2023-10-30  First official release.

@@ -1,11 +1,11 @@ cabal-version: 1.12 --- This file has been generated from package.yaml by hpack version 0.35.2.+-- This file has been generated from package.yaml by hpack version 0.38.1. -- -- see: https://github.com/sol/hpack  name:           orville-postgresql-version:        1.0.0.0+version:        1.1.0.0 synopsis:       A Haskell library for PostgreSQL description:    Orville's goal is to provide a powerful API for applications to access PostgreSQL databases with minimal use of sophisticated language techniques or extensions. See https://github.com/flipstone/orville for more details. category:       database, library, postgresql@@ -15,7 +15,7 @@ license-file:   LICENSE build-type:     Simple tested-with:-    GHC == 8.10.7, GHC == 9.0.2, GHC == 9.2.8, GHC == 9.4.7, GHC == 9.6.3+    GHC == 8.10.7, GHC == 9.0.2, GHC == 9.2.8, GHC == 9.4.8, GHC == 9.6.7, GHC == 9.8.4, GHC == 9.10.2, GHC == 9.12.2 extra-source-files:     CHANGELOG.md @@ -32,6 +32,7 @@   exposed-modules:       Orville.PostgreSQL       Orville.PostgreSQL.AutoMigration+      Orville.PostgreSQL.ErrorDetailLevel       Orville.PostgreSQL.Execution       Orville.PostgreSQL.Execution.Cursor       Orville.PostgreSQL.Execution.Delete@@ -46,39 +47,61 @@       Orville.PostgreSQL.Execution.Sequence       Orville.PostgreSQL.Execution.Transaction       Orville.PostgreSQL.Execution.Update-      Orville.PostgreSQL.ErrorDetailLevel       Orville.PostgreSQL.Expr+      Orville.PostgreSQL.Expr.Aggregate       Orville.PostgreSQL.Expr.BinaryOperator       Orville.PostgreSQL.Expr.ColumnDefinition+      Orville.PostgreSQL.Expr.Comment+      Orville.PostgreSQL.Expr.ConditionalExpr       Orville.PostgreSQL.Expr.Count       Orville.PostgreSQL.Expr.Cursor       Orville.PostgreSQL.Expr.DataType       Orville.PostgreSQL.Expr.Delete+      Orville.PostgreSQL.Expr.Extension+      Orville.PostgreSQL.Expr.FetchClause+      Orville.PostgreSQL.Expr.Filter+      Orville.PostgreSQL.Expr.Function       Orville.PostgreSQL.Expr.GroupBy       Orville.PostgreSQL.Expr.IfExists+      Orville.PostgreSQL.Expr.IfNotExists       Orville.PostgreSQL.Expr.Index       Orville.PostgreSQL.Expr.Insert+      Orville.PostgreSQL.Expr.Join       Orville.PostgreSQL.Expr.LimitExpr       Orville.PostgreSQL.Expr.Math       Orville.PostgreSQL.Expr.Name       Orville.PostgreSQL.Expr.OffsetExpr+      Orville.PostgreSQL.Expr.OnConflict+      Orville.PostgreSQL.Expr.OrReplace       Orville.PostgreSQL.Expr.OrderBy       Orville.PostgreSQL.Expr.Query       Orville.PostgreSQL.Expr.ReturningExpr+      Orville.PostgreSQL.Expr.RowLocking       Orville.PostgreSQL.Expr.Select       Orville.PostgreSQL.Expr.SequenceDefinition       Orville.PostgreSQL.Expr.TableConstraint       Orville.PostgreSQL.Expr.TableDefinition       Orville.PostgreSQL.Expr.TableReferenceList+      Orville.PostgreSQL.Expr.TextSearch       Orville.PostgreSQL.Expr.Time       Orville.PostgreSQL.Expr.Transaction+      Orville.PostgreSQL.Expr.Trigger       Orville.PostgreSQL.Expr.Update+      Orville.PostgreSQL.Expr.Vacuum       Orville.PostgreSQL.Expr.ValueExpression+      Orville.PostgreSQL.Expr.Values       Orville.PostgreSQL.Expr.WhereClause+      Orville.PostgreSQL.Expr.Window+      Orville.PostgreSQL.Expr.Window.WindowClause+      Orville.PostgreSQL.Expr.Window.WindowDefinitionExpr+      Orville.PostgreSQL.Expr.Window.WindowFunction+      Orville.PostgreSQL.Extension.PgTrgm       Orville.PostgreSQL.Marshall+      Orville.PostgreSQL.Marshall.AliasName       Orville.PostgreSQL.Marshall.DefaultValue       Orville.PostgreSQL.Marshall.FieldDefinition       Orville.PostgreSQL.Marshall.MarshallError+      Orville.PostgreSQL.Marshall.SqlComparable       Orville.PostgreSQL.Marshall.SqlMarshaller       Orville.PostgreSQL.Marshall.SqlType       Orville.PostgreSQL.Marshall.SyntheticField@@ -87,12 +110,12 @@       Orville.PostgreSQL.Monad.MonadOrville       Orville.PostgreSQL.Monad.Orville       Orville.PostgreSQL.OrvilleState+      Orville.PostgreSQL.PgCatalog       Orville.PostgreSQL.Plan       Orville.PostgreSQL.Plan.Explanation       Orville.PostgreSQL.Plan.Many       Orville.PostgreSQL.Plan.Operation       Orville.PostgreSQL.Plan.Syntax-      Orville.PostgreSQL.PgCatalog       Orville.PostgreSQL.Raw.Connection       Orville.PostgreSQL.Raw.PgTextFormatValue       Orville.PostgreSQL.Raw.PgTime@@ -101,17 +124,23 @@       Orville.PostgreSQL.Raw.SqlValue       Orville.PostgreSQL.Schema       Orville.PostgreSQL.Schema.ConstraintDefinition+      Orville.PostgreSQL.Schema.ExtensionIdentifier+      Orville.PostgreSQL.Schema.FunctionDefinition+      Orville.PostgreSQL.Schema.FunctionIdentifier       Orville.PostgreSQL.Schema.IndexDefinition       Orville.PostgreSQL.Schema.PrimaryKey       Orville.PostgreSQL.Schema.SequenceDefinition       Orville.PostgreSQL.Schema.SequenceIdentifier       Orville.PostgreSQL.Schema.TableDefinition       Orville.PostgreSQL.Schema.TableIdentifier+      Orville.PostgreSQL.Schema.TriggerDefinition       Orville.PostgreSQL.UnliftIO   other-modules:+      Orville.PostgreSQL.Expr.Internal.Name.Alias       Orville.PostgreSQL.Expr.Internal.Name.ColumnName       Orville.PostgreSQL.Expr.Internal.Name.ConstraintName       Orville.PostgreSQL.Expr.Internal.Name.CursorName+      Orville.PostgreSQL.Expr.Internal.Name.ExtensionName       Orville.PostgreSQL.Expr.Internal.Name.FunctionName       Orville.PostgreSQL.Expr.Internal.Name.Identifier       Orville.PostgreSQL.Expr.Internal.Name.IndexName@@ -120,6 +149,8 @@       Orville.PostgreSQL.Expr.Internal.Name.SchemaName       Orville.PostgreSQL.Expr.Internal.Name.SequenceName       Orville.PostgreSQL.Expr.Internal.Name.TableName+      Orville.PostgreSQL.Expr.Internal.Name.TriggerName+      Orville.PostgreSQL.Expr.Internal.Name.WindowName       Orville.PostgreSQL.Internal.Bracket       Orville.PostgreSQL.Internal.Extra.NonEmpty       Orville.PostgreSQL.Internal.FieldName@@ -134,9 +165,13 @@       Orville.PostgreSQL.PgCatalog.PgAttributeDefault       Orville.PostgreSQL.PgCatalog.PgClass       Orville.PostgreSQL.PgCatalog.PgConstraint+      Orville.PostgreSQL.PgCatalog.PgDescription+      Orville.PostgreSQL.PgCatalog.PgExtension       Orville.PostgreSQL.PgCatalog.PgIndex       Orville.PostgreSQL.PgCatalog.PgNamespace+      Orville.PostgreSQL.PgCatalog.PgProc       Orville.PostgreSQL.PgCatalog.PgSequence+      Orville.PostgreSQL.PgCatalog.PgTrigger       Paths_orville_postgresql   hs-source-dirs:       src@@ -144,23 +179,27 @@       attoparsec >=0.10 && <0.15     , base >=4.8 && <5     , bytestring >=0.10 && <0.13-    , containers ==0.6.*+    , containers >=0.6 && <0.9     , dlist >=0.8 && <1.1     , network-uri ==2.6.*-    , postgresql-libpq >=0.9.4.2 && <0.11+    , postgresql-libpq >=0.9.4.2 && <0.12     , random >=1.0 && <2-    , resource-pool <0.3 || >=0.4 && <0.5+    , resource-pool <0.3 || >=0.4 && <0.6     , safe-exceptions >=0.1.7 && <0.2     , text >=1.2 && <1.3 || >=2.0 && <2.2-    , time >=1.9.1 && <1.13+    , time >=1.9.1 && <1.16     , transformers >=0.5 && <0.7     , unliftio-core >=0.1 && <0.3     , uuid >=1.3.15 && <1.4   default-language: Haskell2010   if flag(ci)-    ghc-options: -Wall -Werror -Wcompat -Widentities -Wincomplete-uni-patterns -Wincomplete-patterns -Wincomplete-record-updates -Wmissing-local-signatures -Wmissing-export-lists -Wmissing-import-lists -Wnoncanonical-monad-instances -Wredundant-constraints -Wpartial-fields -Wmissed-specialisations -Wno-implicit-prelude -Wno-safe -Wno-unsafe-  else-    ghc-options: -Wall -fwarn-incomplete-uni-patterns -fwarn-incomplete-record-updates+    ghc-options: -Wall -Werror -Wcompat -Widentities -Wincomplete-uni-patterns -Wincomplete-patterns -Wincomplete-record-updates -Wmissing-local-signatures -Wmissing-export-lists -Wmissing-import-lists -Wmonomorphism-restriction -Wnoncanonical-monad-instances -Wpartial-fields -Wredundant-constraints -Wmissed-specialisations -Wno-implicit-prelude -Wno-safe -Wno-unsafe+    if impl (ghc >= 9.2)+      ghc-options: -Woperator-whitespace -Wredundant-bang-patterns+    if impl (ghc >= 9.4)+      ghc-options: -Wredundant-strictness-flags+    if impl (ghc >= 9.8)+      ghc-options: -Wterm-variable-capture  test-suite spec   type: exitcode-stdio-1.0@@ -176,20 +215,29 @@       Test.Entities.User       Test.EntityOperations       Test.Execution+      Test.Expr.Aggregate+      Test.Expr.ConditionalExpr       Test.Expr.Count       Test.Expr.Cursor       Test.Expr.GroupBy       Test.Expr.GroupByOrderBy       Test.Expr.InsertUpdateDelete+      Test.Expr.Join       Test.Expr.Math       Test.Expr.OrderBy       Test.Expr.SequenceDefinition       Test.Expr.TableDefinition+      Test.Expr.TableReferenceList       Test.Expr.TestSchema+      Test.Expr.TextSearch       Test.Expr.Time+      Test.Expr.Trigger+      Test.Expr.Vacuum       Test.Expr.Where+      Test.Expr.Window       Test.FieldDefinition       Test.MarshallError+      Test.Orphans       Test.PgAssert       Test.PgCatalog       Test.PgGen@@ -215,17 +263,17 @@       attoparsec >=0.10 && <0.15     , base >=4.8 && <5     , bytestring >=0.10 && <0.13-    , containers ==0.6.*-    , hedgehog >=1.0.5 && <1.5+    , containers >=0.6 && <0.9+    , hedgehog >=1.0.5 && <1.7     , orville-postgresql-    , postgresql-libpq >=0.9.4.2 && <0.11-    , resource-pool <0.3 || >=0.4 && <0.5+    , postgresql-libpq >=0.9.4.2 && <0.12+    , resource-pool <0.3 || >=0.4 && <0.6     , safe-exceptions >=0.1.7 && <0.2     , text >=1.2 && <1.3 || >=2.0 && <2.2-    , time >=1.9.1 && <1.13+    , time >=1.9.1 && <1.16+    , transformers >=0.5 && <0.7+    , unliftio >=0.1 && <0.3     , uuid >=1.3.15 && <1.4   default-language: Haskell2010   if flag(ci)     ghc-options: -j -Wall -Werror -Wcompat -Widentities -Wincomplete-uni-patterns -Wincomplete-record-updates -Wmissing-local-signatures -Wmissing-export-lists -Wno-implicit-prelude -Wno-safe -Wno-unsafe -Wnoncanonical-monad-instances -Wredundant-constraints -Wpartial-fields -Wmissed-specialisations -Woverflowed-literals-  else-    ghc-options: -Wall -Wcompat -Widentities -Wincomplete-uni-patterns -Wincomplete-record-updates -Wmissing-local-signatures -Wmissing-export-lists -Wno-implicit-prelude -Wno-safe -Wno-unsafe -Wnoncanonical-monad-instances -Wredundant-constraints -Wpartial-fields -Wmissed-specialisations -Woverflowed-literals

@@ -1,5 +1,5 @@ {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -70,6 +70,10 @@      -- * Opening transactions and savepoints   , Transaction.withTransaction+  , Transaction.withTransactionInstruction+  , Transaction.TransactionInstruction (Commit, Rollback)+  , Transaction.inWithTransaction+  , Transaction.InWithTransaction (InOutermostTransaction, InSavepointTransaction)      -- * Types for incorporating Orville into other Monads   , MonadOrville.MonadOrville@@ -97,10 +101,14 @@   , TableDefinition.mkTableDefinition   , TableDefinition.mkTableDefinitionWithoutKey   , TableDefinition.setTableSchema+  , TableDefinition.setTableComment+  , TableDefinition.tableComment   , TableDefinition.tableConstraints   , TableDefinition.addTableConstraints   , TableDefinition.tableIndexes   , TableDefinition.addTableIndexes+  , TableDefinition.tableTriggers+  , TableDefinition.addTableTriggers   , TableDefinition.dropColumns   , TableDefinition.columnsToDrop   , TableDefinition.tableIdentifier@@ -144,6 +152,21 @@   , IndexDefinition.IndexCreationStrategy (Transactional, Concurrent)   , IndexDefinition.setIndexCreationStrategy   , IndexDefinition.indexCreationStrategy+  , IndexDefinition.IndexMigrationKey (AttributeBasedIndexKey, NamedIndexKey)+  , IndexDefinition.AttributeBasedIndexMigrationKey (AttributeBasedIndexMigrationKey, indexKeyUniqueness, indexKeyColumns)+  , IndexDefinition.NamedIndexMigrationKey+  , IndexDefinition.indexMigrationKey+  , TriggerDefinition.TriggerDefinition+  , TriggerDefinition.beforeInsert+  , TriggerDefinition.afterInsert+  , TriggerDefinition.beforeUpdate+  , TriggerDefinition.afterUpdate+  , TriggerDefinition.beforeDelete+  , TriggerDefinition.afterDelete+  , TriggerDefinition.mkTriggerDefinition+  , TriggerDefinition.mkCreateTriggerExpr+  , TriggerDefinition.TriggerMigrationKey (NamedTriggerKey)+  , TriggerDefinition.triggerMigrationKey   , PrimaryKey.PrimaryKey   , PrimaryKey.primaryKey   , PrimaryKey.compositePrimaryKey@@ -161,17 +184,20 @@   , SqlMarshaller.marshallReadOnlyField   , SqlMarshaller.marshallPartial   , SqlMarshaller.marshallMaybe+  , SqlMarshaller.marshallQualifyFields   , SqlMarshaller.prefixMarshaller   , SqlMarshaller.foldMarshallerFields   , SqlMarshaller.collectFromField   , SqlMarshaller.ReadOnlyColumnOption (IncludeReadOnlyColumns, ExcludeReadOnlyColumns)   , SyntheticField.SyntheticField   , SyntheticField.syntheticFieldExpression+  , SyntheticField.syntheticFieldName   , SyntheticField.syntheticFieldAlias   , SyntheticField.syntheticFieldValueFromSqlValue   , SyntheticField.syntheticField   , SyntheticField.nullableSyntheticField   , SyntheticField.prefixSyntheticField+  , SyntheticField.orderBySyntheticField   , FieldDefinition.FieldDefinition   , FieldDefinition.NotNull   , FieldDefinition.Nullable@@ -220,6 +246,19 @@   , FieldDefinition.setField   , (FieldDefinition..:=)   , FieldDefinition.FieldNullability (NotNullField, NullableField)+  , FieldDefinition.QualifiedFieldDefinition+  , FieldDefinition.qualifyField+  , FieldDefinition.qualifiedFieldColumnName+  , FieldDefinition.FieldQualifier (qualifyColumnName)+  , FieldDefinition.markAsIdentity+  , FieldDefinition.unmarkIdentity+  , Marshall.AliasName+  , Marshall.stringToAliasName+  , Marshall.aliasNameToString+  , Marshall.aliasNameToAliasExpr+  , Marshall.aliasNameAndFieldNameToColumnName+  , Marshall.aliasNameToByteString+  , Marshall.byteStringToAliasName   , DefaultValue.DefaultValue   , DefaultValue.integerDefault   , DefaultValue.smallIntegerDefault@@ -250,10 +289,15 @@   , SelectOptions.where_   , SelectOptions.emptySelectOptions   , SelectOptions.appendSelectOptions+  , SelectOptions.forRowLock+  , SelectOptions.fetchRow+  , SelectOptions.window   , FieldDefinition.fieldEquals   , (FieldDefinition..==)   , FieldDefinition.fieldNotEquals   , (FieldDefinition../=)+  , FieldDefinition.fieldIsDistinctFrom+  , FieldDefinition.fieldIsNotDistinctFrom   , FieldDefinition.fieldGreaterThan   , (FieldDefinition..>)   , FieldDefinition.fieldLessThan@@ -279,15 +323,26 @@   , Expr.descendingOrder   , Expr.descendingOrderWith   , FieldDefinition.orderByField+  , Marshall.SqlComparable (toComparableSqlValue, referenceValueExpression)+  , Marshall.orderBySqlComparable   , Expr.orderByColumnName   , Expr.andExpr   , Expr.orExpr   , (Expr..&&)   , (Expr..||)+  , Expr.rowLockingClause+  , Expr.updateStrength+  , Expr.noKeyUpdateStrength+  , Expr.shareStrength+  , Expr.keyShareStrength+  , Expr.noWaitRowLockingOption+  , Expr.skipLockedRowLockingOption   , SelectOptions.selectGroupByClause   , SelectOptions.selectOrderByClause   , SelectOptions.selectWhereClause   , SelectOptions.selectDistinct+  , SelectOptions.selectRowLockingClause+  , SelectOptions.selectFetchClause      -- * Functions for defining and working with sequences   , Sequence.sequenceNextValue@@ -319,6 +374,29 @@   , SequenceIdentifier.sequenceIdSchemaNameString   , SequenceIdentifier.sequenceIdToString +    -- * Functions for defining and working with PostgreSQL functions+  , FunctionDefinition.FunctionDefinition+  , FunctionDefinition.setFunctionSchema+  , FunctionDefinition.mkTriggerFunction+  , FunctionDefinition.mkCreateFunctionExpr+  , FunctionDefinition.functionName+  , FunctionDefinition.functionIdentifier+  , FunctionDefinition.functionSource+  , FunctionIdentifier.FunctionIdentifier+  , FunctionIdentifier.unqualifiedNameToFunctionId+  , FunctionIdentifier.functionIdUnqualifiedNameString+  , FunctionIdentifier.functionIdQualifiedName+  , FunctionIdentifier.setFunctionIdSchema+  , FunctionIdentifier.functionIdSchemaNameString+  , FunctionIdentifier.functionIdToString+  , Expr.plpgsql++    -- * Functions for working with PostgreSQL extensions+  , ExtensionIdentifier.ExtensionIdentifier+  , ExtensionIdentifier.nameToExtensionId+  , ExtensionIdentifier.extensionIdName+  , ExtensionIdentifier.extensionIdToString+     -- * Numeric types   , SqlType.integer   , SqlType.serial@@ -374,6 +452,7 @@ import qualified Orville.PostgreSQL.Execution.Sequence as Sequence import qualified Orville.PostgreSQL.Execution.Transaction as Transaction import qualified Orville.PostgreSQL.Expr as Expr+import qualified Orville.PostgreSQL.Marshall as Marshall import qualified Orville.PostgreSQL.Marshall.DefaultValue as DefaultValue import qualified Orville.PostgreSQL.Marshall.FieldDefinition as FieldDefinition import qualified Orville.PostgreSQL.Marshall.SqlMarshaller as SqlMarshaller@@ -386,9 +465,13 @@ import qualified Orville.PostgreSQL.Raw.Connection as Connection import qualified Orville.PostgreSQL.Raw.SqlCommenter as SqlCommenter import qualified Orville.PostgreSQL.Schema.ConstraintDefinition as ConstraintDefinition+import qualified Orville.PostgreSQL.Schema.ExtensionIdentifier as ExtensionIdentifier+import qualified Orville.PostgreSQL.Schema.FunctionDefinition as FunctionDefinition+import qualified Orville.PostgreSQL.Schema.FunctionIdentifier as FunctionIdentifier import qualified Orville.PostgreSQL.Schema.IndexDefinition as IndexDefinition import qualified Orville.PostgreSQL.Schema.PrimaryKey as PrimaryKey import qualified Orville.PostgreSQL.Schema.SequenceDefinition as SequenceDefinition import qualified Orville.PostgreSQL.Schema.SequenceIdentifier as SequenceIdentifier import qualified Orville.PostgreSQL.Schema.TableDefinition as TableDefinition import qualified Orville.PostgreSQL.Schema.TableIdentifier as TableIdentifier+import qualified Orville.PostgreSQL.Schema.TriggerDefinition as TriggerDefinition

@@ -3,7 +3,7 @@ {-# LANGUAGE RankNTypes #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -13,7 +13,7 @@ @since 1.0.0.0 -} module Orville.PostgreSQL.AutoMigration-  ( MigrationOptions (runSchemaChanges, runConcurrentIndexCreations, migrationLockId)+  ( MigrationOptions (runSchemaChanges, runConcurrentIndexCreations, migrationLockOptions)   , defaultOptions   , autoMigrateSchema   , SchemaItem (..)@@ -24,6 +24,12 @@   , executeMigrationPlan   , MigrationStep   , MigrationDataError+  , MigrationLock.MigrationLockOptions+  , MigrationLock.defaultLockOptions+  , MigrationLock.migrationLockId+  , MigrationLock.maxLockAttempts+  , MigrationLock.delayBetweenLockAttemptsMicros+  , MigrationLock.lockDelayVariationMicros   , MigrationLock.MigrationLockId   , MigrationLock.defaultLockId   , MigrationLock.nextLockId@@ -42,6 +48,7 @@ import qualified Data.Maybe as Maybe import qualified Data.Set as Set import qualified Data.String as String+import qualified Data.Text as T import qualified Data.Text.Encoding as Enc import qualified Database.PostgreSQL.LibPQ as LibPQ @@ -49,12 +56,13 @@ import qualified Orville.PostgreSQL.Expr as Expr import qualified Orville.PostgreSQL.Internal.IndexDefinition as IndexDefinition import qualified Orville.PostgreSQL.Internal.MigrationLock as MigrationLock+import qualified Orville.PostgreSQL.Marshall as Marshall import qualified Orville.PostgreSQL.PgCatalog as PgCatalog import qualified Orville.PostgreSQL.Raw.RawSql as RawSql import qualified Orville.PostgreSQL.Schema as Schema+import qualified Orville.PostgreSQL.Schema.TableIdentifier as TableIdentifier -{- |-  A 'SchemaItem' represents a single item in a database schema such as a table,+{- | A 'SchemaItem' represents a single item in a database schema such as a table,   index or constraint. The constructor functions below can be used to create   items from other types (such as 'Orville.TableDefinition') to put them into   a list to be used with 'autoMigrateSchema'.@@ -62,35 +70,60 @@ @since 1.0.0.0 -} data SchemaItem where-  -- |-  --    Constructs a 'SchemaItem' from a 'Orville.TableDefinition'.+  -- | Constructs a 'SchemaItem' from a 'Orville.TableDefinition'.+  --   -- @since 1.0.0.0   SchemaTable ::     Orville.TableDefinition key writeEntity readEntity ->     SchemaItem-  -- |-  --    Constructs a 'SchemaItem' that will drop the specified table if it is+  -- | Constructs a 'SchemaItem' that will drop the specified table if it is   --    found in the database.+  --   -- @since 1.0.0.0   SchemaDropTable ::     Orville.TableIdentifier ->     SchemaItem-  -- |-  --    Constructs a 'SchemaItem' from a 'Orville.SequenceDefinition'.+  -- | Constructs a 'SchemaItem' from a 'Orville.SequenceDefinition'.+  --   -- @since 1.0.0.0   SchemaSequence ::     Orville.SequenceDefinition ->     SchemaItem-  -- |-  --    Constructs a 'SchemaItem' that will drop the specified table if it is-  --    found in the database.+  -- | Constructs a 'SchemaItem' that will drop the specified table if it is+  -- found in the database.+  --   -- @since 1.0.0.0   SchemaDropSequence ::     Orville.SequenceIdentifier ->     SchemaItem+  -- | Constructs a 'SchemaItem' from a 'Orville.FunctionDefinition'.+  --+  -- @since 1.1.0.0+  SchemaFunction ::+    Orville.FunctionDefinition ->+    SchemaItem+  -- | Constructs a 'SchemaItem' that will drop the specified table if it is+  -- found in the database.+  --+  -- @since 1.1.0.0+  SchemaDropFunction ::+    Orville.FunctionIdentifier ->+    SchemaItem+  -- | Constructs a 'SchemaItem' from a 'Orville.ExtensionName', that will load the extension.+  --+  -- @since 1.1.0.0+  SchemaExtension ::+    Orville.ExtensionIdentifier ->+    SchemaItem+  -- | Constructs a 'SchemaItem' that will unload the postgresql extension if it is found in the+  -- database.+  --+  -- @since 1.1.0.0+  SchemaDropExtension ::+    Orville.ExtensionIdentifier ->+    SchemaItem -{- |-  Returns a one-line string describing the 'SchemaItem', suitable for a human+{- | Returns a one-line string describing the 'SchemaItem', suitable for a human   to identify it in a list of output.    For example, a 'SchemaItem' constructed via 'SchemaTable' gives @Table <table@@ -109,6 +142,14 @@       "Sequence " <> Orville.sequenceIdToString (Orville.sequenceIdentifier sequenceDef)     SchemaDropSequence sequenceId ->       "Drop sequence " <> Orville.sequenceIdToString sequenceId+    SchemaFunction functionDef ->+      "Function " <> Orville.functionIdToString (Orville.functionIdentifier functionDef)+    SchemaDropFunction functionId ->+      "Drop function " <> Orville.functionIdToString functionId+    SchemaExtension extension ->+      "Extension " <> Orville.extensionIdToString extension+    SchemaDropExtension extension ->+      "Drop Extension " <> Orville.extensionIdToString extension  {- | A 'MigrationPlan' contains an ordered list of migration steps. Each one is a@@ -128,8 +169,7 @@   , i_concurrentIndexSteps :: [MigrationStep]   } -{- |-  Returns all the 'MigrationStep's found in a 'MigrationPlan' together in a+{- | Returns all the 'MigrationStep's found in a 'MigrationPlan' together in a   single list. This is useful if you merely want to examine the steps of a plan   rather than execute them. You should always use 'executeMigrationPlan' to   execute a migration plan to ensure that the transactional steps are done@@ -151,12 +191,11 @@         $ steps   in     MigrationPlan-      { i_transactionalSteps = map migrationStep transactionalSteps-      , i_concurrentIndexSteps = map migrationStep concurrentIndexSteps+      { i_transactionalSteps = fmap migrationStep transactionalSteps+      , i_concurrentIndexSteps = fmap migrationStep concurrentIndexSteps       } -{- |-  A single SQL statement that will be executed in order to migrate the database+{- | A single SQL statement that will be executed in order to migrate the database   to the desired result. You can use 'generateMigrationPlan' to get a list   of these yourself for inspection and debugging. @@ -169,8 +208,7 @@       RawSql.SqlExpression     ) -{- |-  This type is used internally by Orville to order the migration steps after+{- | This type is used internally by Orville to order the migration steps after   they have been created. It is not exposed outside this module.  @since 1.0.0.0@@ -197,14 +235,20 @@     DropForeignKeys -> True     DropUniqueConstraints -> True     DropIndexes -> True+    DropTriggers -> True+    DropFunctions -> True+    DropExtensions -> True+    AddExtensions -> True     AddRemoveTablesAndColumns -> True+    AddFunctions -> True+    AddTriggers -> True     AddIndexesTransactionally -> True     AddUniqueConstraints -> True     AddForeignKeys -> True     AddIndexesConcurrently -> False+    SetComments -> True -{- |-  Indicates the kind of operation being performed by a 'MigrationStep' so+{- | Indicates the kind of operation being performed by a 'MigrationStep' so   that the steps can be ordered in a sequence that is guaranteed to succeed.   The order of the constructors below indicates the order in which steps will   be run.@@ -212,14 +256,36 @@ @since 1.0.0.0 -} data StepType-  = DropForeignKeys-  | DropUniqueConstraints-  | DropIndexes-  | AddRemoveTablesAndColumns-  | AddIndexesTransactionally-  | AddUniqueConstraints-  | AddForeignKeys-  | AddIndexesConcurrently+  = -- | @since 1.0.0.0+    DropForeignKeys+  | -- | @since 1.0.0.0+    DropUniqueConstraints+  | -- | @since 1.0.0.0+    DropIndexes+  | -- | @since 1.1.0.0+    DropTriggers+  | -- | @since 1.1.0.0+    DropFunctions+  | -- | @since 1.1.0.0+    DropExtensions+  | -- | @since 1.1.0.0+    AddExtensions+  | -- | @since 1.0.0.0+    AddRemoveTablesAndColumns+  | -- | @since 1.1.0.0+    AddFunctions+  | -- | @since 1.1.0.0+    AddTriggers+  | -- | @since 1.0.0.0+    AddIndexesTransactionally+  | -- | @since 1.0.0.0+    AddUniqueConstraints+  | -- | @since 1.0.0.0+    AddForeignKeys+  | -- | @since 1.0.0.0+    AddIndexesConcurrently+  | -- | @since 1.1.0.0+    SetComments   deriving     ( -- | @since 1.0.0.0       Eq@@ -227,8 +293,7 @@       Ord     ) -{- |-  A 'MigrationDataError' will be thrown from the migration functions if data+{- | A 'MigrationDataError' will be thrown from the migration functions if data   necessary for migration cannot be found.  @since 1.0.0.0@@ -268,15 +333,17 @@   --       rest of the schema changes.   --   --       @since 1.0.0.0-  , migrationLockId :: MigrationLock.MigrationLockId+  , migrationLockOptions :: MigrationLock.MigrationLockOptions   -- ^-  --       The 'MigrationLock.MigrationLockId' that will be use to ensure only+  --       The 'MigrationLock.MigrationLockOptions' that will be used to ensure only   --       one application is running migrations at a time. The default value-  --       is 'MigrationLock.defaultLockId'. You may want to change this if you-  --       want to run concurrent index creations separately from the rest of-  --       the schema changes without blocking one another.+  --       is 'MigrationLock.defaultLockOptions'. You may want to change these if you+  --       your application has special migration needs. For instance, you might specify+  --       a custom lock id along with migrating just concurrent indexes to allow them+  --       to run separately from the rest of the schema changes without blocking one+  --       another.   ---  --       @since 1.0.0.0+  --       @since 1.1.0.0   }  {- |@@ -290,11 +357,10 @@   MigrationOptions     { runSchemaChanges = True     , runConcurrentIndexCreations = True-    , migrationLockId = MigrationLock.defaultLockId+    , migrationLockOptions = MigrationLock.defaultLockOptions     } -{- |-  This function compares the list of 'SchemaItem's provided against the current+{- | This function compares the list of 'SchemaItem's provided against the current   schema found in the database to determine whether any migrations are   necessary.  If any changes need to be made, this function executes. You can   call 'generateMigrationPlan' and 'executeMigrationPlan' yourself if you want@@ -312,12 +378,11 @@   [SchemaItem] ->   m () autoMigrateSchema options schemaItems =-  MigrationLock.withMigrationLock (migrationLockId options) $ do+  MigrationLock.withMigrationLock (migrationLockOptions options) $ do     plan <- generateMigrationPlanWithoutLock schemaItems     executeMigrationPlanWithoutLock options plan -{- |-  Compares the list of 'SchemaItem's provided against the current schema found+{- | Compares the list of 'SchemaItem's provided against the current schema found   in the database and returns a 'MigrationPlan' that could be executed to make   the database schema match the items given. @@ -337,7 +402,7 @@   [SchemaItem] ->   m MigrationPlan generateMigrationPlan options =-  MigrationLock.withMigrationLock (migrationLockId options)+  MigrationLock.withMigrationLock (migrationLockOptions options)     . generateMigrationPlanWithoutLock  generateMigrationPlanWithoutLock :: Orville.MonadOrville m => [SchemaItem] -> m MigrationPlan@@ -346,18 +411,27 @@     currentNamespace <- findCurrentNamespace      let-      pgCatalogRelations = fmap (schemaItemPgCatalogRelation currentNamespace) schemaItems+      pgCatalogRelations =+        Maybe.mapMaybe+          (schemaItemPgCatalogRelation currentNamespace)+          schemaItems -    dbDesc <- PgCatalog.describeDatabaseRelations pgCatalogRelations+      pgCatalogFunctions =+        Maybe.mapMaybe+          (schemaItemPgCatalogFunction currentNamespace)+          schemaItems+      pgCatalogExtensions =+        Maybe.mapMaybe schemaItemPgCatalogExtension schemaItems +    dbDesc <- PgCatalog.describeDatabase pgCatalogRelations pgCatalogFunctions pgCatalogExtensions+     case traverse (calculateMigrationSteps currentNamespace dbDesc) schemaItems of       Left err ->         liftIO . throwIO $ err       Right migrationSteps ->         pure . mkMigrationPlan . concat $ migrationSteps -{- |-  Executes a 'MigrationPlan' that has been previously devised via+{- | Executes a 'MigrationPlan' that has been previously devised via   'generateMigrationPlan'. Normally all the steps in a migration plan are   executed in a transaction so that they will all be applied together   successfully or all rolled-back if one of them fails. Any indexes using the@@ -381,7 +455,7 @@   MigrationPlan ->   m () executeMigrationPlan options =-  MigrationLock.withMigrationLock (migrationLockId options)+  MigrationLock.withMigrationLock (migrationLockOptions options)     . executeMigrationPlanWithoutLock options  executeMigrationPlanWithoutLock ::@@ -398,8 +472,7 @@    when (runConcurrentIndexCreations options)     . executeMigrationStepsWithoutTransaction-    $ i_concurrentIndexSteps-    $ plan+    $ i_concurrentIndexSteps plan  executeMigrationStepsWithoutTransaction :: Orville.MonadOrville m => [MigrationStep] -> m () executeMigrationStepsWithoutTransaction =@@ -482,9 +555,68 @@                   AddRemoveTablesAndColumns                   (Expr.dropSequenceExpr Nothing (Orville.sequenceIdQualifiedName sequenceId))               ]+    SchemaFunction functionDef ->+      Right $+        let+          (schemaName, procName) =+            functionIdToPgCatalogNames currentNamespace (Orville.functionIdentifier functionDef)+        in+          case PgCatalog.lookupProcedure (schemaName, procName) dbDesc of+            Nothing ->+              [ mkMigrationStepWithType+                  AddFunctions+                  (Orville.mkCreateFunctionExpr functionDef Nothing)+              ]+            Just pgProc ->+              if PgCatalog.pgProcSource pgProc == T.pack (Orville.functionSource functionDef)+                then []+                else+                  [ mkMigrationStepWithType+                      AddFunctions+                      (Orville.mkCreateFunctionExpr functionDef (Just Expr.orReplace))+                  ]+    SchemaDropFunction functionId ->+      Right $+        let+          (schemaName, procName) =+            functionIdToPgCatalogNames currentNamespace functionId+        in+          case PgCatalog.lookupProcedure (schemaName, procName) dbDesc of+            Nothing ->+              []+            Just _proc ->+              [ mkMigrationStepWithType+                  DropFunctions+                  (Expr.dropFunction Nothing (Orville.functionIdQualifiedName functionId))+              ]+    SchemaExtension extension ->+      Right $+        let+          catalogExtensionName = extensionIdToPgCatalogName extension+        in+          case PgCatalog.lookupExtension catalogExtensionName dbDesc of+            Nothing ->+              [ mkMigrationStepWithType+                  AddExtensions+                  (Expr.createExtensionExpr (Orville.extensionIdName extension) Nothing (Just Expr.extensionCascadeExpr))+              ]+            Just _pgExtension ->+              []+    SchemaDropExtension extension ->+      Right $+        let+          catalogExtensionName = extensionIdToPgCatalogName extension+        in+          case PgCatalog.lookupExtension catalogExtensionName dbDesc of+            Nothing ->+              []+            Just _pgExtension ->+              [ mkMigrationStepWithType+                  DropExtensions+                  (Expr.dropExtensionExpr (Orville.extensionIdName extension) Nothing Nothing)+              ] -{- |-  Builds 'MigrationStep's that will perform table creation. This function+{- | Builds 'MigrationStep's that will perform table creation. This function   assumes the table does not exist. The migration step it produces will fail if   the table already exists in its schema. Multiple steps may be required to   create the table if foreign keys exist to that reference other tables, which@@ -511,6 +643,8 @@         (Orville.mkTablePrimaryKeyExpr tableDef)         [] +    commentSteps = mkCreateTableCommentSteps tableDef+     addConstraintActions =       concatMap         (mkAddConstraintActions currentNamespace Set.empty)@@ -520,13 +654,62 @@       concatMap         (mkAddIndexSteps Set.empty tableName)         (Orville.tableIndexes tableDef)++    addTriggerSteps =+      concatMap+        (mkAddTriggerSteps Set.empty tableName)+        (Orville.tableTriggers tableDef)   in     mkMigrationStepWithType AddRemoveTablesAndColumns createTableExpr       : mkConstraintSteps tableName addConstraintActions         <> addIndexSteps+        <> addTriggerSteps+        <> commentSteps -{- |-  Builds migration steps that are required to create or alter the table's+mkCreateTableCommentSteps ::+  Orville.TableDefinition key writeEntity readEntity ->+  [MigrationStepWithType]+mkCreateTableCommentSteps tableDef =+  let+    mbCommentTableStep =+      fmap+        ( mkMigrationStepWithType SetComments+            . Expr.commentTableExpr (Schema.tableName tableDef)+            . Just+            . Expr.commentText+        )+        (Schema.tableComment tableDef)++    tableId = Orville.tableIdentifier tableDef++    mbCommentColumnStep colName =+      fmap+        ( mkMigrationStepWithType SetComments+            . Expr.commentColumnExpr+              (Schema.tableIdSchemaName tableId)+              (Schema.tableIdUnqualifiedName tableId)+              colName+            . Just+            . Expr.commentText+            . T.pack+        )++    mbCommentColumnsSteps =+      Orville.foldMarshallerFields+        (Orville.unannotatedSqlMarshaller $ Schema.tableMarshaller tableDef)+        []+        ( Orville.collectFromField+            Orville.IncludeReadOnlyColumns+            ( const $ \fieldDef ->+                mbCommentColumnStep+                  (Orville.fieldNameToColumnName $ Orville.fieldName fieldDef)+                  (Orville.fieldDescription fieldDef)+            )+        )+  in+    Maybe.catMaybes (mbCommentTableStep : mbCommentColumnsSteps)++{- | Builds migration steps that are required to create or alter the table's   schema to make it match the given table definition.    This function uses the given relation description to determine what@@ -547,7 +730,7 @@         Orville.foldMarshallerFields           (Orville.unannotatedSqlMarshaller $ Orville.tableMarshaller tableDef)           []-          (Orville.collectFromField Orville.IncludeReadOnlyColumns (mkAddAlterColumnActions relationDesc))+          (Orville.collectFromField Orville.IncludeReadOnlyColumns (const (mkAddAlterColumnActions relationDesc)))      dropColumnActions =       concatMap@@ -606,9 +789,32 @@      dropIndexSteps =       concatMap-        (mkDropIndexSteps indexesToKeep systemIndexOids)+        (mkDropIndexSteps indexesToKeep systemIndexOids . TableIdentifier.tableIdSchemaName $ Orville.tableIdentifier tableDef)         (PgCatalog.relationIndexes relationDesc) +    existingTriggers =+      Set.fromList+        . fmap pgTriggerMigrationKey+        . PgCatalog.relationTriggers+        $ relationDesc++    triggersToKeep =+      Map.keysSet+        . Orville.tableTriggers+        $ tableDef++    addTriggerSteps =+      concatMap+        (mkAddTriggerSteps existingTriggers tableName)+        (Orville.tableTriggers tableDef)++    dropTriggerSteps =+      concatMap+        (mkDropTriggerSteps triggersToKeep tableName)+        (PgCatalog.relationTriggers relationDesc)++    commentSteps = mkCommentSteps relationDesc tableDef+     tableName =       Orville.tableName tableDef   in@@ -616,9 +822,11 @@       <> mkConstraintSteps tableName (addConstraintActions <> dropConstraintActions)       <> addIndexSteps       <> dropIndexSteps+      <> addTriggerSteps+      <> dropTriggerSteps+      <> commentSteps -{- |-  Consolidates alter table actions (which should all be related to adding and+{- | Consolidates alter table actions (which should all be related to adding and   dropping constraints) into migration steps based on their 'StepType'. Actions   with the same 'StepType' will be performed togethir in a single @ALTER TABLE@   statement.@@ -626,7 +834,7 @@ @since 1.0.0.0 -} mkConstraintSteps ::-  Expr.Qualified Expr.TableName ->+  Expr.QualifiedOrUnqualified Expr.TableName ->   [(StepType, Expr.AlterTableAction)] ->   [MigrationStepWithType] mkConstraintSteps tableName actions =@@ -635,24 +843,23 @@       (StepType, Expr.AlterTableAction) ->       (StepType, NonEmpty Expr.AlterTableAction)     mkMapEntry (keyType, action) =-      (keyType, (action :| []))+      (keyType, action :| [])      addStep stepType actionExprs steps =       mkMigrationStepWithType stepType (Expr.alterTableExpr tableName actionExprs) : steps   in     Map.foldrWithKey addStep []       . Map.fromListWith (<>)-      . map mkMapEntry+      . fmap mkMapEntry       $ actions -{- |-  If there are any alter table actions for adding or removing columns, creates a migration+{- | If there are any alter table actions for adding or removing columns, creates a migration   step to perform them. Otherwise returns an empty list.  @since 1.0.0.0 -} mkAlterColumnSteps ::-  Expr.Qualified Expr.TableName ->+  Expr.QualifiedOrUnqualified Expr.TableName ->   [Expr.AlterTableAction] ->   [MigrationStepWithType] mkAlterColumnSteps tableName actionExprs =@@ -662,8 +869,7 @@     Just nonEmptyActionExprs ->       [mkMigrationStepWithType AddRemoveTablesAndColumns (Expr.alterTableExpr tableName nonEmptyActionExprs)] -{- |-  Builds 'Expr.AlterTableAction' expressions to bring the database schema in+{- | Builds 'Expr.AlterTableAction' expressions to bring the database schema in   line with the given 'Orville.FieldDefinition', or none if no change is   required. @@ -690,7 +896,7 @@                   || (Orville.sqlTypeMaximumLength sqlType /= PgCatalog.pgAttributeMaxLength attr)                columnName =-                Orville.fieldColumnName fieldDef+                Orville.fieldNameToColumnName $ Orville.fieldName fieldDef                dataType =                 Orville.sqlTypeExpr sqlType@@ -709,7 +915,7 @@                alterNullability = do                 guard nullabilityIsChanged-                [Expr.alterColumnNullability (Orville.fieldColumnName fieldDef) nullabilityAction]+                [Expr.alterColumnNullability columnName nullabilityAction]                maybeExistingDefault =                 PgCatalog.lookupAttributeDefault attr relationDesc@@ -749,8 +955,28 @@                           ( Just (Expr.alterColumnDropDefault columnName)                           , Just (Expr.alterColumnSetDefault columnName newDefault)                           )++              alterIdentity =+                case (Marshall.fieldIdentityGeneration fieldDef, PgCatalog.pgAttributeIdentity attr) of+                  (Nothing, Nothing) -> mempty+                  (Just Marshall.GeneratedAlways, Just Marshall.GeneratedAlways) -> mempty+                  (Just Marshall.GeneratedByDefault, Just Marshall.GeneratedByDefault) -> mempty+                  (Nothing, Just _) ->+                    pure $ Expr.alterColumnDropIdentity columnName Nothing+                  (Just Marshall.GeneratedAlways, Nothing) ->+                    pure $ Expr.alterColumnAddIdentity columnName Expr.alwaysColumnIdentityGeneration+                  (Just Marshall.GeneratedAlways, Just _existing) ->+                    [Expr.alterColumnDropIdentity columnName Nothing, Expr.alterColumnAddIdentity columnName Expr.alwaysColumnIdentityGeneration]+                  (Just Marshall.GeneratedByDefault, Nothing) ->+                    pure $ Expr.alterColumnAddIdentity columnName Expr.byDefaultColumnIdentityGeneration+                  (Just Marshall.GeneratedByDefault, Just _existing) ->+                    [Expr.alterColumnDropIdentity columnName Nothing, Expr.alterColumnAddIdentity columnName Expr.byDefaultColumnIdentityGeneration]             in-              Maybe.maybeToList dropDefault <> alterType <> Maybe.maybeToList setDefault <> alterNullability+              Maybe.maybeToList dropDefault+                <> alterType+                <> Maybe.maybeToList setDefault+                <> alterNullability+                <> alterIdentity       _ ->         -- Either the column doesn't exist in the table _OR_ it's a system         -- column. If it's a system column, attempting to add it will result@@ -762,8 +988,7 @@         -- attributes.         [Expr.addColumn (Orville.fieldColumnDefinition fieldDef)] -{- |-  Builds 'Expr.AlterTableAction' expressions for the given attribute to make+{- | Builds 'Expr.AlterTableAction' expressions for the given attribute to make   the database schema match the given 'Orville.TableDefinition'. This function   is only responsible for handling cases where the attribute does not have a   correspending 'Orville.FieldDefinition'. See 'mkAlterTableSteps' for those@@ -784,8 +1009,7 @@    [Expr.dropColumn $ Expr.columnName attrName] -{- |-  Sets the schema name on a constraint to the given namespace when the+{- | Sets the schema name on a constraint to the given namespace when the   constraint has no namespace explicitly given. This is important for Orville   to discover whether a constraint from a table definition matches a constraint   found to already exist in the database because constraints in the database@@ -814,8 +1038,7 @@         Just _ ->           constraintKey -{- |-  Builds 'Expr.AlterTableAction' expressions to create the given table+{- | Builds 'Expr.AlterTableAction' expressions to create the given table   constraint if it does not exist.  @since 1.0.0.0@@ -840,8 +1063,7 @@       then []       else [(stepType, Expr.addConstraint (Orville.constraintSqlExpr constraintDef))] -{- |-  Builds 'Expr.AlterTableAction' expressions to drop the given table+{- | Builds 'Expr.AlterTableAction' expressions to drop the given table   constraint if it should not exist.  @since 1.0.0.0@@ -873,8 +1095,7 @@           in             [(stepType, Expr.dropConstraint constraintName)] -{- |-  Builds the orville migration key for a description of an existing constraint+{- | Builds the orville migration key for a description of an existing constraint   so that it can be compared with constraints found in a table definition.   Constraint keys built this way always have a schema name populated, so it's   important to set the schema names for the constraints found in the table@@ -899,8 +1120,9 @@     constraint =       PgCatalog.constraintRecord constraintDesc +    pgAttributeNamesToFieldNames :: [PgCatalog.PgAttribute] -> [Orville.FieldName]     pgAttributeNamesToFieldNames =-      map (Orville.stringToFieldName . PgCatalog.attributeNameToString . PgCatalog.pgAttributeName)+      fmap (Orville.stringToFieldName . PgCatalog.attributeNameToString . PgCatalog.pgAttributeName)      foreignRelationTableId :: PgCatalog.ForeignRelationDescription -> Orville.TableIdentifier     foreignRelationTableId foreignRelationDesc =@@ -941,14 +1163,13 @@               PgCatalog.pgConstraintForeignKeyOnDeleteType $ PgCatalog.constraintRecord constraintDesc           } -{- |-  Builds migration steps to create an index if it does not exist.+{- | Builds migration steps to create an index if it does not exist.  @since 1.0.0.0 -} mkAddIndexSteps ::   Set.Set IndexDefinition.IndexMigrationKey ->-  Expr.Qualified Expr.TableName ->+  Expr.QualifiedOrUnqualified Expr.TableName ->   Orville.IndexDefinition ->   [MigrationStepWithType] mkAddIndexSteps existingIndexes tableName indexDef =@@ -965,17 +1186,17 @@       then []       else [mkMigrationStepWithType indexStep (Orville.indexCreateExpr indexDef tableName)] -{- |-  Builds migration steps to drop an index if it should not exist.+{- | Builds migration steps to drop an index if it should not exist.  @since 1.0.0.0 -} mkDropIndexSteps ::   Set.Set IndexDefinition.IndexMigrationKey ->   Set.Set LibPQ.Oid ->+  Maybe Expr.SchemaName ->   PgCatalog.IndexDescription ->   [MigrationStepWithType]-mkDropIndexSteps indexesToKeep systemIndexOids indexDesc =+mkDropIndexSteps indexesToKeep systemIndexOids mSchema indexDesc =   case pgIndexMigrationKeys indexDesc of     [] ->       []@@ -990,16 +1211,122 @@             . PgCatalog.pgClassRelationName             $ pgClass +        qualifiedIndexName = case mSchema of+          Just schema -> Expr.untrackQualified $ Expr.qualifyIndex schema indexName+          Nothing -> Expr.unqualified indexName+         indexOid =           PgCatalog.pgClassOid pgClass       in         if any (flip Set.member indexesToKeep) indexKeys           || Set.member indexOid systemIndexOids           then []-          else [mkMigrationStepWithType DropIndexes (Expr.dropIndexExpr indexName)]+          else [mkMigrationStepWithType DropIndexes (Expr.dropIndexExpr qualifiedIndexName)] -{- |-  Primary Key, Unique, and Exclusion constraints automatically create indexes+{- | Builds migration steps to create a trigger if it does not exist.++@since 1.1.0.0+-}+mkAddTriggerSteps ::+  Set.Set Schema.TriggerMigrationKey ->+  Expr.QualifiedOrUnqualified Expr.TableName ->+  Orville.TriggerDefinition ->+  [MigrationStepWithType]+mkAddTriggerSteps existingTriggers tableName triggerDef =+  let+    triggerKey =+      Schema.triggerMigrationKey triggerDef+  in+    if Set.member triggerKey existingTriggers+      then []+      else [mkMigrationStepWithType AddTriggers (Orville.mkCreateTriggerExpr triggerDef Nothing tableName)]++{- | Builds migration steps to drop an trigger if it should not exist.++@since 1.1.0.0+-}+mkDropTriggerSteps ::+  Set.Set Schema.TriggerMigrationKey ->+  Expr.QualifiedOrUnqualified Expr.TableName ->+  PgCatalog.PgTrigger ->+  [MigrationStepWithType]+mkDropTriggerSteps triggersToKeep tableName pgTrigger =+  let+    migrationKey =+      pgTriggerMigrationKey pgTrigger++    triggerName =+      Expr.triggerName+        . PgCatalog.triggerNameToString+        . PgCatalog.pgTriggerName+        $ pgTrigger+  in+    if Set.member migrationKey triggersToKeep || PgCatalog.pgTriggerIsInternal pgTrigger+      then []+      else [mkMigrationStepWithType DropTriggers (Expr.dropTrigger Nothing triggerName tableName)]++mkCommentSteps ::+  PgCatalog.RelationDescription ->+  Orville.TableDefinition key writeEntity readEntity ->+  [MigrationStepWithType]+mkCommentSteps relationDesc tableDef =+  let+    tableName = Orville.tableName tableDef++    commentTableStep =+      if PgCatalog.relationComment relationDesc == Schema.tableComment tableDef+        then []+        else+          [ mkMigrationStepWithType+              SetComments+              ( Expr.commentTableExpr+                  tableName+                  (fmap Expr.commentText (Schema.tableComment tableDef))+              )+          ]++    commentColumnsSteps =+      Maybe.catMaybes $+        Orville.foldMarshallerFields+          (Orville.unannotatedSqlMarshaller $ Orville.tableMarshaller tableDef)+          []+          ( Orville.collectFromField+              Orville.IncludeReadOnlyColumns+              (const . mkCommentColumnStep relationDesc $ Orville.tableIdentifier tableDef)+          )+  in+    commentTableStep <> commentColumnsSteps++mkCommentColumnStep ::+  PgCatalog.RelationDescription ->+  Schema.TableIdentifier ->+  Orville.FieldDefinition n a ->+  Maybe MigrationStepWithType+mkCommentColumnStep relationDesc tableId fieldDef =+  let+    fieldAttributeName =+      String.fromString (Orville.fieldNameToString $ Orville.fieldName fieldDef)++    currentFieldComment =+      PgCatalog.lookupAttributeComment fieldAttributeName relationDesc++    targetFieldComment =+      fmap T.pack (Orville.fieldDescription fieldDef)+  in+    if currentFieldComment == targetFieldComment+      then Nothing+      else+        Just $+          mkMigrationStepWithType+            SetComments+            ( Expr.commentColumnExpr+                (Schema.tableIdSchemaName tableId)+                (Schema.tableIdUnqualifiedName tableId)+                (Orville.fieldNameToColumnName $ Orville.fieldName fieldDef)+                (fmap Expr.commentText targetFieldComment)+            )++{- | Primary Key, Unique, and Exclusion constraints automatically create indexes   that we don't want orville to consider for the purposes of migrations. This   function checks the constraint type and returns the OID of the supporting   index if the constraint is one of these types.@@ -1026,8 +1353,7 @@     PgCatalog.ConstraintTrigger ->       Nothing -{- |-  Builds the orville migration keys given a description of an existing index+{- | Builds the orville migration keys given a description of an existing index   so that it can be compared with indexs found in a table definition.    If the description includes expressions as members of the index rather than@@ -1053,7 +1379,7 @@         Nothing ->           []   in-    [mkNamedIndexKey] ++ mkAttributeBasedIndexKey+    mkNamedIndexKey : mkAttributeBasedIndexKey  pgAttributeBasedIndexMigrationKey ::   PgCatalog.IndexDescription ->@@ -1079,21 +1405,102 @@       , IndexDefinition.indexKeyColumns = fieldNames       } +{- | Builds the orville migration key given a description of an existing trigger+  so that it can be compared with triggers found in a table definition.++  If the description includes expressions as members of the trigger rather than+  simple attributes, 'Nothing' is returned.++@since 1.1.0.0+-}+pgTriggerMigrationKey ::+  PgCatalog.PgTrigger ->+  Schema.TriggerMigrationKey+pgTriggerMigrationKey =+  Schema.NamedTriggerKey+    . PgCatalog.triggerNameToString+    . PgCatalog.pgTriggerName++{- | Retrieves from a 'SchemaItem' the relation (if any) that the schema item relates to+  so that the migration infrastructure can look up data about it in the PostgreSQL+  catalog for planning migration steps.+-} schemaItemPgCatalogRelation ::   PgCatalog.NamespaceName ->   SchemaItem ->-  (PgCatalog.NamespaceName, PgCatalog.RelationName)+  Maybe (PgCatalog.NamespaceName, PgCatalog.RelationName) schemaItemPgCatalogRelation currentNamespace item =   case item of     SchemaTable tableDef ->-      tableIdToPgCatalogNames currentNamespace (Orville.tableIdentifier tableDef)+      Just $ tableIdToPgCatalogNames currentNamespace (Orville.tableIdentifier tableDef)     SchemaDropTable tableId ->-      tableIdToPgCatalogNames currentNamespace tableId+      Just $ tableIdToPgCatalogNames currentNamespace tableId     SchemaSequence sequenceDef ->-      sequenceIdToPgCatalogNames currentNamespace (Orville.sequenceIdentifier sequenceDef)+      Just $ sequenceIdToPgCatalogNames currentNamespace (Orville.sequenceIdentifier sequenceDef)     SchemaDropSequence sequenceId ->-      sequenceIdToPgCatalogNames currentNamespace sequenceId+      Just $ sequenceIdToPgCatalogNames currentNamespace sequenceId+    SchemaFunction _functionDef ->+      Nothing+    SchemaDropFunction _functionId ->+      Nothing+    SchemaExtension _extension ->+      Nothing+    SchemaDropExtension _extension ->+      Nothing +{- | Retrieves from a 'SchemaItem' the function (if any) that the schema item relates to+  so that the migration infrastructure can look up data about it in the PostgreSQL+  catalog for planning migration steps.+-}+schemaItemPgCatalogFunction ::+  PgCatalog.NamespaceName ->+  SchemaItem ->+  Maybe (PgCatalog.NamespaceName, PgCatalog.ProcName)+schemaItemPgCatalogFunction currentNamespace item =+  case item of+    SchemaTable _tableDef ->+      Nothing+    SchemaDropTable _tableId ->+      Nothing+    SchemaSequence _sequenceDef ->+      Nothing+    SchemaDropSequence _sequenceId ->+      Nothing+    SchemaFunction functionDef ->+      Just $ functionIdToPgCatalogNames currentNamespace (Orville.functionIdentifier functionDef)+    SchemaDropFunction functionId ->+      Just $ functionIdToPgCatalogNames currentNamespace functionId+    SchemaExtension _extension ->+      Nothing+    SchemaDropExtension _extension ->+      Nothing++{- | Retrieves from a 'SchemaItem' the extension (if any) that the schema item relates to+  so that the migration infrastructure can look up data about it in the PostgreSQL+  catalog for planning migration steps.+-}+schemaItemPgCatalogExtension ::+  SchemaItem ->+  Maybe PgCatalog.ExtensionName+schemaItemPgCatalogExtension item =+  case item of+    SchemaTable _tableDef ->+      Nothing+    SchemaDropTable _tableId ->+      Nothing+    SchemaSequence _sequenceDef ->+      Nothing+    SchemaDropSequence _sequenceId ->+      Nothing+    SchemaFunction _functionDef ->+      Nothing+    SchemaDropFunction _functionId ->+      Nothing+    SchemaExtension extension ->+      Just $ extensionIdToPgCatalogName extension+    SchemaDropExtension extension ->+      Just $ extensionIdToPgCatalogName extension+ tableIdToPgCatalogNames ::   PgCatalog.NamespaceName ->   Orville.TableIdentifier ->@@ -1112,6 +1519,30 @@   in     (actualNamespace, relationName) +functionIdToPgCatalogNames ::+  PgCatalog.NamespaceName ->+  Orville.FunctionIdentifier ->+  (PgCatalog.NamespaceName, PgCatalog.ProcName)+functionIdToPgCatalogNames currentNamespace functionId =+  let+    actualNamespace =+      maybe currentNamespace String.fromString+        . Orville.functionIdSchemaNameString+        $ functionId++    relationName =+      String.fromString+        . Orville.functionIdUnqualifiedNameString+        $ functionId+  in+    (actualNamespace, relationName)++extensionIdToPgCatalogName ::+  Orville.ExtensionIdentifier ->+  PgCatalog.ExtensionName+extensionIdToPgCatalogName =+  String.fromString . Orville.extensionIdToString+ mkAlterSequenceSteps ::   Orville.SequenceDefinition ->   PgCatalog.PgSequence ->@@ -1192,7 +1623,7 @@             -- put it in quotes it tries to treat it as a regular column name,             -- which then can't be found as a column in the query.             (RawSql.unsafeSqlExpression "current_schema")-            (Orville.fieldColumnName PgCatalog.namespaceNameField)+            (Orville.fieldNameToColumnName $ Orville.fieldName PgCatalog.namespaceNameField)         ]     )     Nothing

@@ -17,8 +17,7 @@   ) where -{- |-  'ErrorDetailLevel' provides a means to configure what elements of information+{- | 'ErrorDetailLevel' provides a means to configure what elements of information   are included in error messages that originate from decoding rows queried   from the database. This can be specified either by manually rendering the   error message and providing the desired configuration, or by setting the@@ -40,8 +39,7 @@       Show     ) -{- |-  A minimal 'ErrorDetailLevel' where all information (including any+{- | A minimal 'ErrorDetailLevel' where all information (including any   situationally-specific error messages!) is redacted from error messages.  @since 1.0.0.0@@ -55,8 +53,7 @@     , includeNonIdentifierValues = False     } -{- |-  A default 'ErrorDetailLevel' that strikes a balance of including all "Generic"+{- | A default 'ErrorDetailLevel' that strikes a balance of including all "Generic"   information such as the error message, schema names and row identifiers, but   avoids unintentionally leaking non-identifier values from the database by   redacting them.@@ -72,8 +69,7 @@     , includeNonIdentifierValues = False     } -{- |-  A maximal 'ErrorDetailLevel' that redacts no information from the error+{- | A maximal 'ErrorDetailLevel' that redacts no information from the error   messages. Error messages will include values from the database for any   columns that are involved in a decoding failure, including some which you may   not have intended to expose through error messages. Use with caution.@@ -89,8 +85,7 @@     , includeNonIdentifierValues = True     } -{- |-  Redacts given the error message string if the 'ErrorDetailLevel' indicates+{- | Redacts given the error message string if the 'ErrorDetailLevel' indicates   that error messages should be redacted.  @since 1.0.0.0@@ -101,8 +96,7 @@     then message     else redactedValue -{- |-  Redacts given the schema name string if the 'ErrorDetailLevel' indicates+{- | Redacts given the schema name string if the 'ErrorDetailLevel' indicates   that schema names should be redacted.  @since 1.0.0.0@@ -113,8 +107,7 @@     then schemaName     else redactedValue -{- |-  Redacts given the identifier value string if the 'ErrorDetailLevel' indicates+{- | Redacts given the identifier value string if the 'ErrorDetailLevel' indicates   that identifier values should be redacted.  @since 1.0.0.0@@ -125,11 +118,10 @@     then idValue     else redactedValue -{- |-  Redacts given the non-identifier value string if the 'ErrorDetailLevel' indicates+{- | Redacts given the non-identifier value string if the 'ErrorDetailLevel' indicates   that non-identifier values should be redacted. -@since 1.0.0.0+  @since 1.0.0.0 -} redactNonIdentifierValue :: ErrorDetailLevel -> String -> String redactNonIdentifierValue detailLevel nonIdValue =

@@ -51,8 +51,7 @@ import Orville.PostgreSQL.Marshall (AnnotatedSqlMarshaller) import qualified Orville.PostgreSQL.Monad as Monad -{- |-  A 'Cursor' allows you to fetch rows incrementally from PostgreSQL. Using+{- | A 'Cursor' allows you to fetch rows incrementally from PostgreSQL. Using   a cursor will allow you to execute a query that returns a very large   result set without the entire result set being loaded in memory in your   application and instead pulling rows as you're able to process them.@@ -68,8 +67,7 @@     Expr.CursorName ->     Cursor readEntity -{- |-  Declares a @CURSOR@ in PostgreSQL that is available for the duration of the+{- | Declares a @CURSOR@ in PostgreSQL that is available for the duration of the   action passed to 'withCursor' and closes the cursor when that action   completes (or raises an exception). @@ -90,14 +88,12 @@   Select readEntity ->   (Cursor readEntity -> m a) ->   m a-withCursor scrollExpr holdExpr select useCursor =+withCursor scrollExpr holdExpr select =   Bracket.bracketWithResult     (declareCursor scrollExpr holdExpr select)     (\cursor _bracketResult -> closeCursor cursor)-    useCursor -{- |-  Declares a @CURSOR@ in PostgreSQL and returns it for you to use. The cursor+{- | Declares a @CURSOR@ in PostgreSQL and returns it for you to use. The cursor   must be closed via 'closeCursor' (or another means) when you are done using   it. Generally you should use 'withCursor' instead of 'declareCursor' to   ensure that the cursor gets closed properly.@@ -125,8 +121,7 @@     _ <- Execute.executeVoid QueryType.CursorQuery declareExpr     pure (Cursor marshaller cursorName) -{- |-  Closes a @CURSOR@ in PostgreSQL that was previously declared.+{- | Closes a @CURSOR@ in PostgreSQL that was previously declared.   This should be used to close any cursors you open via 'declareCursor',   though we recommend you use 'withCursor' instead to ensure that any   opened cursors are closed in the event of an exception.@@ -143,8 +138,7 @@     . Right     $ cursorName -{- |-  Fetch rows from a cursor according to the 'Expr.CursorDirection' given. See+{- | Fetch rows from a cursor according to the 'Expr.CursorDirection' given. See   @https://www.postgresql.org/docs/current/sql-fetch.html@ for details about   the effects of fetch and the meanings of cursor directions to PostgreSQL. @@ -161,8 +155,7 @@     (Expr.fetch direction cursorName)     marshaller -{- |-  Moves a cursor according to the 'Expr.CursorDirection' given. See+{- | Moves a cursor according to the 'Expr.CursorDirection' given. See   @https://www.postgresql.org/docs/current/sql-fetch.html@ for details about   the effect of move and the meanings of cursor directions to PostgreSQL. @@ -178,8 +171,7 @@     QueryType.CursorQuery     (Expr.move direction cursorName) -{- |-  INTERNAL - Generates a unique (or very nearly guaranteed to be) cursor name.+{- | INTERNAL - Generates a unique (or very nearly guaranteed to be) cursor name.   Cursor names only need to be unique among the currently-open cursors on the   current connection, so using POSIX time plus a 32-bit random tag should be   more than sufficient to ensure conflicts are not seen in practice.

@@ -35,8 +35,7 @@ import qualified Orville.PostgreSQL.Monad as Monad import Orville.PostgreSQL.Schema (TableDefinition, mkTableReturningClause, tableMarshaller, tableName) -{- |-Represents a @DELETE@ statement that can be executed against a database. A+{- | Represents a @DELETE@ statement that can be executed against a database. A 'Delete' has a 'Orville.PostgreSQL.SqlMarshaller' bound to it that, when the delete returns data from the database, will be used to decode the database result set when it is executed.@@ -49,8 +48,7 @@     Delete readEntity NoReturningClause   DeleteReturning :: AnnotatedSqlMarshaller writeEntity readEntity -> Expr.DeleteExpr -> Delete readEntity ReturningClause -{- |-  Extracts the query that will be run when the delete is executed. Normally you+{- | Extracts the query that will be run when the delete is executed. Normally you   don't want to extract the query and run it yourself, but this function is   useful to view the query for debugging or query explanation. @@ -60,8 +58,7 @@ deleteFromDeleteExpr (Delete expr) = expr deleteFromDeleteExpr (DeleteReturning _ expr) = expr -{- |-  Executes the database query for the 'Delete' and returns the number of+{- | Executes the database query for the 'Delete' and returns the number of   rows affected by the query.  @since 1.0.0.0@@ -73,8 +70,7 @@ executeDelete (Delete expr) =   Execute.executeAndReturnAffectedRows QueryType.DeleteQuery expr -{- |-Executes the database query for the 'Delete' and uses its+{- | Executes the database query for the 'Delete' and uses its 'Orville.PostgreSQL.SqlMarshaller' to decode the rows (that were just deleted) as returned via a RETURNING clause. @@ -87,8 +83,7 @@ executeDeleteReturnEntities (DeleteReturning marshaller expr) =   Execute.executeAndDecode QueryType.DeleteQuery expr marshaller -{- |-  Builds a 'Delete' that will delete all of the writable columns described in the+{- | Builds a 'Delete' that will delete all of the writable columns described in the   'TableDefinition' without returning the data as seen by the database.  @since 1.0.0.0@@ -100,8 +95,7 @@ deleteFromTable =   deleteTable WithoutReturning -{- |-  Builds a 'Delete' that will delete all of the writable columns described in the+{- | Builds a 'Delete' that will delete all of the writable columns described in the   'TableDefinition' and return the data as seen by the database. This is useful for getting   database-managed columns such as auto-incrementing identifiers and sequences. @@ -130,8 +124,7 @@   in     rawDeleteExpr returningOption (tableMarshaller tableDef) deleteExpr -{- |-  Builds a 'Delete' that will execute the specified query and use the given+{- | Builds a 'Delete' that will execute the specified query and use the given   'Orville.PostgreSQL.SqlMarshaller' to decode it. It is up to the caller to   ensure that the given 'Expr.DeleteExpr' makes sense and returns a result that   the 'Orville.PostgreSQL.SqlMarshaller' can decode.

@@ -51,8 +51,7 @@ import qualified Orville.PostgreSQL.Monad as Monad import qualified Orville.PostgreSQL.Schema as Schema -{- |-  Inserts an entity into the specified table.+{- | Inserts an entity into the specified table.  @since 1.0.0.0 -}@@ -64,8 +63,7 @@ insertEntity entityTable =   Monad.void . insertEntityAndReturnRowCount entityTable -{- |-  Inserts an entity into the specified table. Returns the number of rows+{- | Inserts an entity into the specified table. Returns the number of rows   affected by the query.  @since 1.0.0.0@@ -78,8 +76,7 @@ insertEntityAndReturnRowCount entityTable entity =   insertEntitiesAndReturnRowCount entityTable (entity :| []) -{- |-  Inserts an entity into the specified table, returning the data inserted into+{- | Inserts an entity into the specified table, returning the data inserted into   the database.    You can use this function to obtain any column values filled in by the@@ -99,8 +96,7 @@     "insertAndReturnEntity RETURNING clause"     returnedEntities -{- |-  Inserts a non-empty list of entities into the specified table.+{- | Inserts a non-empty list of entities into the specified table.  @since 1.0.0.0 -}@@ -112,8 +108,7 @@ insertEntities tableDef =   Monad.void . insertEntitiesAndReturnRowCount tableDef -{- |-  Inserts a non-empty list of entities into the specified table. Returns the+{- | Inserts a non-empty list of entities into the specified table. Returns the   number of rows affected by the query.  @since 1.0.0.0@@ -126,8 +121,7 @@ insertEntitiesAndReturnRowCount tableDef =   Insert.executeInsert . Insert.insertToTable tableDef -{- |-  Inserts a non-empty list of entities into the specified table, returning the data that+{- | Inserts a non-empty list of entities into the specified table, returning the data that   was inserted into the database.    You can use this function to obtain any column values filled in by the@@ -143,8 +137,7 @@ insertAndReturnEntities tableDef =   Insert.executeInsertReturnEntities . Insert.insertToTableReturning tableDef -{- |-  Updates the row with the given key with the data given by @writeEntity@.+{- | Updates the row with the given key with the data given by @writeEntity@.  @since 1.0.0.0 -}@@ -157,8 +150,7 @@ updateEntity tableDef key =   Monad.void . updateEntityAndReturnRowCount tableDef key -{- |-  Updates the row with the given key with the data given by @writeEntity@.+{- | Updates the row with the given key with the data given by @writeEntity@.   Returns the number of rows affected by the query.  @since 1.0.0.0@@ -176,8 +168,7 @@     Just update ->       Update.executeUpdate update -{- |-  Updates the row with the given key with the data given by @writeEntity@,+{- | Updates the row with the given key with the data given by @writeEntity@,   returning the updated row from the database. If no row matches the given key,   'Nothing' will be returned. @@ -202,8 +193,7 @@         "updateAndReturnEntity RETURNING clause"         returnedEntities -{- |-  Applies the given 'Expr.SetClause's to the rows in the table that match the+{- | Applies the given 'Expr.SetClause's to the rows in the table that match the   given where condition. The easiest way to construct a 'Expr.SetClause' is   via the 'Orville.Postgresql.setField' function (also exported as @.:=@). @@ -218,8 +208,7 @@ updateFields tableDef setClauses =   Monad.void . updateFieldsAndReturnRowCount tableDef setClauses -{- |-  Applies the given 'Expr.SetClause's to the rows in the table that match the+{- | Applies the given 'Expr.SetClause's to the rows in the table that match the   given where condition. The easiest way to construct a 'Expr.SetClause' is   via the 'Orville.Postgresql.setField' function (also exported as @.:=@).   Returns the number of rows affected by the query.@@ -236,8 +225,7 @@   Update.executeUpdate $     Update.updateToTableFields tableDef setClauses mbWhereCondition -{- |-  Like 'updateFields', but uses a @RETURNING@ clause to return the updated+{- | Like 'updateFields', but uses a @RETURNING@ clause to return the updated   version of any rows that were affected by the update.  @since 1.0.0.0@@ -252,8 +240,7 @@   Update.executeUpdateReturnEntities $     Update.updateToTableFieldsReturning tableDef setClauses mbWhereCondition -{- |-  Deletes the row with the given key.+{- | Deletes the row with the given key.  @since 1.0.0.0 -}@@ -265,8 +252,7 @@ deleteEntity entityTable =   Monad.void . deleteEntityAndReturnRowCount entityTable -{- |-  Deletes the row with the given key. Returns the number of rows affected+{- | Deletes the row with the given key. Returns the number of rows affected   by the query.  @since 1.0.0.0@@ -286,8 +272,7 @@     Delete.executeDelete $       Delete.deleteFromTable entityTable (Just primaryKeyCondition) -{- |-  Deletes the row with the given key, returning the row that was deleted.+{- | Deletes the row with the given key, returning the row that was deleted.   If no row matches the given key, 'Nothing' is returned.  @since 1.0.0.0@@ -310,8 +295,7 @@     "deleteAndReturnEntity RETURNING clause"     returnedEntities -{- |-  Deletes all rows in the given table that match the where condition.+{- | Deletes all rows in the given table that match the where condition.  @since 1.0.0.0 -}@@ -323,8 +307,7 @@ deleteEntities entityTable =   Monad.void . deleteEntitiesAndReturnRowCount entityTable -{- |-  Deletes all rows in the given table that match the where condition. Returns+{- | Deletes all rows in the given table that match the where condition. Returns   the number of rows affected by the query.  @since 1.0.0.0@@ -338,8 +321,7 @@   Delete.executeDelete $     Delete.deleteFromTable entityTable whereCondition -{- |-  Deletes all rows in the given table that match the where condition, returning+{- | Deletes all rows in the given table that match the where condition, returning   the rows that were deleted.  @since 1.0.0.0@@ -353,8 +335,7 @@   Delete.executeDeleteReturnEntities $     Delete.deleteFromTableReturning entityTable whereCondition -{- |-  Finds all the entities in the given table according to the specified+{- | Finds all the entities in the given table according to the specified   'SelectOptions.SelectOptions', which may include where conditions to   match, ordering specifications, etc. @@ -369,8 +350,7 @@   Select.executeSelect $     Select.selectTable entityTable selectOptions -{- |-  Like 'findEntitiesBy', but adds a 'LIMIT 1' to the query and then returns+{- | Like 'findEntitiesBy', but adds a 'LIMIT 1' to the query and then returns   the first item from the list. Usually when you use this you will want to   provide an order by clause in the 'SelectOptions.SelectOptions' because the   database will not guarantee ordering.@@ -386,8 +366,7 @@   listToMaybe     <$> findEntitiesBy entityTable (SelectOptions.limit 1 <> selectOptions) -{- |-  Finds a single entity by the table's primary key value.+{- | Finds a single entity by the table's primary key value.  @since 1.0.0.0 -}@@ -405,8 +384,7 @@   in     findFirstEntityBy entityTable (SelectOptions.where_ primaryKeyCondition) -{- |-  Finds multiple entities by the table's primary key.+{- | Finds multiple entities by the table's primary key.  @since 1.0.0.0 -}@@ -424,8 +402,7 @@   in     findEntitiesBy entityTable (SelectOptions.where_ primaryKeyCondition) -{- |-  Thrown by 'updateFields' and 'updateFieldsAndReturnEntities' if the+{- | Thrown by 'updateFields' and 'updateFieldsAndReturnEntities' if the   'Schema.TableDefinition' they are given has no columns to update.  @since 1.0.0.0

@@ -32,8 +32,7 @@ import qualified Orville.PostgreSQL.Raw.SqlCommenter as SqlCommenter import qualified Orville.PostgreSQL.Raw.SqlValue as SqlValue -{- |-  Executes a SQL query and decodes the result set using the provided+{- | Executes a SQL query and decodes the result set using the provided   marshaller. Any SQL Execution callbacks that have been added to the   'OrvilleState' will be called. @@ -52,8 +51,7 @@   orvilleState <- askOrvilleState   withConnection (liftIO . executeAndDecodeIO queryType sql marshaller orvilleState) -{- |-  Executes a SQL query and returns the number of rows affected by the query.+{- | Executes a SQL query and returns the number of rows affected by the query.   Any SQL Execution callbacks that have been added to the 'OrvilleState' will   be called. @@ -76,8 +74,7 @@   orvilleState <- askOrvilleState   withConnection (liftIO . executeAndReturnAffectedRowsIO queryType sql orvilleState) -{- |-  Executes a SQL query and ignores the result. Any SQL Execution callbacks+{- | Executes a SQL query and ignores the result. Any SQL Execution callbacks   that have been added to the 'OrvilleState' will be called.    If the query fails an exception will be raised.@@ -93,8 +90,7 @@   orvilleState <- askOrvilleState   withConnection (liftIO . executeVoidIO queryType sql orvilleState) -{- |-  Executes a SQL query and decodes the result set using the provided+{- | Executes a SQL query and decodes the result set using the provided   marshaller. Any SQL Execution callbacks that have been added to the   'OrvilleState' will be called. @@ -129,8 +125,7 @@     Right entities ->       pure entities -{- |-  Executes a SQL query and returns the number of rows affected by the query.+{- | Executes a SQL query and returns the number of rows affected by the query.   Any SQL Execution callbacks that have been added to the 'OrvilleState' will   be called. @@ -166,8 +161,7 @@         Right n ->           pure n -{- |-  Executes a SQL query and ignores the result. Any SQL Execution callbacks+{- | Executes a SQL query and ignores the result. Any SQL Execution callbacks   that have been added to the 'OrvilleState' will be called.    If the query fails, an exception will be raised.@@ -206,8 +200,7 @@       rawSql       (RawSql.execute conn rawSql) -{- |-  Thrown by 'executeAndReturnAffectedRows' and 'executeAndReturnAffectedRowsIO'+{- | Thrown by 'executeAndReturnAffectedRows' and 'executeAndReturnAffectedRowsIO'   if the number of affected rows cannot be successfully read from the LibPQ   command result. 

@@ -1,7 +1,7 @@ {-# LANGUAGE GeneralizedNewtypeDeriving #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -25,8 +25,7 @@ import Orville.PostgreSQL.Raw.SqlValue (SqlValue) import qualified Orville.PostgreSQL.Raw.SqlValue as SqlValue -{- |-  A trivial wrapper for `Int` to help keep track of column vs row number.+{- | A trivial wrapper for `Int` to help keep track of column vs row number.  @since 1.0.0.0 -}@@ -43,8 +42,7 @@       Num     ) -{- |-  A trivial wrapper for `Int` to help keep track of column vs row number.+{- | A trivial wrapper for `Int` to help keep track of column vs row number.  @since 1.0.0.0 -}@@ -61,8 +59,7 @@       Num     ) -{- |-  'ExecutionResult' is a common interface for types that represent a result set+{- | 'ExecutionResult' is a common interface for types that represent a result set   returned from the database. For real, live database interactions, the   concrete type will be a 'LibPQ.Result', but the 'FakeLibPQResult' may be   useful as well if you are writing custom code for decoding result sets and@@ -76,8 +73,7 @@   columnName :: result -> Column -> IO (Maybe BS.ByteString)   getValue :: result -> Row -> Column -> IO SqlValue -{- |-  Reads the rows of an 'ExecutionResult' as a list of column name, 'SqlValue'+{- | Reads the rows of an 'ExecutionResult' as a list of column name, 'SqlValue'   pairs. You're almost always better off using a   'Orville.PostgreSQL.SqlMarshaller' instead, but this function is provided for   cases where you really want to decode the rows yourself but don't want to use@@ -107,7 +103,7 @@     readValue rowIndex columnIndex = do       name <- columnName res columnIndex       value <- getValue res rowIndex columnIndex-      pure $ (name, value)+      pure (name, value)      readRow rowIndex =       traverse (readValue rowIndex) columnIndices@@ -140,8 +136,7 @@     SqlValue.fromRawBytesNullable       <$> LibPQ.getvalue' result (LibPQ.toRow row) (LibPQ.toColumn column) -{- |-  `FakeLibPQResult` provides a fake, in-memory implementation of+{- | `FakeLibPQResult` provides a fake, in-memory implementation of   `ExecutionResult`.  This is mostly useful for writing automated tests that   can assume a result set has been loaded and you just need to test decoding   the results.@@ -160,8 +155,7 @@   columnName result = pure . fakeLibPQColumnName result   getValue result column = pure . fakeLibPQGetValue result column -{- |-  Constructs a `FakeLibPQResult`. The column names given are associated with+{- | Constructs a `FakeLibPQResult`. The column names given are associated with   the values for each row by their position in-list. Any missing values (e.g.   because a row is shorter than the header list) are treated as a SQL Null   value.@@ -197,7 +191,7 @@ fakeLibPQMaxColumn result =   let     maxColumnsByRow =-      map fst+      fmap fst         . Maybe.mapMaybe Map.lookupMax         . Map.elems         . fakeLibPQRows@@ -209,7 +203,7 @@       _ ->         Just (maximum maxColumnsByRow) -fakeLibPQColumnName :: FakeLibPQResult -> Column -> (Maybe BS.ByteString)+fakeLibPQColumnName :: FakeLibPQResult -> Column -> Maybe BS.ByteString fakeLibPQColumnName result column =   Map.lookup column (fakeLibPQColumns result) 

@@ -38,8 +38,7 @@ import qualified Orville.PostgreSQL.Monad as Monad import Orville.PostgreSQL.Schema (TableDefinition, mkInsertExpr, tableMarshaller) -{- |-Represents an @INSERT@ statement that can be executed against a database. An+{- | Represents an @INSERT@ statement that can be executed against a database. An 'Insert' has a 'Orville.PostgreSQL.SqlMarshaller' bound to it that, when the insert returns data from the database, will be used to decode the database result set when it is executed.@@ -53,8 +52,7 @@     Insert readEntity NoReturningClause   InsertReturning :: AnnotatedSqlMarshaller writeEntity readEntity -> Expr.InsertExpr -> Insert readEntity ReturningClause -{- |-  Extracts the query that will be run when the insert is executed. Normally you+{- | Extracts the query that will be run when the insert is executed. Normally you   don't want to extract the query and run it yourself, but this function is   useful to view the query for debugging or query explanation. @@ -64,8 +62,7 @@ insertToInsertExpr (Insert _ expr) = expr insertToInsertExpr (InsertReturning _ expr) = expr -{- |-  Executes the database query for the 'Insert' and returns the number of rows+{- | Executes the database query for the 'Insert' and returns the number of rows   affected by the query.  @since 1.0.0.0@@ -77,8 +74,7 @@ executeInsert (Insert _ expr) =   Execute.executeAndReturnAffectedRows QueryType.InsertQuery expr -{- |-Executes the database query for the 'Insert' and uses its+{- | Executes the database query for the 'Insert' and uses its 'Orville.PostgreSQL.SqlMarshaller' to decode the rows (that were just inserted) as returned via a RETURNING clause. @@ -91,8 +87,7 @@ executeInsertReturnEntities (InsertReturning marshaller expr) =   Execute.executeAndDecode QueryType.InsertQuery expr marshaller -{- |-  Builds an 'Insert' that will insert all of the writable columns described in the+{- | Builds an 'Insert' that will insert all of the writable columns described in the   'TableDefinition' without returning the data as seen by the database.  @since 1.0.0.0@@ -104,8 +99,7 @@ insertToTable =   insertTable WithoutReturning -{- |-  Builds an 'Insert' that will insert all of the writable columns described in the+{- | Builds an 'Insert' that will insert all of the writable columns described in the   'TableDefinition' and return the data as seen by the database. This is useful for getting   database-managed columns such as auto-incrementing identifiers and sequences. @@ -125,10 +119,9 @@   NonEmpty writeEntity ->   Insert readEntity returningClause insertTable returningOption tableDef entities =-  rawInsertExpr returningOption (tableMarshaller tableDef) (mkInsertExpr returningOption tableDef entities)+  rawInsertExpr returningOption (tableMarshaller tableDef) (mkInsertExpr returningOption tableDef Nothing entities) -{- |-  Builds an 'Insert' that will execute the specified query and use the given+{- | Builds an 'Insert' that will execute the specified query and use the given   'Orville.PostgreSQL.SqlMarshaller' to decode it. It is up to the caller to   ensure that the given 'Expr.InsertExpr' makes sense and produces a value that   can be stored, as well as returning a result that the

@@ -10,8 +10,7 @@   ) where -{- |-  A simple categorization of SQL queries that is used to provide a hint to+{- | A simple categorization of SQL queries that is used to provide a hint to   user callbacks about what kind of query is being run.    See 'Orville.PostgreSQL.addSqlExecutionCallback'

@@ -26,10 +26,10 @@ -} data NoReturningClause -{- |-  Specifies whether or not a @RETURNING@ clause should be included when a+{- | Specifies whether or not a @RETURNING@ clause should be included when a   query expression is built. This type is found as a parameter on a number   of the query-building functions related to 'Orville.PostgreSQL.TableDefinition'.+ @since 1.0.0.0 -} data ReturningOption clause where

@@ -2,7 +2,7 @@ {-# LANGUAGE RankNTypes #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -35,8 +35,7 @@ import qualified Orville.PostgreSQL.Monad as Monad import Orville.PostgreSQL.Schema (TableDefinition, tableMarshaller, tableName) -{- |-  Represents a @SELECT@ statement that can be executed against a database. A+{- | Represents a @SELECT@ statement that can be executed against a database. A   'Select' has a 'Orville.PostgreSQL.SqlMarshaller' bound to it that will be   used to decode the database result set when it is executed. @@ -45,8 +44,7 @@ data Select readEntity where   Select :: AnnotatedSqlMarshaller writeEntity readEntity -> Expr.QueryExpr -> Select readEntity -{- |-  Extracts the query that will be run when the select is executed. Normally you+{- | Extracts the query that will be run when the select is executed. Normally you   don't want to extract the query and run it yourself, but this function is   useful to view the query for debugging or query explanation. @@ -55,8 +53,7 @@ selectToQueryExpr :: Select readEntity -> Expr.QueryExpr selectToQueryExpr (Select _ query) = query -{- |-  Executes the database query for the 'Select' and uses its+{- | Executes the database query for the 'Select' and uses its   'Orville.PostgreSQL.SqlMarshaller' to decode the result set.  @since 1.0.0.0@@ -65,8 +62,7 @@ executeSelect =   useSelect (Execute.executeAndDecode QueryType.SelectQuery) -{- |-  Runs a function allowing it to use the data elements containted within the+{- | Runs a function allowing it to use the data elements containted within the   'Select' it pleases. The marshaller that the function is provided can be use   to decode results from the query. @@ -83,8 +79,7 @@ useSelect f (Select marshaller query) =   f query marshaller -{- |-  Builds a 'Select' that will select all the columns described in the+{- | Builds a 'Select' that will select all the columns described in the   'TableDefinition'. This is the safest way to build a 'Select', because table   name and columns are all read from the 'TableDefinition'. If the table is   being managed with Orville auto-migrations, this will match the schema in the@@ -99,8 +94,7 @@ selectTable tableDef =   selectMarshalledColumns (tableMarshaller tableDef) (tableName tableDef) -{- |-  Builds a 'Select' that will select the columns described by the marshaller+{- | Builds a 'Select' that will select the columns described by the marshaller   from the specified table. It is up to the caller to ensure that the columns   in the marshaller make sense for the table. @@ -111,18 +105,17 @@ -} selectMarshalledColumns ::   AnnotatedSqlMarshaller writeEntity readEntity ->-  Expr.Qualified Expr.TableName ->+  Expr.QualifiedOrUnqualified Expr.TableName ->   SelectOptions.SelectOptions ->   Select readEntity selectMarshalledColumns marshaller qualifiedTableName selectOptions =   rawSelectQueryExpr marshaller $     SelectOptions.selectOptionsQueryExpr       (Expr.selectDerivedColumns (marshallerDerivedColumns . unannotatedSqlMarshaller $ marshaller))-      (Expr.referencesTable qualifiedTableName)+      (Expr.singleTableReferenceList qualifiedTableName)       selectOptions -{- |-  Builds a 'Select' that will execute the specified query and use the given+{- | Builds a 'Select' that will execute the specified query and use the given   'Orville.PostgreSQL.SqlMarshaller' to decode it. It is up to the caller to   ensure that the given 'Expr.QueryExpr' makes sense and produces a result set   that the 'Orville.PostgreSQL.SqlMarshaller' can decode.

@@ -1,5 +1,5 @@ {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -15,12 +15,18 @@   , selectGroupByClause   , selectLimitExpr   , selectOffsetExpr+  , selectRowLockingClause+  , selectWindowClause+  , selectFetchClause   , distinct   , where_   , orderBy   , limit   , offset   , groupBy+  , forRowLock+  , window+  , fetchRow   , selectOptionsQueryExpr   ) where@@ -29,8 +35,7 @@  import qualified Orville.PostgreSQL.Expr as Expr -{- |-   A 'SelectOptions' is a set of options that can be used to change the way+{- |  A 'SelectOptions' is a set of options that can be used to change the way    a basic query function works by adding @WHERE@, @ORDER BY@, @GROUP BY@, etc.    Functions are provided to construct 'SelectOptions' for individual options,    which may then be combined via '<>' (also exposed as 'appendSelectOptions').@@ -44,6 +49,9 @@   , i_limitExpr :: First Expr.LimitExpr   , i_offsetExpr :: First Expr.OffsetExpr   , i_groupByExpr :: Maybe Expr.GroupByExpr+  , i_rowLockingClause :: First Expr.RowLockingClause+  , i_windowExpr :: Maybe Expr.NamedWindowDefinitionExpr+  , i_fetchClause :: First Expr.FetchClause   }  -- | @since 1.0.0.0@@ -54,8 +62,7 @@ instance Monoid SelectOptions where   mempty = emptySelectOptions -{- |-  A set of empty 'SelectOptions' that will not change how a query is run.+{- | A set of empty 'SelectOptions' that will not change how a query is run.  @since 1.0.0.0 -}@@ -68,10 +75,12 @@     , i_limitExpr = mempty     , i_offsetExpr = mempty     , i_groupByExpr = mempty+    , i_rowLockingClause = mempty+    , i_windowExpr = Nothing+    , i_fetchClause = mempty     } -{- |-  Combines multple select options together, unioning the options together where+{- | Combines multple select options together, unioning the options together where   possible. For options where this is not possible (e.g. @LIMIT@), the one   on the left is preferred. @@ -86,6 +95,9 @@     (i_limitExpr left <> i_limitExpr right)     (i_offsetExpr left <> i_offsetExpr right)     (i_groupByExpr left <> i_groupByExpr right)+    (i_rowLockingClause left <> i_rowLockingClause right)+    (i_windowExpr left <> i_windowExpr right)+    (i_fetchClause left <> i_fetchClause right)  unionMaybeWith :: (a -> a -> a) -> Maybe a -> Maybe a -> Maybe a unionMaybeWith f mbLeft mbRight =@@ -95,8 +107,7 @@     (Nothing, Just right) -> Just right     (Just left, Just right) -> Just (f left right) -{- |-  Builds the 'Expr.SelectClause' that should be used to include the+{- | Builds the 'Expr.SelectClause' that should be used to include the   'distinct's from the 'SelectOptions' on a query.  @since 1.0.0.0@@ -107,8 +118,7 @@     First (Just True) -> Expr.selectClause . Expr.selectExpr $ Just Expr.Distinct     _ -> Expr.selectClause $ Expr.selectExpr Nothing -{- |-  Builds the 'Expr.WhereClause' that should be used to include the+{- | Builds the 'Expr.WhereClause' that should be used to include the   'Expr.BooleanExpr's from the 'SelectOptions' on a query. This will be 'Nothing'   when no 'Expr.BooleanExpr's have been specified. @@ -118,8 +128,7 @@ selectWhereClause =   fmap Expr.whereClause . i_whereCondition -{- |-  Constructs a 'SelectOptions' with just 'distinct' set to 'True'.+{- | Constructs a 'SelectOptions' with just 'distinct' set to 'True'.  @since 1.0.0.0 -}@@ -129,8 +138,7 @@     { i_distinct = First $ Just True     } -{- |-  Builds the 'Expr.OrderByClause' that should be used to include the+{- | Builds the 'Expr.OrderByClause' that should be used to include the   'Expr.OrderByClause's from the 'SelectOptions' on a query. This will be   'Nothing' when no 'Expr.OrderByClause's have been specified. @@ -140,8 +148,7 @@ selectOrderByClause =   fmap Expr.orderByClause . i_orderBy -{- |-  Builds the 'Expr.GroupByClause' that should be used to include the+{- | Builds the 'Expr.GroupByClause' that should be used to include the   'Expr.GroupByClause's from the 'SelectOptions' on a query. This will be   'Nothing' when no 'Expr.GroupByClause's have been specified. @@ -151,8 +158,7 @@ selectGroupByClause =   fmap Expr.groupByClause . i_groupByExpr -{- |-  Builds a 'Expr.LimitExpr' that will limit the query results to the+{- | Builds a 'Expr.LimitExpr' that will limit the query results to the   number specified in the 'SelectOptions' (if any).  @since 1.0.0.0@@ -161,8 +167,7 @@ selectLimitExpr =   getFirst . i_limitExpr -{- |-  Builds an 'Expr.OffsetExpr' that will limit the query results to the+{- | Builds an 'Expr.OffsetExpr' that will limit the query results to the   number specified in the 'SelectOptions' (if any).  @since 1.0.0.0@@ -171,9 +176,32 @@ selectOffsetExpr =   getFirst . i_offsetExpr -{- |-  Constructs a 'SelectOptions' with just the given 'Expr.BooleanExpr'.+{- | Builds an 'Expr.RowLockingClause' that will apply the locking rules specified in the 'SelectOptions' (if any). +@since 1.1.0.0+-}+selectRowLockingClause :: SelectOptions -> Maybe Expr.RowLockingClause+selectRowLockingClause =+  getFirst . i_rowLockingClause++{- | Builds an 'Expr.WindowClause' that will apply the windowing rules specified in the 'SelectOptions' (if any).++@since 1.1.0.0+-}+selectWindowClause :: SelectOptions -> Maybe Expr.WindowClause+selectWindowClause =+  fmap Expr.windowClause . i_windowExpr++{- | Builds an 'Expr.FetchClause' that will apply the fetching rules specified in the 'SelectOptions' (if any).++@since 1.1.0.0+-}+selectFetchClause :: SelectOptions -> Maybe Expr.FetchClause+selectFetchClause =+  getFirst . i_fetchClause++{- | Constructs a 'SelectOptions' with just the given 'Expr.BooleanExpr'.+ @since 1.0.0.0 -} where_ :: Expr.BooleanExpr -> SelectOptions@@ -182,8 +210,7 @@     { i_whereCondition = Just condition     } -{- |-  Constructs a 'SelectOptions' with just the given 'Expr.OrderByExpr'.+{- | Constructs a 'SelectOptions' with just the given 'Expr.OrderByExpr'.  @since 1.0.0.0 -}@@ -193,8 +220,7 @@     { i_orderBy = Just order     } -{- |-  Constructs a 'SelectOptions' that will apply the given limit.+{- | Constructs a 'SelectOptions' that will apply the given limit.  @since 1.0.0.0 -}@@ -204,8 +230,7 @@     { i_limitExpr = First . Just . Expr.limitExpr $ limitValue     } -{- |-  Constructs a 'SelectOptions' that will apply the given offset.+{- | Constructs a 'SelectOptions' that will apply the given offset.  @since 1.0.0.0 -}@@ -215,8 +240,7 @@     { i_offsetExpr = First . Just . Expr.offsetExpr $ offsetValue     } -{- |-  Constructs a 'SelectOptions' with just the given 'Expr.GroupByClause'.+{- | Constructs a 'SelectOptions' with just the given 'Expr.GroupByExpr'.  @since 1.0.0.0 -}@@ -226,8 +250,37 @@     { i_groupByExpr = Just groupByExpr     } -{- |-  Builds a 'Expr.QueryExpr' that will use the specified 'Expr.SelectList' when+{- | Constructs a 'SelectOptions' with just the given 'Expr.RowLockingClause'.++@since 1.1.0.0+-}+forRowLock :: Expr.RowLockingClause -> SelectOptions+forRowLock rowLockingClause =+  emptySelectOptions+    { i_rowLockingClause = First $ Just rowLockingClause+    }++{- | Constructs a 'SelectOptions' with just the given 'Expr.NamedWindowDefinitionExpr'.++@since 1.1.0.0+-}+window :: Expr.NamedWindowDefinitionExpr -> SelectOptions+window namedWindow =+  emptySelectOptions+    { i_windowExpr = Just namedWindow+    }++{- | Constructs a 'SelectOptions' with just the given 'Expr.FetchClause'.++@since 1.1.0.0+-}+fetchRow :: Expr.FetchClause -> SelectOptions+fetchRow fetchClause =+  emptySelectOptions+    { i_fetchClause = First $ Just fetchClause+    }++{- | Builds a 'Expr.QueryExpr' that will use the specified 'Expr.SelectList' when   building the @SELECT@ statement to execute. It is up to the caller to make   sure that the 'Expr.SelectList' expression makes sense for the table being   queried, and that the names of the columns in the result set match those@@ -260,4 +313,7 @@           (selectOrderByClause selectOptions)           (selectLimitExpr selectOptions)           (selectOffsetExpr selectOptions)+          (selectRowLockingClause selectOptions)+          (selectWindowClause selectOptions)+          (selectFetchClause selectOptions)     )

@@ -26,8 +26,7 @@ import qualified Orville.PostgreSQL.Monad as Monad import Orville.PostgreSQL.Schema (SequenceDefinition, sequenceName) -{- |-  Fetches the next value from a sequence via the PostgreSQL @nextval@ function.+{- | Fetches the next value from a sequence via the PostgreSQL @nextval@ function.  @since 1.0.0.0 -}@@ -37,8 +36,7 @@     "sequenceNextValue"     (Expr.nextVal (sequenceName sequenceDef)) -{- |-  Fetches the current value from a sequence via the PostgreSQL @currval@ function.+{- | Fetches the current value from a sequence via the PostgreSQL @currval@ function.  @since 1.0.0.0 -}@@ -48,8 +46,7 @@     "sequenceCurrentValue"     (Expr.currVal (sequenceName sequenceDef)) -{- |-  Sets the current value from a sequence via the PostgreSQL @setval@ function.+{- | Sets the current value from a sequence via the PostgreSQL @setval@ function.  @since 1.0.0.0 -}

@@ -1,5 +1,5 @@ {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -10,10 +10,18 @@ -} module Orville.PostgreSQL.Execution.Transaction   ( withTransaction+  , withTransactionInstruction+  , TransactionInstruction (Commit, Rollback)+  , inWithTransaction+  , InWithTransaction (InOutermostTransaction, InSavepointTransaction)+  , UnexpectedTransactionStatusError (..)   ) where -import Control.Monad.IO.Class (MonadIO, liftIO)+import Control.Exception (Exception, finally, onException, throwIO, try, uninterruptibleMask)+import Control.Monad.IO.Class (liftIO)+import qualified Database.PostgreSQL.LibPQ as LibPQ+import Numeric.Natural (Natural)  import qualified Orville.PostgreSQL.Execution.Execute as Execute import qualified Orville.PostgreSQL.Execution.QueryType as QueryType@@ -22,25 +30,57 @@ import qualified Orville.PostgreSQL.Internal.MonadOrville as MonadOrville import qualified Orville.PostgreSQL.Internal.OrvilleState as OrvilleState import qualified Orville.PostgreSQL.Monad as Monad+import qualified Orville.PostgreSQL.Raw.Connection as Connection import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-  Performs an action in an Orville monad within a database transaction. The transaction+{- | Performs an action in an Orville monad within a database transaction. The transaction   is begun before the action is called. If the action completes without raising an exception,   the transaction will be committed. If the action raises an exception, the transaction will-  rollback.+  rollback. This is equivalent to calling 'withTransactionInstruction' and always returning+  'Commit' as the 'TransactionInstruction'.    This function is safe to call from within another transaction. When called this way, the   transaction will establish a new savepoint at the beginning of the nested transaction and   either release the savepoint or rollback to it as appropriate. +  See also: 'withTransactionInstruction'+   Note: Exceptions are handled using the implementations of 'Monad.catch' and   'Monad.mask' provided by the 'Monad.MonadOrvilleControl' instance for @m@.  @since 1.0.0.0 -} withTransaction :: Monad.MonadOrville m => m a -> m a-withTransaction action =+withTransaction =+  withTransactionInstruction . fmap (\a -> (a, Commit))++{- |+Used with 'withTransactionInstruction' to indicate whether the transaction should be+committed or rolled back.++@since 1.1.0.0+-}+data TransactionInstruction = Commit | Rollback++{- | Performs an action in an Orville monad within a database transaction. The transaction+  is begun before the action is called. If the action completes without raising an exception,+  the transaction will be it will either be commited or rolled back, depending on the+  'TransactionInstruction' returned by the action.. If the action raises an exception, the+  transaction will rollback.++  This function is safe to call from within another transaction. When called this way, the+  transaction will establish a new savepoint at the beginning of the nested transaction and+  either release the savepoint or rollback to it as appropriate.++  See also: 'withTransaction'++  Note: Exceptions are handled using the implementations of 'Monad.catch' and+  'Monad.mask' provided by the 'Monad.MonadOrvilleControl' instance for @m@.++@since 1.1.0.0+-}+withTransactionInstruction :: Monad.MonadOrville m => m (a, TransactionInstruction) -> m a+withTransactionInstruction action =   MonadOrville.withConnectedState $ \connectedState -> do     let       conn = OrvilleState.connectedConnection connectedState@@ -61,35 +101,116 @@       callback =         OrvilleState.orvilleTransactionCallback state +      beginTransaction :: IO ()       beginTransaction = do-        liftIO $ do-          let-            openEvent = OrvilleState.openTransactionEvent transaction-          executeTransactionSql (transactionEventSql state openEvent)-          callback openEvent+        status <- Connection.transactionStatusOrThrow conn+        let+          openEvent = OrvilleState.openTransactionEvent transaction+          beginAction = do+            executeTransactionSql (transactionEventSql state openEvent)+            callback openEvent+          transactionError = UnexpectedTransactionStatusError status openEvent+        case status of+          LibPQ.TransIdle -> case openEvent of+            OrvilleState.BeginTransaction -> do+              let+                execRollback :: (IO () -> IO a) -> IO a+                execRollback restore = do+                  executeTransactionSql (transactionEventSql state OrvilleState.RollbackTransaction)+                  restore $ callback OrvilleState.RollbackTransaction+                rollback = uninterruptibleMask $ \restore -> do+                  postBeginStatus <- Connection.transactionStatusOrThrow conn+                  case postBeginStatus of+                    LibPQ.TransInTrans -> execRollback restore+                    LibPQ.TransInError -> execRollback restore+                    LibPQ.TransActive -> execRollback restore+                    LibPQ.TransIdle -> pure ()+                    LibPQ.TransUnknown -> pure ()+              beginAction `onException` rollback+            _ ->+              throwIO transactionError+          LibPQ.TransInTrans -> case openEvent of+            OrvilleState.NewSavepoint _ ->+              beginAction+            _ ->+              throwIO transactionError+          LibPQ.TransActive ->+            throwIO transactionError+          LibPQ.TransInError ->+            throwIO transactionError+          LibPQ.TransUnknown ->+            throwIO transactionError        doAction () =         Monad.localOrvilleState           (OrvilleState.connectState innerConnectedState)           action -      finishTransaction :: MonadIO m => () -> Bracket.BracketResult -> m ()-      finishTransaction () result =-        liftIO $-          case result of-            Bracket.BracketSuccess -> do-              let-                successEvent = OrvilleState.transactionSuccessEvent transaction-              executeTransactionSql (transactionEventSql state successEvent)-              callback successEvent-            Bracket.BracketError -> do-              let-                rollbackEvent = OrvilleState.rollbackTransactionEvent transaction-              executeTransactionSql (transactionEventSql state rollbackEvent)-              callback rollbackEvent+      finishTransaction :: Bracket.BracketResult (a, TransactionInstruction) -> IO ()+      finishTransaction result = uninterruptibleMask $ \restore -> do+        status <- Connection.transactionStatusOrThrow conn+        let+          successEvent = OrvilleState.transactionSuccessEvent transaction+          rollbackEvent = OrvilleState.rollbackTransactionEvent transaction+          rollback = do+            executeTransactionSql (transactionEventSql state rollbackEvent)+            restore $ callback rollbackEvent+          transactionError = UnexpectedTransactionStatusError status $ case result of+            Bracket.BracketSuccess (_, Commit) -> successEvent+            Bracket.BracketSuccess (_, Rollback) -> rollbackEvent+            Bracket.BracketError -> rollbackEvent+        case status of+          LibPQ.TransInTrans -> case result of+            Bracket.BracketSuccess (_, Commit) -> do+              eSuccess <- try $ executeTransactionSql (transactionEventSql state successEvent)+              case eSuccess of+                Right () ->+                  restore $ callback successEvent+                Left ex -> do+                  restore (callback rollbackEvent) `finally` throwIO (ex :: Connection.SqlExecutionError)+            Bracket.BracketSuccess (_, Rollback) -> do+              rollback+            Bracket.BracketError ->+              rollback+          LibPQ.TransInError ->+            rollback+          LibPQ.TransActive ->+            throwIO transactionError+          LibPQ.TransIdle ->+            throwIO transactionError+          LibPQ.TransUnknown ->+            throwIO transactionError -    Bracket.bracketWithResult beginTransaction finishTransaction doAction+    fmap fst $+      Bracket.bracketWithResult+        (liftIO beginTransaction)+        (const $ liftIO . finishTransaction)+        doAction +{- | 'withTransaction' will throw this exception if libpq reports a transaction status on the underlying+  connection that is incompatible with the current transaction event.++@since 1.1.0.0+-}+data UnexpectedTransactionStatusError = UnexpectedTransactionStatusError+  { unexpectedTransactionStatusErrorTransactionStatus :: LibPQ.TransactionStatus+  , unexpectedTransactionStatusErrorTransactionEvent :: OrvilleState.TransactionEvent+  }++{- |++@since 1.1.0.0+-}+instance Show UnexpectedTransactionStatusError where+  show (UnexpectedTransactionStatusError status event) =+    "Unexpected transaction status during event " <> show event <> ": " <> show status++{- |++@since 1.1.0.0+-}+instance Exception UnexpectedTransactionStatusError+ transactionEventSql ::   OrvilleState.OrvilleState ->   OrvilleState.TransactionEvent ->@@ -101,16 +222,15 @@     OrvilleState.NewSavepoint savepoint ->       RawSql.toRawSql $ Expr.savepoint (savepointName savepoint)     OrvilleState.RollbackTransaction ->-      RawSql.toRawSql $ Expr.rollback+      RawSql.toRawSql Expr.rollback     OrvilleState.RollbackToSavepoint savepoint ->       RawSql.toRawSql $ Expr.rollbackTo (savepointName savepoint)     OrvilleState.CommitTransaction ->-      RawSql.toRawSql $ Expr.commit+      RawSql.toRawSql Expr.commit     OrvilleState.ReleaseSavepoint savepoint ->       RawSql.toRawSql $ Expr.releaseSavepoint (savepointName savepoint) -{- |-  INTERNAL: Constructs a savepoint name based on the current nesting level of+{- | INTERNAL: Constructs a savepoint name based on the current nesting level of   transactions, as tracked by the `OrvilleState.Savepoint` type. Strictly   speaking this is not necessary for PostgreSQL because it supports shadowing   savepoint names. The SQL standard doesn't allow for savepoint name shadowing,@@ -127,3 +247,43 @@     n = OrvilleState.savepointNestingLevel savepoint   in     Expr.savepointName ("orville_savepoint_level_" <> show n)++{- | Information about the current transaction state of an action passed to 'withTransaction'.++@since 1.1.0.0+-}+data InWithTransaction+  = InOutermostTransaction+  | -- | The 'Natural' indicates the savepoint depth, where @1@ is the first savepoint.+    InSavepointTransaction Natural+  deriving+    ( -- | @since 1.1.0.0+      Eq+    , -- | @since 1.1.0.0+      Ord+    , -- | @since 1.1.0.0+      Show+    )++{- |  Returns 'Just' an 'InWithTransaction' value when called inside of the action passed to+  'withTransaction', and 'Nothing' otherwise.++@since 1.1.0.0+-}+inWithTransaction :: MonadOrville.MonadOrville m => m (Maybe InWithTransaction)+inWithTransaction =+  fmap+    ( \state -> case OrvilleState.orvilleConnectionState state of+        OrvilleState.Connected connectedState ->+          fmap+            ( \transactionState -> case transactionState of+                OrvilleState.OutermostTransaction ->+                  InOutermostTransaction+                OrvilleState.SavepointTransaction i ->+                  InSavepointTransaction . fromIntegral $ OrvilleState.savepointNestingLevel i+            )+            (OrvilleState.connectedTransaction connectedState)+        OrvilleState.NotConnected ->+          Nothing+    )+    Monad.askOrvilleState

@@ -39,8 +39,7 @@ import qualified Orville.PostgreSQL.Monad as Monad import Orville.PostgreSQL.Schema (HasKey, TableDefinition, mkTableReturningClause, primaryKeyEquals, tableMarshaller, tableName, tablePrimaryKey) -{- |-  Represents an @UPDATE@ statement that can be executed against a database. An+{- | Represents an @UPDATE@ statement that can be executed against a database. An   'Update' has a 'Orville.PostgreSQL.SqlMarshaller' bound to it that, when the   update returns data from the database, will be used to decode the database   result set when it is executed.@@ -51,8 +50,7 @@   UpdateNoReturning :: Expr.UpdateExpr -> Update readEntity NoReturningClause   UpdateReturning :: AnnotatedSqlMarshaller writeEntity readEntity -> Expr.UpdateExpr -> Update readEntity ReturningClause -{- |-  Extracts the query that will be run when the update is executed. Normally you+{- | Extracts the query that will be run when the update is executed. Normally you   don't want to extract the query and run it yourself, but this function is   useful to view the query for debugging or query explanation. @@ -62,8 +60,7 @@ updateToUpdateExpr (UpdateNoReturning expr) = expr updateToUpdateExpr (UpdateReturning _ expr) = expr -{- |-  Executes the database query for the 'Update' and returns the number of+{- | Executes the database query for the 'Update' and returns the number of   affected rows.  @since 1.0.0.0@@ -72,8 +69,7 @@ executeUpdate =   Execute.executeAndReturnAffectedRows QueryType.UpdateQuery . updateToUpdateExpr -{- |-  Executes the database query for the 'Update' and uses its+{- | Executes the database query for the 'Update' and uses its   'AnnotatedSqlMarshaller' to decode any rows that were just updated, as   returned via a RETURNING clause. @@ -83,8 +79,7 @@ executeUpdateReturnEntities (UpdateReturning marshaller expr) =   Execute.executeAndDecode QueryType.UpdateQuery expr marshaller -{- |-  Builds an 'Update' that will update all of the writable columns described in+{- | Builds an 'Update' that will update all of the writable columns described in   the 'TableDefinition' without returning the data as seen by the database.    This function returns 'Nothing' if the 'TableDefinition' has no columns,@@ -100,8 +95,7 @@ updateToTable =   updateTable WithoutReturning -{- |-  Builds an 'Update' that will update all of the writable columns described in+{- | Builds an 'Update' that will update all of the writable columns described in   the 'TableDefinition' and return the data as seen by the database. This is   useful for getting database-managed columns such as auto-incrementing   identifiers and sequences.@@ -119,8 +113,7 @@ updateToTableReturning =   updateTable WithReturning -{- |-  Builds an 'Update' that will apply the specified column set clauses to rows+{- | Builds an 'Update' that will apply the specified column set clauses to rows   within the specified table without returning the data as seen by the database.  @since 1.0.0.0@@ -133,8 +126,7 @@ updateToTableFields =   updateFields WithoutReturning -{- |-  Builds an 'Update' that will apply the specified column set clauses to rows+{- | Builds an 'Update' that will apply the specified column set clauses to rows   within the specified table and return the updated version of any rows affected by   the update state by using a @RETURNING@ clause. @@ -148,8 +140,7 @@ updateToTableFieldsReturning =   updateFields WithReturning -{- |-  Builds an 'Update' that will execute the specified query and use the given 'AnnotatedSqlMarshaller' to+{- | Builds an 'Update' that will execute the specified query and use the given 'AnnotatedSqlMarshaller' to   decode it. It is up to the caller to ensure that the given 'Expr.UpdateExpr' makes sense and   produces a value that can be stored, as well as returning a result that the 'AnnotatedSqlMarshaller' can   decode.@@ -208,6 +199,8 @@     rawUpdateExpr returingOption (tableMarshaller tableDef) $       Expr.updateExpr         (tableName tableDef)+        Nothing         (Expr.setClauseList setClauses)+        Nothing         whereClause         (mkTableReturningClause returingOption tableDef)

@@ -1,7 +1,7 @@ {-# OPTIONS_GHC -Wno-missing-import-lists #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -37,14 +37,19 @@ module Orville.PostgreSQL.Expr   ( module Orville.PostgreSQL.Expr.BinaryOperator   , module Orville.PostgreSQL.Expr.ColumnDefinition+  , module Orville.PostgreSQL.Expr.Comment   , module Orville.PostgreSQL.Expr.Count   , module Orville.PostgreSQL.Expr.Cursor   , module Orville.PostgreSQL.Expr.DataType   , module Orville.PostgreSQL.Expr.Delete   , module Orville.PostgreSQL.Expr.GroupBy+  , module Orville.PostgreSQL.Expr.TableReferenceList   , module Orville.PostgreSQL.Expr.IfExists+  , module Orville.PostgreSQL.Expr.IfNotExists   , module Orville.PostgreSQL.Expr.Index   , module Orville.PostgreSQL.Expr.Insert+  , module Orville.PostgreSQL.Expr.OnConflict+  , module Orville.PostgreSQL.Expr.Join   , module Orville.PostgreSQL.Expr.LimitExpr   , module Orville.PostgreSQL.Expr.Math   , module Orville.PostgreSQL.Expr.Name@@ -56,42 +61,71 @@   , module Orville.PostgreSQL.Expr.SequenceDefinition   , module Orville.PostgreSQL.Expr.TableConstraint   , module Orville.PostgreSQL.Expr.TableDefinition-  , module Orville.PostgreSQL.Expr.TableReferenceList   , module Orville.PostgreSQL.Expr.Time   , module Orville.PostgreSQL.Expr.Transaction   , module Orville.PostgreSQL.Expr.Update   , module Orville.PostgreSQL.Expr.ValueExpression   , module Orville.PostgreSQL.Expr.WhereClause+  , module Orville.PostgreSQL.Expr.Trigger+  , module Orville.PostgreSQL.Expr.Function+  , module Orville.PostgreSQL.Expr.OrReplace+  , module Orville.PostgreSQL.Expr.ConditionalExpr+  , module Orville.PostgreSQL.Expr.Window+  , module Orville.PostgreSQL.Expr.Vacuum+  , module Orville.PostgreSQL.Expr.Extension+  , module Orville.PostgreSQL.Expr.RowLocking+  , module Orville.PostgreSQL.Expr.Aggregate+  , module Orville.PostgreSQL.Expr.Filter+  , module Orville.PostgreSQL.Expr.FetchClause+  , module Orville.PostgreSQL.Expr.Values+  , module Orville.PostgreSQL.Expr.TextSearch   ) where  -- Note: we list the re-exports explicity above to control the order that they -- appear in the generated haddock documentation. +import Orville.PostgreSQL.Expr.Aggregate import Orville.PostgreSQL.Expr.BinaryOperator import Orville.PostgreSQL.Expr.ColumnDefinition+import Orville.PostgreSQL.Expr.Comment+import Orville.PostgreSQL.Expr.ConditionalExpr import Orville.PostgreSQL.Expr.Count import Orville.PostgreSQL.Expr.Cursor import Orville.PostgreSQL.Expr.DataType import Orville.PostgreSQL.Expr.Delete+import Orville.PostgreSQL.Expr.Extension+import Orville.PostgreSQL.Expr.FetchClause+import Orville.PostgreSQL.Expr.Filter+import Orville.PostgreSQL.Expr.Function import Orville.PostgreSQL.Expr.GroupBy import Orville.PostgreSQL.Expr.IfExists+import Orville.PostgreSQL.Expr.IfNotExists import Orville.PostgreSQL.Expr.Index import Orville.PostgreSQL.Expr.Insert+import Orville.PostgreSQL.Expr.Join import Orville.PostgreSQL.Expr.LimitExpr import Orville.PostgreSQL.Expr.Math import Orville.PostgreSQL.Expr.Name import Orville.PostgreSQL.Expr.OffsetExpr+import Orville.PostgreSQL.Expr.OnConflict+import Orville.PostgreSQL.Expr.OrReplace import Orville.PostgreSQL.Expr.OrderBy import Orville.PostgreSQL.Expr.Query import Orville.PostgreSQL.Expr.ReturningExpr+import Orville.PostgreSQL.Expr.RowLocking import Orville.PostgreSQL.Expr.Select import Orville.PostgreSQL.Expr.SequenceDefinition import Orville.PostgreSQL.Expr.TableConstraint import Orville.PostgreSQL.Expr.TableDefinition import Orville.PostgreSQL.Expr.TableReferenceList+import Orville.PostgreSQL.Expr.TextSearch import Orville.PostgreSQL.Expr.Time import Orville.PostgreSQL.Expr.Transaction+import Orville.PostgreSQL.Expr.Trigger import Orville.PostgreSQL.Expr.Update+import Orville.PostgreSQL.Expr.Vacuum import Orville.PostgreSQL.Expr.ValueExpression+import Orville.PostgreSQL.Expr.Values import Orville.PostgreSQL.Expr.WhereClause+import Orville.PostgreSQL.Expr.Window

@@ -0,0 +1,502 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024-2025+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Aggregate+  ( AggregateOptionExpr+  , aggregateExpression+  , aggregateStarExpression+  , aggregateWithinGroupExpression+  , arrayAggAggregateFunction+  , avgAggregateFunction+  , bitAndAggregateFunction+  , bitOrAggregateFunction+  , bitXorAggregateFunction+  , boolAndAggregateFunction+  , boolOrAggregateFunction+  , countExprAggregateFunction+  , count1AggregateFunction+  , countColumnAggregateFunction+  , countAggregateFunction+  , everyAggregateFunction+  , jsonAggAggregateFunction+  , jsonObjectAggAggregateFunction+  , jsonbAggAggregateFunction+  , jsonbObjectAggAggregateFunction+  , maxAggregateFunction+  , minAggregateFunction+  , stringAggAggregateFunction+  , sumAggregateFunction+  , corAggregateFunction+  , covarPopAggregateFunction+  , covarSampAggregateFunction+  , stddevPopAggregateFunction+  , stddevSampAggregateFunction+  , varPopAggregateFunction+  , varSampAggregateFunction+  )+where++import qualified Data.List.NonEmpty as NEL++import qualified Orville.PostgreSQL.Expr.Filter as Filter+import Orville.PostgreSQL.Expr.Name (FunctionName)+import qualified Orville.PostgreSQL.Expr.Name as Name+import qualified Orville.PostgreSQL.Expr.OrderBy as OrderBy+import qualified Orville.PostgreSQL.Expr.ValueExpression as ValueExpression+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | 'AggregateOptionExpr' represents the options to aggregate functions. E.G.++> ALL++or++> DISTINCT++'AggregateOptionExpr' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype AggregateOptionExpr = AggregateOptionExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Builds an aggregate expression. Note that it is up to the caller to ensure the validity of all of the arguments and that the resulting 'ValueExpression.ValueExpression' is used in an appropriate manner.++@since 1.1.0.0+-}+aggregateExpression :: FunctionName -> Maybe AggregateOptionExpr -> NEL.NonEmpty ValueExpression.ValueExpression -> Maybe OrderBy.OrderByClause -> Maybe Filter.FilterExpr -> ValueExpression.ValueExpression+aggregateExpression function mbAggOption parameters mbOrderByClause mbFilter =+  let+    fnCall =+      RawSql.toRawSql function+        <> RawSql.parenthesized+          ( ( case mbAggOption of+                Nothing -> mempty+                Just aggOption ->+                  RawSql.toRawSql aggOption+                    <> RawSql.space+            )+              <> RawSql.intercalate RawSql.comma parameters+              <> maybe mempty RawSql.toRawSql mbOrderByClause+          )++    filtering =+      case mbFilter of+        Nothing -> mempty+        Just filterExpr -> RawSql.space <> RawSql.toRawSql filterExpr+  in+    RawSql.unsafeFromRawSql $+      fnCall+        <> filtering++{- | Builds an aggregate expression with a * as the function argument. Note that it is up to the caller to ensure the validity of all of the arguments and that the resulting 'ValueExpression.ValueExpression' is used in an appropriate manner.++@since 1.1.0.0+-}+aggregateStarExpression :: FunctionName -> Maybe Filter.FilterExpr -> ValueExpression.ValueExpression+aggregateStarExpression function mbFilter =+  let+    parameters :: [ValueExpression.ValueExpression]+    parameters = pure . RawSql.unsafeFromRawSql $ RawSql.fromString "*"+    filtering =+      case mbFilter of+        Nothing -> mempty+        Just filterExpr -> RawSql.space <> RawSql.toRawSql filterExpr+  in+    RawSql.unsafeFromRawSql $+      RawSql.toRawSql (ValueExpression.functionCall function parameters)+        <> filtering++{- | Builds an orderd-set aggregate expression. These have the 'OrderBy.OrderByClause' as an argument to the aggregating function. Note that it is up to the caller to ensure the validity of all of the arguments and that the resulting 'ValueExpression.ValueExpression' is used in an appropriate manner.++@since 1.1.0.0+-}+aggregateWithinGroupExpression :: FunctionName -> [ValueExpression.ValueExpression] -> OrderBy.OrderByClause -> Maybe Filter.FilterExpr -> ValueExpression.ValueExpression+aggregateWithinGroupExpression function parameters orderByClause mbFilter =+  let+    within =+      RawSql.fromString " WITHIN GROUP "+        <> RawSql.parenthesized (RawSql.toRawSql orderByClause)+    filtering =+      case mbFilter of+        Nothing -> mempty+        Just filterExpr -> RawSql.space <> RawSql.toRawSql filterExpr+  in+    RawSql.unsafeFromRawSql $+      RawSql.toRawSql (ValueExpression.functionCall function parameters)+        <> within+        <> filtering++{- | The SQL @array_agg@ aggregate function.++@since 1.1.0.0+-}+arrayAggAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+arrayAggAggregateFunction =+  singleParameterAggregateFunction Name.arrayAggFunctionName++{- | The SQL @avg@ aggregate function.++@since 1.1.0.0+-}+avgAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+avgAggregateFunction =+  singleParameterAggregateFunction Name.avgFunctionName++{- | The SQL @bit_and@ aggregate function.++@since 1.1.0.0+-}+bitAndAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+bitAndAggregateFunction =+  singleParameterAggregateFunction Name.bitAndFunctionName++{- | The SQL @bit_or@ aggregate function.++@since 1.1.0.0+-}+bitOrAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+bitOrAggregateFunction =+  singleParameterAggregateFunction Name.bitOrFunctionName++{- | The SQL @bit_xor@ aggregate function.++@since 1.1.0.0+-}+bitXorAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+bitXorAggregateFunction =+  singleParameterAggregateFunction Name.bitXorFunctionName++{- | The SQL @bool_and@ aggregate function.++@since 1.1.0.0+-}+boolAndAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+boolAndAggregateFunction =+  singleParameterAggregateFunction Name.boolAndFunctionName++{- | The SQL @bool_or@ aggregate function.++@since 1.1.0.0+-}+boolOrAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+boolOrAggregateFunction =+  singleParameterAggregateFunction Name.boolOrFunctionName++{- | A simplified version of 'countAggregateFunction' for the SQL @count@ of a+   'ValueExpression.ValueExpression'++@since 1.1.0.0+-}+countExprAggregateFunction ::+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression+countExprAggregateFunction valExpr =+  singleParameterAggregateFunction Name.countFunctionName Nothing valExpr Nothing Nothing++{- | A simplified version of 'countAggregateFunction' for the SQL @count(1)@++@since 1.1.0.0+-}+count1AggregateFunction ::+  ValueExpression.ValueExpression+count1AggregateFunction =+  countExprAggregateFunction (RawSql.unsafeFromRawSql . RawSql.intDecLiteral $ 1)++{- | A simplified version of 'countAggregateFunction' for the SQL @count@ of a column++@since 1.1.0.0+-}+countColumnAggregateFunction ::+  Name.QualifiedOrUnqualified Name.ColumnName ->+  ValueExpression.ValueExpression+countColumnAggregateFunction =+  countExprAggregateFunction . ValueExpression.columnReference++{- | The SQL @count@ aggregate function.++@since 1.1.0.0+-}+countAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+countAggregateFunction =+  singleParameterAggregateFunction Name.countFunctionName++{- | The SQL @every@ aggregate function.++@since 1.1.0.0+-}+everyAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+everyAggregateFunction =+  singleParameterAggregateFunction Name.everyFunctionName++{- | The SQL @json_agg@ aggregate function.++@since 1.1.0.0+-}+jsonAggAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+jsonAggAggregateFunction =+  singleParameterAggregateFunction Name.jsonAggFunctionName++{- | The SQL @json_object_agg@ aggregate function.++@since 1.1.0.0+-}+jsonObjectAggAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+jsonObjectAggAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.jsonObjectAggFunctionName mbAggOption (param1 NEL.:| pure param2)++{- | The SQL @jsonb_agg@ aggregate function.++@since 1.1.0.0+-}+jsonbAggAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+jsonbAggAggregateFunction =+  singleParameterAggregateFunction Name.jsonbAggFunctionName++{- | The SQL @jsonb_object_agg@ aggregate function.++@since 1.1.0.0+-}+jsonbObjectAggAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+jsonbObjectAggAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.jsonbObjectAggFunctionName mbAggOption (param1 NEL.:| pure param2)++{- | The SQL @max@ aggregate function.++@since 1.1.0.0+-}+maxAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+maxAggregateFunction =+  singleParameterAggregateFunction Name.maxFunctionName++{- | The SQL @min@ aggregate function.++@since 1.1.0.0+-}+minAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+minAggregateFunction =+  singleParameterAggregateFunction Name.minFunctionName++{- | The SQL @string_agg@ aggregate function.++@since 1.1.0.0+-}+stringAggAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+stringAggAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.stringAggFunctionName mbAggOption (param1 NEL.:| pure param2)++{- | The SQL @sum@ aggregate function.++@since 1.1.0.0+-}+sumAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+sumAggregateFunction =+  singleParameterAggregateFunction Name.sumFunctionName++{- | The SQL @cor@ aggregate function.++@since 1.1.0.0+-}+corAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+corAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.corFunctionName mbAggOption (param1 NEL.:| pure param2)++{- | The SQL @covar_pop@ aggregate function.++@since 1.1.0.0+-}+covarPopAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+covarPopAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.covarPopFunctionName mbAggOption (param1 NEL.:| pure param2)++{- | The SQL @covar_samp@ aggregate function.++@since 1.1.0.0+-}+covarSampAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+covarSampAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.covarSampFunctionName mbAggOption (param1 NEL.:| pure param2)++{- | The SQL @stddev_pop@ aggregate function.++@since 1.1.0.0+-}+stddevPopAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+stddevPopAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.stddevPopFunctionName mbAggOption (param1 NEL.:| pure param2)++{- | The SQL @stddev_samp@ aggregate function.++@since 1.1.0.0+-}+stddevSampAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+stddevSampAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.stddevSampFunctionName mbAggOption (param1 NEL.:| pure param2)++{- | The SQL @var_pop@ aggregate function.++@since 1.1.0.0+-}+varPopAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+varPopAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.varPopFunctionName mbAggOption (param1 NEL.:| pure param2)++{- | The SQL @var_samp@ aggregate function.++@since 1.1.0.0+-}+varSampAggregateFunction ::+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+varSampAggregateFunction mbAggOption param1 param2 =+  aggregateExpression Name.varSampFunctionName mbAggOption (param1 NEL.:| pure param2)++-- internal helper to make building up the aggregates that only take a single parameter.+singleParameterAggregateFunction ::+  FunctionName ->+  Maybe AggregateOptionExpr ->+  ValueExpression.ValueExpression ->+  Maybe OrderBy.OrderByClause ->+  Maybe Filter.FilterExpr ->+  ValueExpression.ValueExpression+singleParameterAggregateFunction function mbAggOption parameter =+  aggregateExpression function mbAggOption (pure parameter)

@@ -15,6 +15,8 @@   , binaryOperator   , binaryOpExpression   , equalsOp+  , isDistinctFromOp+  , isNotDistinctFromOp   , notEqualsOp   , greaterThanOp   , lessThanOp@@ -41,8 +43,7 @@ import Orville.PostgreSQL.Expr.ValueExpression (ValueExpression) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent any SQL operator of two arguments. E.G.+{- | Type to represent any SQL operator of two arguments. E.G.  > AND @@ -85,6 +86,20 @@ notEqualsOp =   binaryOperator "<>" +{- | The SQL 'IS DISTINCT FROM' binary 'operator'.++@since 1.1.0.0+-}+isDistinctFromOp :: BinaryOperator+isDistinctFromOp = binaryOperator "IS DISTINCT FROM"++{- | The SQL 'IS NOT DISTINCT FROM' binary 'operator'.++@since 1.1.0.0+-}+isNotDistinctFromOp :: BinaryOperator+isNotDistinctFromOp = binaryOperator "IS NOT DISTINCT FROM"+ {- | The SQL strictly greater than binary operator.  @since 1.0.0.0@@ -253,8 +268,8 @@ binaryOpExpression op left right =   binaryOpExpressionUnparenthenizedArguments     op-    (RawSql.unsafeFromRawSql (RawSql.leftParen <> RawSql.toRawSql left <> RawSql.rightParen))-    (RawSql.unsafeFromRawSql (RawSql.leftParen <> RawSql.toRawSql right <> RawSql.rightParen))+    (RawSql.unsafeFromRawSql (RawSql.parenthesized left))+    (RawSql.unsafeFromRawSql (RawSql.parenthesized right))  -- internal helper function binaryOpExpressionUnparenthenizedArguments ::

@@ -1,7 +1,7 @@ {-# LANGUAGE GeneralizedNewtypeDeriving #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -15,18 +15,19 @@   , nullConstraint   , ColumnDefault   , columnDefault+  , identityColumnConstraint+  , ColumnIdentityGeneration+  , alwaysColumnIdentityGeneration+  , byDefaultColumnIdentityGeneration   ) where -import qualified Data.Maybe as Maybe- import Orville.PostgreSQL.Expr.DataType (DataType) import Orville.PostgreSQL.Expr.Name (ColumnName) import Orville.PostgreSQL.Expr.ValueExpression (ValueExpression) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Represent a complete definition of a column. E.G.+{- | Represent a complete definition of a column. E.G.  > foo INTEGER @@ -52,23 +53,28 @@   ColumnName ->   -- | The SQL type of the column.   DataType ->-  -- | The constraint on the column, if any.-  Maybe ColumnConstraint ->+  -- | The constraints on the column, if any.+  [ColumnConstraint] ->   -- | The default value for the column, if any.   Maybe ColumnDefault ->   ColumnDefinition-columnDefinition columnName dataType maybeColumnConstraint maybeColumnDefault =-  ColumnDefinition-    . RawSql.intercalate RawSql.space-    $ Maybe.catMaybes-      [ Just $ RawSql.toRawSql columnName-      , Just $ RawSql.toRawSql dataType-      , fmap RawSql.toRawSql maybeColumnConstraint-      , fmap RawSql.toRawSql maybeColumnDefault-      ]+columnDefinition columnName dataType columnConstraints maybeColumnDefault =+  let+    constraintRawSql =+      RawSql.intercalate RawSql.space columnConstraints+  in+    ColumnDefinition $+      RawSql.toRawSql columnName+        <> RawSql.space+        <> RawSql.toRawSql dataType+        <> RawSql.space+        <> constraintRawSql+        <> case maybeColumnDefault of+          Nothing -> mempty+          Just colDefault ->+            RawSql.space <> RawSql.toRawSql colDefault -{- |-Represent constraints, such as nullability, on a column. E.G.+{- | Represent constraints, such as nullability, on a column. E.G.  > NOT NULL @@ -101,8 +107,51 @@ nullConstraint =   ColumnConstraint (RawSql.fromString "NULL") -{- |-Represents the default value of a column. E.G.+{- | Represent the generation definition of an identity column. E.G.++> ALWAYS++'ColumnIdentityGeneration' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype ColumnIdentityGeneration+  = ColumnIdentityGeneration RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Express that a column is an identity column.++@since 1.1.0.0+-}+identityColumnConstraint ::+  ColumnIdentityGeneration ->+  ColumnConstraint+identityColumnConstraint identityGeneration =+  ColumnConstraint $+    RawSql.fromString "GENERATED "+      <> RawSql.toRawSql identityGeneration+      <> RawSql.fromString " AS IDENTITY"++{- | The @ALWAYS@ generation for an identity column++@since 1.1.0.0+-}+alwaysColumnIdentityGeneration :: ColumnIdentityGeneration+alwaysColumnIdentityGeneration = ColumnIdentityGeneration $ RawSql.fromString "ALWAYS"++{- | The @BY DEFAULT@ generation for an identity column++@since 1.1.0.0+-}+byDefaultColumnIdentityGeneration :: ColumnIdentityGeneration+byDefaultColumnIdentityGeneration = ColumnIdentityGeneration $ RawSql.fromString "BY DEFAULT"++{- | Represents the default value of a column. E.G.  > now() 

@@ -0,0 +1,79 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Comment+  ( Comment+  , commentText+  , CommentExpr+  , commentTableExpr+  , commentColumnExpr+  ) where++import qualified Data.Text as T+import qualified Data.Text.Encoding as TEnc++import Orville.PostgreSQL.Expr.Name (ColumnName, QualifiedOrUnqualified, SchemaName, TableName, qualifyColumn)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent a PostgreSQL comment string literal.++@since 1.1.0.0+-}+newtype Comment = Comment RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Construct a 'Comment' from a 'T.Text' value. The value will be escaped and quoted.++@since 1.1.0.0+-}+commentText :: T.Text -> Comment+commentText = Comment . RawSql.stringLiteral . TEnc.encodeUtf8++{- | Type to represent a PostgreSQL @COMMENT@ statement.++@since 1.1.0.0+-}+newtype CommentExpr = CommentExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Construct a 'CommentExpr' for a @COMMENT ON TABLE@ statement.++@since 1.1.0.0+-}+commentTableExpr :: QualifiedOrUnqualified TableName -> Maybe Comment -> CommentExpr+commentTableExpr tableName mbComment =+  CommentExpr $+    RawSql.intercalate+      RawSql.space+      [ RawSql.fromString "COMMENT ON TABLE"+      , RawSql.toRawSql tableName+      , RawSql.fromString "IS"+      , maybe RawSql.nullLiteral RawSql.toRawSql mbComment+      ]++{- | Construct a 'CommentExpr' for a @COMMENT ON COLUMN@ statement.++@since 1.1.0.0+-}+commentColumnExpr :: Maybe SchemaName -> TableName -> ColumnName -> Maybe Comment -> CommentExpr+commentColumnExpr mbSchema tableName colName mbComment =+  CommentExpr $+    RawSql.intercalate+      RawSql.space+      [ RawSql.fromString "COMMENT ON COLUMN"+      , RawSql.toRawSql $ qualifyColumn mbSchema tableName colName+      , RawSql.fromString "IS"+      , maybe RawSql.nullLiteral RawSql.toRawSql mbComment+      ]

@@ -0,0 +1,130 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.ConditionalExpr+  ( coalesce+  , WhenExpr+  , whenExpr+  , caseExpr+  , nullIf+  , greatest+  , least+  ) where++import qualified Data.List.NonEmpty as NE++import Orville.PostgreSQL.Expr.ValueExpression (ValueExpression)+import Orville.PostgreSQL.Expr.WhereClause (BooleanExpr)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Creates a 'ValueExpression' corresponding to the SQL @COALESE@.++@since 1.1.0.0+-}+coalesce :: NE.NonEmpty ValueExpression -> ValueExpression+coalesce valExprs =+  RawSql.unsafeFromRawSql $+    RawSql.fromString "COALESCE"+      <> RawSql.leftParen+      <> RawSql.intercalate RawSql.comma (fmap RawSql.toRawSql valExprs)+      <> RawSql.rightParen++{- | Type to represent the @WHEN@ portion of a SQL @CASE@ expressions.+E.G.++> WHEN condition THEN result++'WhenExpr' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype WhenExpr = WhenExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Builds a 'WhenExpr' that will apply when the given 'BooleanExpr' evaluates to @TRUE@, resulting in the 'ValueExpression'++@since 1.1.0.0+-}+whenExpr :: BooleanExpr -> ValueExpression -> WhenExpr+whenExpr boolExpr resultExpr =+  WhenExpr $+    RawSql.fromString "WHEN"+      <> RawSql.space+      <> RawSql.toRawSql boolExpr+      <> RawSql.space+      <> RawSql.fromString "THEN"+      <> RawSql.space+      <> RawSql.toRawSql resultExpr++{- | Builds a 'ValueExpression' corresponding to a SQL @CASE@ using the given 'WhenExpr' as the tested value with results and an optional 'ValueExpression' that corresponds to the @ELSE@ portion of the @CASE@.++@since 1.1.0.0+-}+caseExpr ::+  NE.NonEmpty WhenExpr ->+  Maybe ValueExpression ->+  ValueExpression+caseExpr whens mbElse =+  RawSql.unsafeFromRawSql $+    RawSql.fromString "CASE"+      <> RawSql.space+      <> RawSql.intercalate RawSql.space (fmap RawSql.toRawSql whens)+      <> RawSql.space+      <> case mbElse of+        Nothing ->+          RawSql.fromString "END"+        Just elseVal ->+          RawSql.fromString "ELSE"+            <> RawSql.space+            <> RawSql.toRawSql elseVal+            <> RawSql.space+            <> RawSql.fromString "END"++{- | Creates a 'ValueExpression' corresponding to the SQL @NULLIF@.++@since 1.1.0.0+-}+nullIf :: ValueExpression -> ValueExpression -> ValueExpression+nullIf leftVal rightVal =+  RawSql.unsafeFromRawSql $+    RawSql.fromString "NULLIF"+      <> RawSql.leftParen+      <> RawSql.toRawSql leftVal+      <> RawSql.commaSpace+      <> RawSql.toRawSql rightVal+      <> RawSql.rightParen++{- | Creates a 'ValueExpression' corresponding to the SQL @GREATEST@.++@since 1.1.0.0+-}+greatest :: NE.NonEmpty ValueExpression -> ValueExpression+greatest valExprs =+  RawSql.unsafeFromRawSql $+    RawSql.fromString "GREATEST"+      <> RawSql.leftParen+      <> RawSql.intercalate RawSql.comma (fmap RawSql.toRawSql valExprs)+      <> RawSql.rightParen++{- | Creates a 'ValueExpression' corresponding to the SQL @LEAST@.++@since 1.1.0.0+-}+least :: NE.NonEmpty ValueExpression -> ValueExpression+least valExprs =+  RawSql.unsafeFromRawSql $+    RawSql.fromString "LEAST"+      <> RawSql.leftParen+      <> RawSql.intercalate RawSql.comma (fmap RawSql.toRawSql valExprs)+      <> RawSql.rightParen

@@ -1,5 +1,5 @@ {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2024 License   : MIT Stability : Stable @@ -13,10 +13,12 @@   ) where -import Orville.PostgreSQL.Expr.Name (ColumnName, FunctionName, functionName)+import Orville.PostgreSQL.Expr.Name (ColumnName, FunctionName, QualifiedOrUnqualified, functionName) import Orville.PostgreSQL.Expr.ValueExpression (ValueExpression, columnReference, functionCall) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql +{-# DEPRECATED countFunction "Use Orville.PostgreSQL.Expr.countFunctionName" #-}+ {- | The SQL @count@ function.  @since 1.0.0.0@@ -24,6 +26,8 @@ countFunction :: FunctionName countFunction = functionName "count" +{-# DEPRECATED count "Use Orville.PostgreSQL.Expr.countExprAggregateFunction" #-}+ {- | Given a 'ValueExpression', use it as the argument to the SQL @count@.  @since 1.0.0.0@@ -32,6 +36,8 @@ count value =   functionCall countFunction [value] +{-# DEPRECATED count1 "Use Orville.PostgreSQL.Expr.count1AggregateFunction" #-}+ {- | The SQL @count(1)@.  @since 1.0.0.0@@ -40,10 +46,12 @@ count1 =   count . RawSql.unsafeFromRawSql . RawSql.intDecLiteral $ 1 +{-# DEPRECATED countColumn "Use Orville.PostgreSQL.Expr.countColumnAggregateFunction" #-}+ {- | Use a given column as the argument to the SQL @count@.  @since 1.0.0.0 -}-countColumn :: ColumnName -> ValueExpression+countColumn :: QualifiedOrUnqualified ColumnName -> ValueExpression countColumn =   count . columnReference

@@ -49,8 +49,7 @@ import Orville.PostgreSQL.Expr.Query (QueryExpr) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-'DeclareExpr' corresponds to the SQL DECLARE statement, for declaring and+{- | 'DeclareExpr' corresponds to the SQL DECLARE statement, for declaring and opening cursors. E.G.  > DECLARE FOO CURSOR FOR SELECT * FROM BAR@@ -84,20 +83,19 @@   QueryExpr ->   DeclareExpr declare cursorName maybeScrollExpr maybeHoldExpr queryExpr =-  DeclareExpr $-    RawSql.intercalate RawSql.space $-      catMaybes-        [ Just $ RawSql.fromString "DECLARE"-        , Just $ RawSql.toRawSql cursorName-        , fmap RawSql.toRawSql maybeScrollExpr-        , Just $ RawSql.fromString "CURSOR"-        , fmap RawSql.toRawSql maybeHoldExpr-        , Just $ RawSql.fromString "FOR"-        , Just $ RawSql.toRawSql queryExpr-        ]+  DeclareExpr+    . RawSql.intercalate RawSql.space+    $ catMaybes+      [ Just $ RawSql.fromString "DECLARE"+      , Just $ RawSql.toRawSql cursorName+      , fmap RawSql.toRawSql maybeScrollExpr+      , Just $ RawSql.fromString "CURSOR"+      , fmap RawSql.toRawSql maybeHoldExpr+      , Just $ RawSql.fromString "FOR"+      , Just $ RawSql.toRawSql queryExpr+      ] -{- |-'ScrollExpr' is used to determine if a cursor should be able to fetch+{- | 'ScrollExpr' is used to determine if a cursor should be able to fetch nonsequentially. E.G.  > NO SCROLL@@ -137,8 +135,7 @@ noScroll =   ScrollExpr . RawSql.fromString $ "NO SCROLL" -{- |-'HoldExpr' is used to determine if a cursor should be available for use after+{- | 'HoldExpr' is used to determine if a cursor should be available for use after the transaction that created it has been committed. E.G.  > WITH HOLD@@ -175,8 +172,7 @@ withoutHold =   HoldExpr . RawSql.fromString $ "WITHOUT HOLD" -{- |-'CloseExpr' corresponds to the SQL CLOSE statement. E.G.+{- | 'CloseExpr' corresponds to the SQL CLOSE statement. E.G.  > CLOSE ALL @@ -207,8 +203,7 @@     RawSql.fromString "CLOSE "       <> either RawSql.toRawSql RawSql.toRawSql allOrCursorName -{- |-'AllCursors' corresponds to the ALL keyword in a CLOSE statement. E.G.+{- | 'AllCursors' corresponds to the ALL keyword in a CLOSE statement. E.G.  > ALL @@ -233,8 +228,7 @@ allCursors =   AllCursors . RawSql.fromString $ "ALL" -{- |-'FetchExpr' corresponds to the SQL FETCH statement, for retrieving rows from a+{- | 'FetchExpr' corresponds to the SQL FETCH statement, for retrieving rows from a previously-created cursor. E.G.  > FETCH NEXT FOO@@ -262,16 +256,15 @@ -} fetch :: Maybe CursorDirection -> CursorName -> FetchExpr fetch maybeDirection cursorName =-  FetchExpr $-    RawSql.intercalate RawSql.space $-      catMaybes-        [ Just $ RawSql.fromString "FETCH"-        , fmap RawSql.toRawSql maybeDirection-        , Just $ RawSql.toRawSql cursorName-        ]+  FetchExpr+    . RawSql.intercalate RawSql.space+    $ catMaybes+      [ Just $ RawSql.fromString "FETCH"+      , fmap RawSql.toRawSql maybeDirection+      , Just $ RawSql.toRawSql cursorName+      ] -{- |-'MoveExpr' corresponds to the SQL MOVE statement, for positioning a previously+{- | 'MoveExpr' corresponds to the SQL MOVE statement, for positioning a previously created cursor, /without/ retrieving any rows. E.G.  > MOVE NEXT FOO@@ -303,8 +296,7 @@       , Just $ RawSql.toRawSql cursorName       ] -{- |-'CursorDirection' corresponds to the direction argument to the SQL FETCH and+{- | 'CursorDirection' corresponds to the direction argument to the SQL FETCH and MOVE statements. E.G.  > BACKWARD

@@ -33,8 +33,7 @@  import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent any SQL data type expression. E.G.+{- | Type to represent any SQL data type expression. E.G.    > INTEGER @@ -237,8 +236,7 @@ smallint =   DataType (RawSql.fromString "SMALLINT") -{- |-  A 'DataType' that represents the PostgreSQL "JSONB" data type.+{- | A 'DataType' that represents the PostgreSQL "JSONB" data type.  See [postgresql documentation](https://www.postgresql.org/docs/current/datatype-json.html) for more information.

@@ -17,13 +17,12 @@  import Data.Maybe (catMaybes) -import Orville.PostgreSQL.Expr.Name (Qualified, TableName)+import Orville.PostgreSQL.Expr.Name (QualifiedOrUnqualified, TableName) import Orville.PostgreSQL.Expr.ReturningExpr (ReturningExpr) import Orville.PostgreSQL.Expr.WhereClause (WhereClause) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL delete statement. E.G.+{- | Type to represent a SQL delete statement. E.G.  > DELETE FROM foo WHERE id < 10 @@ -40,24 +39,22 @@       RawSql.SqlExpression     ) -{- |--Construct a SQL DELETE from a table, optionally limiting with a 'WhereClause' and optionally+{- | Construct a SQL DELETE from a table, optionally limiting with a 'WhereClause' and optionally returning a 'ReturningExpr'.  @since 1.0.0.0 -} deleteExpr ::-  Qualified TableName ->+  QualifiedOrUnqualified TableName ->   Maybe WhereClause ->   Maybe ReturningExpr ->   DeleteExpr deleteExpr tableName maybeWhereClause maybeReturningExpr =-  DeleteExpr $-    RawSql.intercalate RawSql.space $-      catMaybes-        [ Just $ RawSql.fromString "DELETE FROM"-        , Just $ RawSql.toRawSql tableName-        , fmap RawSql.toRawSql maybeWhereClause-        , fmap RawSql.toRawSql maybeReturningExpr-        ]+  DeleteExpr+    . RawSql.intercalate RawSql.space+    $ catMaybes+      [ Just $ RawSql.fromString "DELETE FROM"+      , Just $ RawSql.toRawSql tableName+      , fmap RawSql.toRawSql maybeWhereClause+      , fmap RawSql.toRawSql maybeReturningExpr+      ]

@@ -0,0 +1,116 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++Types and functionality related to loading PostgreSQL extensions. This does not contain features+related to any specific extension, but serves as the basis for loading some extension.++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Extension+  ( CreateExtensionExpr+  , createExtensionExpr+  , DropExtensionExpr+  , dropExtensionExpr+  , ExtensionActionExpr+  , extensionCascadeExpr+  , extensionRestrictExpr+  ) where++import Orville.PostgreSQL.Expr.IfExists (IfExists)+import Orville.PostgreSQL.Expr.IfNotExists (IfNotExists)+import Orville.PostgreSQL.Expr.Name (ExtensionName)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent a SQL "CREATE EXTENSION" statement. E.G.++> CREATE EXTENSION foo++'CreateIndexExpr' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype CreateExtensionExpr = CreateExtensionExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Construct a SQL CREATE EXTENSION statement from the extension name and if the statement should+not fail on loading an extension with the same name as an already loaded one.++@since 1.1.0.0+-}+createExtensionExpr :: ExtensionName -> Maybe IfNotExists -> Maybe ExtensionActionExpr -> CreateExtensionExpr+createExtensionExpr extension mbIfNotExists mbAction =+  CreateExtensionExpr $+    RawSql.fromString "CREATE EXTENSION "+      <> maybe mempty ((<> RawSql.space) . RawSql.toRawSql) mbIfNotExists+      <> RawSql.toRawSql extension+      <> maybe mempty ((<> RawSql.space) . RawSql.toRawSql) mbAction++{- | Type to represent a SQL "DROP EXTENSION" statement. E.G.++> DROP EXTENSION foo++'DropIndexExpr' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype DropExtensionExpr = DropExtensionExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Construct a SQL DROP EXTENSION statement from the extension name and if the statement should+not fail on loading an extension with the same name as an already loaded one.++@since 1.1.0.0+-}+dropExtensionExpr :: ExtensionName -> Maybe IfExists -> Maybe ExtensionActionExpr -> DropExtensionExpr+dropExtensionExpr extension mbIfExists mbAction =+  DropExtensionExpr $+    RawSql.fromString "DROP EXTENSION "+      <> maybe mempty ((<> RawSql.space) . RawSql.toRawSql) mbIfExists+      <> RawSql.toRawSql extension+      <> maybe mempty ((<> RawSql.space) . RawSql.toRawSql) mbAction++{- | Type to represent a extension action on a @EXTENSION@. E.G.+the @CASCADE@ in++> CREATE EXTENSION foo CASCADE++'ExtensionActionExpr' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype ExtensionActionExpr+  = ExtensionActionExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | The extension action @RESTRICT@.++  @since 1.1.0.0+-}+extensionRestrictExpr :: ExtensionActionExpr+extensionRestrictExpr = ExtensionActionExpr $ RawSql.fromString "RESTRICT"++{- | The extension action @CASCADE@.++  @since 1.1.0.0+-}+extensionCascadeExpr :: ExtensionActionExpr+extensionCascadeExpr = ExtensionActionExpr $ RawSql.fromString "CASCADE"

@@ -0,0 +1,100 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.FetchClause+  ( FetchClause+  , fetchClauseInt+  , FetchClauseModifier+  , withTiesFetchClauseModifier+  , onlyFetchClauseModifier+  )+where++import qualified Orville.PostgreSQL.Raw.RawSql as RawSql+import qualified Orville.PostgreSQL.Raw.SqlValue as SqlValue++{- | Type to represent a SQL FETCH clause. E.G.++> FETCH FIRST 2 ROWS ONLY++'FetchClause' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype FetchClause+  = FetchClause RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Build a SQL FETCH clause for a given number of rows and 'FetchClauseModifier'.++@since 1.1.0.0+-}+fetchClauseInt :: Int -> FetchClauseModifier -> FetchClause+fetchClauseInt fetchNumber =+  internal_fetchRaw (RawSql.parameter (SqlValue.fromInt fetchNumber))++-- Internal helper for FETCH. Note this allows illegal expressions to be put together. However many+-- potentially interesting expressions are valid. Such as:+--+-- `VALUES (1, 'o'), (2, 't'), (3, 'th') order by column2 fetch first (select 2) ROW with ties;`+--+-- How to best expose these is not clear at this moment as we do not generally allow any raw sql to+-- be injected, but we do not have a good expression to capture the allowed values here. Finally, it+-- would _appear_ that the same restrictions here would also apply to expressions allowed for+-- LIMIT. Which as of this writing, we do not have a helper for creation.+--+-- Finally note that NEXT and ROW are as PostgreSQL docs call them, noise words, they do not impact+-- the meaning. See https://www.postgresql.org/docs/13/sql-select.html. 'NEXT' and 'ROW' are chosen+-- over 'FIRST' and 'ROWS' respecitvely because they are shorter and thus result in a smaller+-- bytestring being sent over the wire.+internal_fetchRaw :: RawSql.RawSql -> FetchClauseModifier -> FetchClause+internal_fetchRaw countingRawSql modifier =+  FetchClause $+    RawSql.fromString "FETCH NEXT "+      <> RawSql.parenthesized countingRawSql+      <> RawSql.fromString " ROW "+      <> RawSql.toRawSql modifier++{- | Type to represent the treatment of ties in a SQL FETCH expression. E.G.++> WITH TIES++'FetchClauseModifier' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype FetchClauseModifier+  = FetchClauseModifier RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Allow a FETCH clause to have ties.++@since 1.1.0.0+-}+withTiesFetchClauseModifier :: FetchClauseModifier+withTiesFetchClauseModifier =+  FetchClauseModifier (RawSql.fromString "WITH TIES")++{- | Disallow a FETCH clause to have ties.++@since 1.1.0.0+-}+onlyFetchClauseModifier :: FetchClauseModifier+onlyFetchClauseModifier =+  FetchClauseModifier (RawSql.fromString "ONLY")

@@ -0,0 +1,43 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Filter+  ( FilterExpr+  , filterExpr+  ) where++import qualified Orville.PostgreSQL.Expr.WhereClause as WhereClause+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | 'FilterExpr' represents the @FILTER@ subexpression E.G.++> FILTER (WHERE some_boolean_expr)+++'FilterExpr' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype FilterExpr = FilterExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Builds a 'FilterExpr' with the given 'WhereClause.WhereClause'++@since 1.1.0.0+-}+filterExpr :: WhereClause.WhereClause -> FilterExpr+filterExpr whereClause =+  FilterExpr $+    RawSql.fromString "FILTER"+      <> RawSql.parenthesized (RawSql.toRawSql whereClause)

@@ -0,0 +1,247 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Function+  ( DropFunctionExpr+  , dropFunction+  , CreateFunctionExpr+  , createFunction+  , FunctionReturns+  , returns+  , ReturnType+  , returnTypeTrigger+  , FunctionLanguage+  , language+  , LanguageName+  , plpgsql+  , FunctionDefinition+  , asDefinition+  ) where++import qualified Data.ByteString.Char8 as BS8+import Data.Maybe (catMaybes)++import Orville.PostgreSQL.Expr.IfExists (IfExists)+import Orville.PostgreSQL.Expr.Name (FunctionName, QualifiedOrUnqualified)+import Orville.PostgreSQL.Expr.OrReplace (OrReplace)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent a SQL "DROP FUNCTION" statement. E.G.++> DROP FUNCTION my_function++'DropFunctionExpr' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype DropFunctionExpr+  = DropFunctionExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Constructs a SQL @DROP FUNCTION@ statement from a function name.++@since 1.1.0.0+-}+dropFunction :: Maybe IfExists -> QualifiedOrUnqualified FunctionName -> DropFunctionExpr+dropFunction maybeIfExists name =+  DropFunctionExpr $+    RawSql.intercalate+      RawSql.space+      ( catMaybes+          [ Just (RawSql.fromString "DROP FUNCTION")+          , fmap RawSql.toRawSql maybeIfExists+          , Just (RawSql.toRawSql name)+          ]+      )++{- | Type to represent a SQL "CREATE FUNCTION" statement. E.G.++> CREATE FUNCTION my_function RETURNS trigger AS '<definition>'++'CreateFunctionExpr' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype CreateFunctionExpr+  = CreateFunctionExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Constructs a SQL @CREATE FUNCTION@ statement from a function name, return type,+language and definiton.++Note: Orville does not currently support creating functions with arguments.++@since 1.1.0.0+-}+createFunction ::+  Maybe OrReplace ->+  QualifiedOrUnqualified FunctionName ->+  FunctionReturns ->+  FunctionLanguage ->+  FunctionDefinition ->+  CreateFunctionExpr+createFunction maybeOrReplace name functionReturns functionLanguage definition =+  CreateFunctionExpr $+    RawSql.intercalate+      RawSql.space+      ( catMaybes+          [ Just $ RawSql.fromString "CREATE"+          , fmap RawSql.toRawSql maybeOrReplace+          , Just $ RawSql.fromString "FUNCTION"+          , Just $ RawSql.toRawSql name+          , Just $ RawSql.fromString "()" -- currently we don't support specifying arguments+          , Just $ RawSql.toRawSql functionReturns+          , Just $ RawSql.toRawSql functionLanguage+          , Just $ RawSql.toRawSql definition+          ]+      )++{- | Type to represent the return specifier given as part of a SQL "CREATE+FUNCTION" statement. E.G. the @RETURNS trigger@ in++> CREATE FUNCTION my_function RETURNS trigger++'FunctionReturns' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype FunctionReturns+  = FunctionReturns RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Constructs a @RETURNS@ specifier for a @CREATE FUNCTION@ statement with the+  given return type.++@since 1.1.0.0+-}+returns :: ReturnType -> FunctionReturns+returns returnType =+  FunctionReturns $ RawSql.fromString "RETURNS " <> RawSql.toRawSql returnType++{- | Type to represent the return type given as part of a SQL "CREATE+FUNCTION" statement. E.G. the @trigger@ in++> CREATE FUNCTION my_function RETURNS trigger++'ReturnType' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype ReturnType+  = ReturnType RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | The @trigger@ return type.++@since 1.1.0.0+-}+returnTypeTrigger :: ReturnType+returnTypeTrigger =+  ReturnType (RawSql.fromString "trigger")++{- | Type to represent the language specifier given as part of a SQL "CREATE+FUNCTION" statement. E.G. the @LANGUAGE plpgsql@ in++> CREATE FUNCTION my_function LANGUAGE plpgsql++'FunctionLanguage' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype FunctionLanguage+  = FunctionLanguage RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Constructs a @LANGUAGE@ specifier for a @CREATE FUNCTION@ statement with the+  given language name as the language.++@since 1.1.0.0+-}+language :: LanguageName -> FunctionLanguage+language name =+  FunctionLanguage $ RawSql.fromString "LANGUAGE " <> RawSql.toRawSql name++{- | Type to represent the language that the function definition is given in as part+of a SQL "CREATE FUNCTION" statement. E.G. the @plpgsql@ in++> CREATE FUNCTION my_function LANGUAGE plpgsql++'LanguageName' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype LanguageName+  = LanguageName RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | The @plpgsql@ language.++@since 1.1.0.0+-}+plpgsql :: LanguageName+plpgsql =+  LanguageName (RawSql.fromString "plpgsql")++{- | Type to represent the definition body of a a SQL "CREATE FUNCTION" statement. E.G. the+@AS <definition>@ in++> CREATE FUNCTION my_function AS <definition>++'FunctionDefinition' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype FunctionDefinition+  = FunctionDefinition RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Constructs a 'FunctionDefinition' from a 'String', which will be passed as an+  escaped string literal to PosgreSQL.++@since 1.1.0.0+-}+asDefinition :: String -> FunctionDefinition+asDefinition body =+  FunctionDefinition $+    RawSql.fromString "AS " <> RawSql.stringLiteral (BS8.pack body)

@@ -1,7 +1,7 @@ {-# LANGUAGE GeneralizedNewtypeDeriving #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2024 License   : MIT Stability : Stable @@ -18,11 +18,10 @@  import Data.List.NonEmpty (NonEmpty) -import Orville.PostgreSQL.Expr.Name (ColumnName)+import Orville.PostgreSQL.Expr.Name (ColumnName, QualifiedOrUnqualified) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL group by clause. E.G.+{- | Type to represent a SQL group by clause. E.G.  > GROUP BY team_name @@ -46,8 +45,7 @@ groupByClause :: GroupByExpr -> GroupByClause groupByClause expr = GroupByClause (RawSql.fromString "GROUP BY " <> RawSql.toRawSql expr) -{- |-Type to represent a SQL group by expression (the part that follows the+{- | Type to represent a SQL group by expression (the part that follows the @GROUP BY@ in SQL). E.G.  > team_name@@ -83,6 +81,6 @@  @since 1.0.0.0 -}-groupByColumnsExpr :: NonEmpty ColumnName -> GroupByExpr+groupByColumnsExpr :: NonEmpty (QualifiedOrUnqualified ColumnName) -> GroupByExpr groupByColumnsExpr =   GroupByExpr . RawSql.intercalate RawSql.commaSpace

@@ -15,8 +15,7 @@  import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL "IF EXISTS" expression. E.G.+{- | Type to represent a SQL "IF EXISTS" expression. E.G.  > IF EXISTS @@ -33,8 +32,7 @@       RawSql.SqlExpression     ) -{- |-A value of the SQL "IF EXISTS".+{- | A value of the SQL "IF EXISTS".  @since 1.0.0.0 -}

@@ -0,0 +1,44 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.IfNotExists+  ( IfNotExists+  , ifNotExists+  )+where++import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent a SQL "IF NOT EXISTS" expression. E.G.++> IF NOT EXISTS++It is notable that 'IfNotExists' and 'Orville.PostgreSQL.Expr.IfExists' are not usable in all the+same places.++'IfNotExists' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype IfNotExists+  = IfNotExists RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | A value of the SQL "IF NOT EXISTS".++@since 1.1.0.0+-}+ifNotExists :: IfNotExists+ifNotExists =+  IfNotExists $ RawSql.fromString "IF NOT EXISTS"

@@ -23,11 +23,10 @@  import Data.List.NonEmpty (NonEmpty) -import Orville.PostgreSQL.Expr.Name (ColumnName, IndexName, Qualified, TableName)+import Orville.PostgreSQL.Expr.Name (ColumnName, IndexName, QualifiedOrUnqualified, TableName) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL "CREATE INDEX" statement. E.G.+{- | Type to represent a SQL "CREATE INDEX" statement. E.G.  > CREATE INDEX ON table (foo, bar, baz) @@ -44,8 +43,7 @@       RawSql.SqlExpression     ) -{- |-Construct a SQL CREATE INDEX from an indicator of if the index should be+{- | Construct a SQL CREATE INDEX from an indicator of if the index should be unique, a table, and corresponding collection of 'ColumnName's.  @since 1.0.0.0@@ -53,7 +51,7 @@ createIndexExpr ::   IndexUniqueness ->   Maybe ConcurrentlyExpr ->-  Qualified TableName ->+  QualifiedOrUnqualified TableName ->   NonEmpty ColumnName ->   CreateIndexExpr createIndexExpr uniqueness mbConcurrently tableName columns =@@ -61,14 +59,13 @@     RawSql.fromString "CREATE "       <> uniquenessToSql uniqueness       <> RawSql.fromString "INDEX "-      <> maybe mempty (<> RawSql.space) (fmap RawSql.toRawSql mbConcurrently)+      <> maybe mempty ((<> RawSql.space) . RawSql.toRawSql) mbConcurrently       <> RawSql.fromString "ON "       <> RawSql.toRawSql tableName       <> RawSql.space       <> RawSql.toRawSql (indexBodyColumns columns) -{- |-Construct a SQL CREATE INDEX from an indicator of if the index should be+{- | Construct a SQL CREATE INDEX from an indicator of if the index should be unique, a table, a name for the index, and some SQL representing the rest of the index creation. @@ -77,7 +74,7 @@ createNamedIndexExpr ::   IndexUniqueness ->   Maybe ConcurrentlyExpr ->-  Qualified TableName ->+  QualifiedOrUnqualified TableName ->   IndexName ->   IndexBodyExpr ->   CreateIndexExpr@@ -86,15 +83,14 @@     RawSql.fromString "CREATE "       <> uniquenessToSql uniqueness       <> RawSql.fromString "INDEX "-      <> maybe mempty (<> RawSql.space) (fmap RawSql.toRawSql mbConcurrently)+      <> maybe mempty ((<> RawSql.space) . RawSql.toRawSql) mbConcurrently       <> RawSql.toRawSql indexName       <> RawSql.fromString " ON "       <> RawSql.toRawSql tableName       <> RawSql.space       <> RawSql.toRawSql bodyExpr -{- |-Type to represent the @CONCURRENTLY@ keyword for index creation. E.G.+{- | Type to represent the @CONCURRENTLY@ keyword for index creation. E.G.  > CONCURRENTLY @@ -111,8 +107,7 @@       RawSql.SqlExpression     ) -{- |-The @CONCURRENTLY@ keyword indicates to PostgreSQL that an index should be+{- | The @CONCURRENTLY@ keyword indicates to PostgreSQL that an index should be created concurrently.  @since 1.0.0.0@@ -121,8 +116,7 @@ concurrently =   RawSql.unsafeSqlExpression "CONCURRENTLY" -{- |-Type to represent the body of an index definition E.G.+{- | Type to represent the body of an index definition E.G.  > (foo, bar) @@ -143,8 +137,7 @@       RawSql.SqlExpression     ) -{- |-Creates an 'IndexBodyExpr' for the given column names. The resulting+{- | Creates an 'IndexBodyExpr' for the given column names. The resulting SQL looks like @(column1, column2, ...)@.  @since 1.0.0.0@@ -158,8 +151,7 @@       <> RawSql.intercalate RawSql.comma columns       <> RawSql.rightParen -{- |-Type to represent if an index should be unique.+{- | Type to represent if an index should be unique.  @since 1.0.0.0 -}@@ -182,8 +174,7 @@     UniqueIndex -> RawSql.fromString "UNIQUE "     NonUniqueIndex -> mempty -{- |-Type to represent a SQL "DROP INDEX" statement. E.G.+{- | Type to represent a SQL "DROP INDEX" statement. E.G.  > DROP INDEX foo @@ -200,12 +191,11 @@       RawSql.SqlExpression     ) -{- |-Construct a SQL DROP INDEX for a given 'IndexName'.+{- | Construct a SQL DROP INDEX for a given 'IndexName'.  @since 1.0.0.0 -}-dropIndexExpr :: IndexName -> DropIndexExpr+dropIndexExpr :: QualifiedOrUnqualified IndexName -> DropIndexExpr dropIndexExpr indexName =   DropIndexExpr $     RawSql.fromString "DROP INDEX " <> RawSql.toRawSql indexName

@@ -1,7 +1,7 @@ {-# LANGUAGE GeneralizedNewtypeDeriving #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2024 License   : MIT Stability : Stable @@ -16,18 +16,21 @@   , insertSqlValues   , RowValues   , rowValues+  , valuesExprInsertSource   ) where  import Data.Maybe (catMaybes) -import Orville.PostgreSQL.Expr.Name (ColumnName, Qualified, TableName)+import qualified Data.List.NonEmpty as NE+import Orville.PostgreSQL.Expr.Name (ColumnName, QualifiedOrUnqualified, TableName)+import Orville.PostgreSQL.Expr.OnConflict (OnConflictExpr) import Orville.PostgreSQL.Expr.ReturningExpr (ReturningExpr)+import Orville.PostgreSQL.Expr.Values (ValuesExpr) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql import Orville.PostgreSQL.Raw.SqlValue (SqlValue) -{- |-Type to represent a SQL "INSERT" statement. E.G.+{- | Type to represent a SQL "INSERT" statement. E.G.  > INSERT INTO foo (id) VALUES (1),(3),(3) @@ -52,12 +55,13 @@ @since 1.0.0.0 -} insertExpr ::-  Qualified TableName ->+  QualifiedOrUnqualified TableName ->   Maybe InsertColumnList ->   InsertSource ->+  Maybe OnConflictExpr ->   Maybe ReturningExpr ->   InsertExpr-insertExpr target maybeInsertColumns source maybeReturning =+insertExpr target maybeInsertColumns source maybeOnConflict maybeReturning =   InsertExpr     . RawSql.intercalate RawSql.space     $ catMaybes@@ -65,11 +69,11 @@       , Just $ RawSql.toRawSql target       , fmap RawSql.toRawSql maybeInsertColumns       , Just $ RawSql.toRawSql source+      , fmap RawSql.toRawSql maybeOnConflict       , fmap RawSql.toRawSql maybeReturning       ] -{- |-Type to represent the SQL columns list for an insert statement. E.G.+{- | Type to represent the SQL columns list for an insert statement. E.G.  > (foo,bar,baz) @@ -91,15 +95,15 @@  @since 1.0.0.0 -}-insertColumnList :: [ColumnName] -> InsertColumnList+insertColumnList :: [QualifiedOrUnqualified ColumnName] -> InsertColumnList insertColumnList columnNames =   InsertColumnList $-    RawSql.leftParen-      <> RawSql.intercalate RawSql.comma (fmap RawSql.toRawSql columnNames)-      <> RawSql.rightParen+    maybe+      mempty+      (RawSql.parenthesized . RawSql.intercalate RawSql.comma . fmap RawSql.toRawSql)+      (NE.nonEmpty columnNames) -{- |-Type to represent the SQL for the source of data for an insert statement. E.G.+{- | Type to represent the SQL for the source of data for an insert statement. E.G.  > VALUES ('Bob',32),('Cindy',33) @@ -116,6 +120,15 @@       RawSql.SqlExpression     ) +{- | Use a 'ValuesExpr' as an 'InsertSource'.++@since 1.1.0.0+-}+valuesExprInsertSource :: ValuesExpr -> InsertSource+valuesExprInsertSource = InsertSource . RawSql.toRawSql++{-# DEPRECATED insertRowValues "Use Orville.PostgreSQL.Expr.valuesExpr and Orville.PostgreSQL.Expr.valuesExprInsertSource" #-}+ {- | Create an 'InsertSource' for the given 'RowValues'. This ensures that all input values are used as parameters and comma-separated in the generated SQL. @@ -127,6 +140,8 @@     RawSql.fromString "VALUES "       <> RawSql.intercalate RawSql.comma (fmap RawSql.toRawSql rows) +{-# DEPRECATED insertSqlValues "Use Orville.PostgreSQL.Expr.ValuesExpr and Orivlle.PostgreSQL.Expr.valuesExprInsertSource" #-}+ {- | Create an 'InsertSource' for the given 'SqlValue's. This ensures that all input values are used as parameters and comma-separated in the generated SQL. @@ -136,8 +151,7 @@ insertSqlValues =   insertRowValues . fmap rowValues -{- |-Type to represent a SQL row literal. For example, a single row to insert+{- | Type to represent a SQL row literal. For example, a single row to insert in a @VALUES@ clause. E.G.  > ('Cindy',33)

@@ -0,0 +1,46 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024-2205+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Internal.Name.Alias+  ( AliasExpr+  , stringToAliasExpr+  )+where++import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent a SQL alias. 'AliasExpr' values constructed+via the 'alias' function will be properly escaped as part of the+generated SQL. E.G.++> "some_alias"++'AliasExpr' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype AliasExpr+  = AliasExpr Identifier+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    , -- | @since 1.1.0.0+      IdentifierExpression+    )++{- | Construct an 'AliasExpr' from a 'String' with proper escaping as part of the generated SQL.++@since 1.1.0.0+-}+stringToAliasExpr :: String -> AliasExpr+stringToAliasExpr =+  AliasExpr . identifier

@@ -16,8 +16,7 @@ import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL column name. 'ColumnName' values constructed via the+{- | Type to represent a SQL column name. 'ColumnName' values constructed via the 'columnName' function will be properly escaped as part of the generated SQL. E.G.  > "some_column_name"@@ -37,8 +36,7 @@       IdentifierExpression     ) -{- |-Construct a 'ColumnName' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct a 'ColumnName' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}

@@ -16,8 +16,7 @@ import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL constraint name. 'ConstraintName' values constructed+{- | Type to represent a SQL constraint name. 'ConstraintName' values constructed via the 'constraintName' function will be properly escaped as part of the generated SQL. E.G. @@ -38,8 +37,7 @@       IdentifierExpression     ) -{- |-Construct a 'ConstraintName' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct a 'ConstraintName' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}

@@ -16,8 +16,7 @@ import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL cursor name. 'CursorName' values constructed+{- | Type to represent a SQL cursor name. 'CursorName' values constructed via the 'cursorName' function will be properly escaped as part of the generated SQL. E.G. @@ -38,8 +37,7 @@       IdentifierExpression     ) -{- |-Construct a 'CursorName' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct a 'CursorName' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}

@@ -0,0 +1,44 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Internal.Name.ExtensionName+  ( ExtensionName+  , extensionName+  )+where++import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent a PostgreSQL extension name. 'ExtensionName' values constructed via the+'extensionName' function will be properly escaped as part of the generated SQL. E.G.++> "some_extension_name"++'ExtensionName' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype ExtensionName+  = ExtensionName Identifier+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    , -- | @since 1.1.0.0+      IdentifierExpression+    )++{- | Construct an 'ExtensionName' from a 'String'.++@since 1.1.0.0+-}+extensionName :: String -> ExtensionName+extensionName = ExtensionName . identifier

@@ -10,14 +10,37 @@ module Orville.PostgreSQL.Expr.Internal.Name.FunctionName   ( FunctionName   , functionName+  , arrayAggFunctionName+  , avgFunctionName+  , bitAndFunctionName+  , bitOrFunctionName+  , bitXorFunctionName+  , boolAndFunctionName+  , boolOrFunctionName+  , countFunctionName+  , everyFunctionName+  , jsonAggFunctionName+  , jsonObjectAggFunctionName+  , jsonbAggFunctionName+  , jsonbObjectAggFunctionName+  , maxFunctionName+  , minFunctionName+  , stringAggFunctionName+  , sumFunctionName+  , corFunctionName+  , covarPopFunctionName+  , covarSampFunctionName+  , stddevPopFunctionName+  , stddevSampFunctionName+  , varPopFunctionName+  , varSampFunctionName   ) where  import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL function name. 'FunctionName' values constructed+{- | Type to represent a SQL function name. 'FunctionName' values constructed via the 'functionName' function will be properly escaped as part of the generated SQL. E.G. @@ -38,11 +61,178 @@       IdentifierExpression     ) -{- |-Construct a 'FunctionName' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct a 'FunctionName' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -} functionName :: String -> FunctionName functionName =   FunctionName . identifier++{- | The @array_agg@ window function name++@since 1.1.0.0+-}+arrayAggFunctionName :: FunctionName+arrayAggFunctionName = functionName "array_agg"++{- | The @avg@ window function name++@since 1.1.0.0+-}+avgFunctionName :: FunctionName+avgFunctionName = functionName "avg"++{- | The @bit_and@ window function name++@since 1.1.0.0+-}+bitAndFunctionName :: FunctionName+bitAndFunctionName = functionName "bit_and"++{- | The @bit_or@ window function name++@since 1.1.0.0+-}+bitOrFunctionName :: FunctionName+bitOrFunctionName = functionName "bit_or"++{- | The @bit_xor@ window function name++@since 1.1.0.0+-}+bitXorFunctionName :: FunctionName+bitXorFunctionName = functionName "bit_xor"++{- | The @bool_and@ window function name++@since 1.1.0.0+-}+boolAndFunctionName :: FunctionName+boolAndFunctionName = functionName "bool_and"++{- | The @bool_or@ window function name++@since 1.1.0.0+-}+boolOrFunctionName :: FunctionName+boolOrFunctionName = functionName "bool_or"++{- | The @count@ window function name++@since 1.1.0.0+-}+countFunctionName :: FunctionName+countFunctionName = functionName "count"++{- | The @every@ window function name++@since 1.1.0.0+-}+everyFunctionName :: FunctionName+everyFunctionName = functionName "every"++{- | The @json_agg@ window function name++@since 1.1.0.0+-}+jsonAggFunctionName :: FunctionName+jsonAggFunctionName = functionName "json_agg"++{- | The @json_object_agg@ window function name++@since 1.1.0.0+-}+jsonObjectAggFunctionName :: FunctionName+jsonObjectAggFunctionName = functionName "json_object_agg"++{- | The @jsonb_agg@ window function name++@since 1.1.0.0+-}+jsonbAggFunctionName :: FunctionName+jsonbAggFunctionName = functionName "jsonb_agg"++{- | The @jsonb_object_agg@ window function name++@since 1.1.0.0+-}+jsonbObjectAggFunctionName :: FunctionName+jsonbObjectAggFunctionName = functionName "jsonb_object_agg"++{- | The @max@ window function name++@since 1.1.0.0+-}+maxFunctionName :: FunctionName+maxFunctionName = functionName "max"++{- | The @min@ window function name++@since 1.1.0.0+-}+minFunctionName :: FunctionName+minFunctionName = functionName "min"++{- | The @string_agg@ window function name++@since 1.1.0.0+-}+stringAggFunctionName :: FunctionName+stringAggFunctionName = functionName "string_agg"++{- | The @sum@ window function name++@since 1.1.0.0+-}+sumFunctionName :: FunctionName+sumFunctionName = functionName "sum"++{- | The @cor@ window function name++@since 1.1.0.0+-}+corFunctionName :: FunctionName+corFunctionName = functionName "cor"++{- | The @covar_pop@ window function name++@since 1.1.0.0+-}+covarPopFunctionName :: FunctionName+covarPopFunctionName = functionName "covar_pop"++{- | The @covar_samp@ window function name++@since 1.1.0.0+-}+covarSampFunctionName :: FunctionName+covarSampFunctionName = functionName "covar_samp"++{- | The @stddev_pop@ window function name++@since 1.1.0.0+-}+stddevPopFunctionName :: FunctionName+stddevPopFunctionName = functionName "stddev_pop"++{- | The @stddev_samp@ window function name++@since 1.1.0.0+-}+stddevSampFunctionName :: FunctionName+stddevSampFunctionName = functionName "stddev_samp"++{- | The @var_pop@ window function name++@since 1.1.0.0+-}+varPopFunctionName :: FunctionName+varPopFunctionName = functionName "var_pop"++{- | The @var_samp@ window function name++@since 1.1.0.0+-}+varSampFunctionName :: FunctionName+varSampFunctionName = functionName "var_samp"

@@ -18,8 +18,7 @@ import qualified Data.ByteString.Char8 as B8 import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL identifier. 'Identifier' values constructed via the+{- | Type to represent a SQL identifier. 'Identifier' values constructed via the 'identifier' function will be properly escaped as part of the generated SQL. E.G. @@ -38,8 +37,7 @@       RawSql.SqlExpression     ) -{- |-Construct an 'Identifier' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct an 'Identifier' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}@@ -47,8 +45,7 @@ identifier =   identifierFromBytes . B8.pack -{- |-Construct an 'Identifier' from a 'B8.ByteString' with proper escaping as part of the generated SQL.+{- | Construct an 'Identifier' from a 'B8.ByteString' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}

@@ -16,8 +16,7 @@ import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL index name. 'IndexName' values constructed via the+{- | Type to represent a SQL index name. 'IndexName' values constructed via the 'indexName' function will be properly escaped as part of the generated SQL. E.G.  > "some_index_name"@@ -37,8 +36,7 @@       IdentifierExpression     ) -{- |-Construct an 'IndexName' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct an 'IndexName' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}

@@ -1,7 +1,7 @@ {-# LANGUAGE GeneralizedNewtypeDeriving #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -11,22 +11,69 @@   ( Qualified   , qualifyTable   , qualifySequence+  , qualifyFunction+  , qualifyIndex   , qualifyColumn+  , aliasQualifyColumn+  , QualifiedOrUnqualified+  , untrackQualified+  , unqualified   ) where +import Orville.PostgreSQL.Expr.Internal.Name.Alias (AliasExpr) import Orville.PostgreSQL.Expr.Internal.Name.ColumnName (ColumnName)+import Orville.PostgreSQL.Expr.Internal.Name.FunctionName (FunctionName) import Orville.PostgreSQL.Expr.Internal.Name.Identifier (IdentifierExpression (toIdentifier))+import Orville.PostgreSQL.Expr.Internal.Name.IndexName (IndexName) import Orville.PostgreSQL.Expr.Internal.Name.SchemaName (SchemaName) import Orville.PostgreSQL.Expr.Internal.Name.SequenceName (SequenceName) import Orville.PostgreSQL.Expr.Internal.Name.TableName (TableName) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a qualified SQL name. E.G.+{- | Type to represent a SQL name that could be qualified or not. E.G.  > "some_schema_name"."some_table_name" +or++> "some_table_name"++'QualifiedOrUnqualified' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype QualifiedOrUnqualified name+  = QualifiedOrUnqualified RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | 'untrackQualified' loses the information of the value certainly having a qualification. This is+   useful when working with functionality that takes a 'QualifiedOrUnqualifed name'.++@since 1.1.0.0+-}+untrackQualified :: Qualified name -> QualifiedOrUnqualified name+untrackQualified =+  QualifiedOrUnqualified . RawSql.toRawSql++{- | 'unqualified' loses the information of the value not having a qualification. This is+   useful when working with functionality that takes a 'QualifiedOrUnqualifed name'.++@since 1.1.0.0+-}+unqualified :: RawSql.SqlExpression name => name -> QualifiedOrUnqualified name+unqualified =+  QualifiedOrUnqualified . RawSql.toRawSql++{- | Type to represent a qualified SQL name. E.G.++> "some_schema_name"."some_table_name"+ 'Qualified' provides a 'RawSql.SqlExpression' instance. See 'RawSql.unsafeSqlExpression' for how to construct a value with your own custom SQL.@@ -40,8 +87,7 @@       RawSql.SqlExpression     ) -{- |-Optionally qualifies a 'TableName' with a 'SchemaName'.+{- | Qualifies a 'TableName' with a 'SchemaName'.  Note: If you already have a 'Orville.PostgreSQL.Schema.TableIdentifier' in hand you should probably use@@ -49,13 +95,12 @@ @since 1.0.0.0 -} qualifyTable ::-  Maybe SchemaName ->+  SchemaName ->   TableName ->   Qualified TableName qualifyTable = unsafeSchemaQualify -{- |-Optionally qualifies a 'SequenceName' with a 'SchemaName'.+{- | Qualifies a 'SequenceName' with a 'SchemaName'.  Note: If you already have a 'Orville.PostgreSQL.Schema.SequenceIdentifier' in hand you should probably use@@ -64,13 +109,35 @@ @since 1.0.0.0 -} qualifySequence ::-  Maybe SchemaName ->+  SchemaName ->   SequenceName ->   Qualified SequenceName qualifySequence = unsafeSchemaQualify -{- |-Qualifies a 'ColumnName' with a 'TableName' and, optionally, a 'SchemaName'.+{- | Qualifies a 'FunctionName' with a 'SchemaName'.++Note: If you already have a 'Orville.PostgreSQL.Schema.FunctionIdentifier' in+hand you should probably use+'Orville.PostgreSQL.Schema.functionIdQualifiedName' instead.++@since 1.1.0.0+-}+qualifyFunction ::+  SchemaName ->+  FunctionName ->+  Qualified FunctionName+qualifyFunction = unsafeSchemaQualify++{- | Qualifies an 'IndexName' with a 'SchemaName'.+@since 1.1.0.0+-}+qualifyIndex ::+  SchemaName ->+  IndexName ->+  Qualified IndexName+qualifyIndex = unsafeSchemaQualify++{- | Qualifies a 'ColumnName' with a 'TableName' and, optionally, a 'SchemaName'. This should be used to refer to the column in SQL queries where a qualified reference is appropriate. @@ -78,25 +145,47 @@ -} qualifyColumn :: Maybe SchemaName -> TableName -> ColumnName -> Qualified ColumnName qualifyColumn mbSchemaName tableName unqualifiedName =-  unsafeSchemaQualify mbSchemaName-    . RawSql.unsafeFromRawSql-    $ RawSql.toRawSql (toIdentifier tableName) <> RawSql.dot <> RawSql.toRawSql (toIdentifier unqualifiedName)+  let+    tableQualifiedColumn =+      rawQualify tableName unqualifiedName+  in+    case mbSchemaName of+      Nothing ->+        Qualified tableQualifiedColumn+      Just schemaName ->+        Qualified (rawQualify schemaName tableQualifiedColumn) +{- | Qualifies a 'ColumnName' with an 'AliasExpr'. This should be used to refer to the column+in SQL queries where an aliased reference is appropriate.++@since 1.1.0.0+-}+aliasQualifyColumn :: AliasExpr -> ColumnName -> Qualified ColumnName+aliasQualifyColumn aliasName =+  Qualified . rawQualify aliasName+ -- Note: Not everything actually makes sense to be qualified by _only_ a schema name, such as -- columns, as in 'qualifyColumn'. But this does give us a nice uniform way to provide the -- functionality in those more type restricted scenarios. unsafeSchemaQualify ::   IdentifierExpression name =>-  Maybe SchemaName ->+  SchemaName ->   name ->   Qualified name-unsafeSchemaQualify mbSchemaName unqualifiedName =-  case mbSchemaName of-    Nothing ->-      Qualified . RawSql.toRawSql . toIdentifier $ unqualifiedName-    Just schemaName ->-      Qualified-        ( RawSql.toRawSql schemaName-            <> RawSql.dot-            <> RawSql.toRawSql (toIdentifier unqualifiedName)-        )+unsafeSchemaQualify schemaName =+  Qualified . rawQualify schemaName . toIdentifier++{- |+  An internal helper to qualify any sql expressions as raw sql. The types for this+  function do not enforce any relationship between the qualifier and the qualified+  name, and the result is 'RawSql' rather than any more specific expression type.+-}+rawQualify ::+  (RawSql.SqlExpression qualifier, RawSql.SqlExpression name) =>+  qualifier ->+  name ->+  RawSql.RawSql+rawQualify qualifier name =+  RawSql.toRawSql qualifier+    <> RawSql.dot+    <> RawSql.toRawSql name

@@ -16,8 +16,7 @@ import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL savepoint name. 'SavepointName' values constructed via+{- | Type to represent a SQL savepoint name. 'SavepointName' values constructed via the 'savepointName' function will be properly escaped as part of the generated SQL. E.G. @@ -38,8 +37,7 @@       IdentifierExpression     ) -{- |-Construct a 'SavepointName' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct a 'SavepointName' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}

@@ -16,8 +16,7 @@ import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL schema name. 'SchemaName' values constructed via the+{- | Type to represent a SQL schema name. 'SchemaName' values constructed via the 'schemaName' function will be properly escaped as part of the generated SQL. E.G. @@ -38,8 +37,7 @@       IdentifierExpression     ) -{- |-Construct a 'SchemaName' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct a 'SchemaName' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}

@@ -16,8 +16,7 @@ import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL sequence name. 'SequenceName' values constructed via+{- | Type to represent a SQL sequence name. 'SequenceName' values constructed via the 'sequenceName' function will be properly escaped as part of the generated SQL. E.G. @@ -38,8 +37,7 @@       IdentifierExpression     ) -{- |-Construct a 'SequenceName' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct a 'SequenceName' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}

@@ -16,8 +16,7 @@ import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier) import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL table name. 'TableName' values constructed via the+{- | Type to represent a SQL table name. 'TableName' values constructed via the 'tableName' function will be properly escaped as part of the generated SQL. E.G. @@ -38,8 +37,7 @@       IdentifierExpression     ) -{- |-Construct a 'TableName' from a 'String' with proper escaping as part of the generated SQL.+{- | Construct a 'TableName' from a 'String' with proper escaping as part of the generated SQL.  @since 1.0.0.0 -}

@@ -0,0 +1,46 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Internal.Name.TriggerName+  ( TriggerName+  , triggerName+  )+where++import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent a SQL trigger name. 'TriggerName' values constructed via the+'triggerName' function will be properly escaped as part of the generated SQL.+E.G.++> "some_trigger_name"++'TriggerName' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype TriggerName+  = TriggerName Identifier+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    , -- | @since 1.1.0.0+      IdentifierExpression+    )++{- | Construct a 'TriggerName' from a 'String' with proper escaping as part of the generated SQL.++@since 1.1.0.0+-}+triggerName :: String -> TriggerName+triggerName =+  TriggerName . identifier

@@ -0,0 +1,46 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Internal.Name.WindowName+  ( WindowName+  , windowName+  )+where++import Orville.PostgreSQL.Expr.Internal.Name.Identifier (Identifier, IdentifierExpression, identifier)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent a SQL window name. 'WindowName' values constructed+via the 'windowName' window will be properly escaped as part of the+generated SQL. E.G.++> "some_window_name"++'WindowName' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype WindowName+  = WindowName Identifier+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    , -- | @since 1.1.0.0+      IdentifierExpression+    )++{- | Construct a 'WindowName' from a 'String' with proper escaping as part of the generated SQL.++@since 1.1.0.0+-}+windowName :: String -> WindowName+windowName =+  WindowName . identifier

@@ -0,0 +1,189 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024-2025+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.Join+  ( JoinType+  , innerJoinType+  , leftJoinType+  , rightJoinType+  , fullJoinType+  , leftLateralJoinType+  , innerLateralJoinType+  , JoinConstraint+  , joinOnConstraint+  , joinedTable+  , join+  , joining+  ) where++import Orville.PostgreSQL.Expr.TableReferenceList (TableReference)+import Orville.PostgreSQL.Expr.WhereClause (BooleanExpr)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Representation of what kind of 'JOIN' to perform.++  From the documentation at https://www.postgresql.org/docs/15/sql-select.html there are 4 basic+  types of join.++  - Inner join+    Use 'innerJoinType' for constructing+  - Left join+    Sometimes called a left "outer" join. Use 'leftJoinType' for construction.+  - Right join+    Sometimes called a right "outer" join. use 'rightJoinType' for construction.+  - Full join+    Sometimes called a full "outer" join. Use 'fullJoinType' for construction.++@since 1.1.0.0+-}+newtype JoinType = JoinType RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Constructs a 'JoinType' for an INNER JOIN.++@since 1.1.0.0+-}+innerJoinType :: JoinType+innerJoinType = JoinType $ RawSql.fromString "INNER JOIN"++{- | Constructs a 'JoinType' for a LEFT JOIN.++  Note that the documentation at https://www.postgresql.org/docs/15/sql-select.html describes the+  keyword OUTER as optional, and the sql generated from here omits it for brevity of query.++@since 1.1.0.0+-}+leftJoinType :: JoinType+leftJoinType = JoinType $ RawSql.fromString "LEFT JOIN"++{- | Constructs a 'JoinType' for a RIGHT JOIN.++  Note that the documentation at https://www.postgresql.org/docs/15/sql-select.html describes the+  keyword OUTER as optional, and the sql generated from here omits it for brevity of query.++@since 1.1.0.0+-}+rightJoinType :: JoinType+rightJoinType = JoinType $ RawSql.fromString "RIGHT JOIN"++{- | Constructs a 'JoinType' for a FULL JOIN.++  Note that the documentation at https://www.postgresql.org/docs/15/sql-select.html describes the+  keyword OUTER as optional, and the sql generated from here omits it for brevity of query.++@since 1.1.0.0+-}+fullJoinType :: JoinType+fullJoinType = JoinType $ RawSql.fromString "FULL JOIN"++{- | Constructs a 'JoinType' for a LEFT JOIN LATERAL.++  Note that the documentation at https://www.postgresql.org/docs/15/sql-select.html describes the+  keyword OUTER as optional, and the sql generated from here omits it for brevity of query.++@since 1.1.0.0+-}+leftLateralJoinType :: JoinType+leftLateralJoinType = JoinType $ RawSql.fromString "LEFT JOIN LATERAL"++{- | Constructs a 'JoinType' for an INNER JOIN.++@since 1.1.0.0+-}+innerLateralJoinType :: JoinType+innerLateralJoinType = JoinType $ RawSql.fromString "JOIN LATERAL"++{- | Representation of the "ON" part of a JOIN in sql.++@since 1.1.0.0+-}+newtype JoinConstraint = JoinConstraint RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Constructs a 'JoinConstraint' from a given 'BooleanExpr' that specifies which rows in the JOIN are+   considering to match.++@since 1.1.0.0+-}+joinOnConstraint :: BooleanExpr -> JoinConstraint+joinOnConstraint booleanExpr =+  JoinConstraint $+    RawSql.fromString "ON " <> RawSql.toRawSql booleanExpr++{- | Constructs a 'TableReference' by creating a join expression from two existing table references.+  The result is an @n+m@ way join, where @n@ is the number of tables referenced in the first table+  reference expression (which itself may be a join) and @m@ is the number of tables referenced by+  the second table reference expression.++  See also: 'join', 'joining'++@since 1.1.0.0+-}+joinedTable ::+  TableReference ->+  JoinType ->+  TableReference ->+  JoinConstraint ->+  TableReference+joinedTable tableRefA joinType tableRefB joinOn =+  RawSql.unsafeFromRawSql $+    RawSql.toRawSql tableRefA+      <> RawSql.space+      <> RawSql.toRawSql joinType+      <> RawSql.space+      <> RawSql.toRawSql tableRefB+      <> RawSql.space+      <> RawSql.toRawSql joinOn++{- | A flipped version of 'joinedTable' that allows joined tables to be constructed in a syntax more+  similar to SQL. For example:++  @@+    fooTableRef+      & join leftJoinType barTableRef someJoinCondition+      & join leftJoinType bazTableRef someOtherJoinCondition+  @@++  See also: 'joining', 'joinedTable'++  @since 1.1.0.0+-}+join ::+  JoinType ->+  TableReference ->+  JoinConstraint ->+  TableReference ->+  TableReference+join joinType tableRefB joinOn tableRefA =+  joinedTable tableRefA joinType tableRefB joinOn++{- | A convenience function for constructing joins by tracking the tables to be joined in a list+  instead of using the '(&)' operator. The tables will be joined in a left associative manner,+  matching the associativity of the analogous SQL expression.++  @@+    joining fooTableRef+      [ join leftJoinType barTableRef someJoinCondition+      , join leftJoinType bazTableRef someOtherJoinCondition+      ]+  @@++  See also: 'join', 'joinedTable'++  @since 1.1.0.0+-}+joining :: TableReference -> [TableReference -> TableReference] -> TableReference+joining tableRef joinList =+  foldr (flip (.)) id joinList tableRef

@@ -16,8 +16,7 @@ import qualified Orville.PostgreSQL.Raw.RawSql as RawSql import qualified Orville.PostgreSQL.Raw.SqlValue as SqlValue -{- |-Type to represent a SQL limit expression. E.G.+{- | Type to represent a SQL limit expression. E.G.  > LIMIT 10 

@@ -1,7 +1,7 @@ {-# OPTIONS_GHC -Wno-missing-import-lists #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2024 License   : MIT Stability : Stable @@ -12,9 +12,11 @@   ) where +import Orville.PostgreSQL.Expr.Internal.Name.Alias as Export import Orville.PostgreSQL.Expr.Internal.Name.ColumnName as Export import Orville.PostgreSQL.Expr.Internal.Name.ConstraintName as Export import Orville.PostgreSQL.Expr.Internal.Name.CursorName as Export+import Orville.PostgreSQL.Expr.Internal.Name.ExtensionName as Export import Orville.PostgreSQL.Expr.Internal.Name.FunctionName as Export import Orville.PostgreSQL.Expr.Internal.Name.Identifier as Export import Orville.PostgreSQL.Expr.Internal.Name.IndexName as Export@@ -23,3 +25,5 @@ import Orville.PostgreSQL.Expr.Internal.Name.SchemaName as Export import Orville.PostgreSQL.Expr.Internal.Name.SequenceName as Export import Orville.PostgreSQL.Expr.Internal.Name.TableName as Export+import Orville.PostgreSQL.Expr.Internal.Name.TriggerName as Export+import Orville.PostgreSQL.Expr.Internal.Name.WindowName as Export

@@ -16,8 +16,7 @@ import qualified Orville.PostgreSQL.Raw.RawSql as RawSql import qualified Orville.PostgreSQL.Raw.SqlValue as SqlValue -{- |-Type to represent a SQL offset expression. E.G.+{- | Type to represent a SQL offset expression. E.G.  > OFFSET 10 

@@ -0,0 +1,193 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.OnConflict+  ( OnConflictExpr+  , onConflict+  , onConflictDoNothing+  , onConflictDoUpdate+  , ConflictTargetExpr+  , conflictTargetForIndexColumn+  , conflictTargetForIndexExpr+  , conflictTargetForConstraint+  , ConflictActionExpr+  , ConflictSetItemExpr+  , setColumnNameExcluded+  )+where++import Data.List.NonEmpty (NonEmpty)++import Orville.PostgreSQL.Expr.Index (IndexBodyExpr)+import Orville.PostgreSQL.Expr.Internal.Name.ConstraintName (ConstraintName)+import Orville.PostgreSQL.Expr.Name (ColumnName, QualifiedOrUnqualified)+import Orville.PostgreSQL.Expr.WhereClause (WhereClause)+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent the SQL for the 'ON CONFLICT' clause.++'OnConflict' provides a 'RawSql.SqlExpression' instance. See 'RawSql.unsafeSqlExpression' for how to+construct a value with your own custom SQL.++@since 1.1.0.0+-}+newtype OnConflictExpr+  = OnConflictExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Create an 'OnConflict' that performs the specified action to be taken during a conflicting insert.++@since 1.1.0.0+-}+onConflict :: Maybe ConflictTargetExpr -> ConflictActionExpr -> OnConflictExpr+onConflict mbTarget action =+  OnConflictExpr $+    RawSql.fromString "ON CONFLICT "+      <> case mbTarget of+        Nothing ->+          RawSql.toRawSql action+        Just target ->+          RawSql.toRawSql target <> RawSql.space <> RawSql.toRawSql action++{- | A wrapper around 'onConflict' for no specific target and an explicit no action to perform.++@since 1.1.0.0+-}+onConflictDoNothing :: OnConflictExpr+onConflictDoNothing =+  onConflict Nothing doNothingActionExpr++{- | A wrapper around 'onConflict' to perform an update, with optional target and where clause. That+   will use the given 'ConflictSetItemExpr's as the update body.++@since 1.1.0.0+-}+onConflictDoUpdate :: Maybe ConflictTargetExpr -> NonEmpty ConflictSetItemExpr -> Maybe WhereClause -> OnConflictExpr+onConflictDoUpdate mbTarget setItems =+  onConflict mbTarget . doUpdateSetActionExpr setItems++{- | Type to represent the target portion of the SQL 'ON CONFLICT target action'++@since 1.1.0.0+-}+newtype ConflictTargetExpr+  = ConflictTargetExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Build a 'ConflictTargetExpr' that would conflict on a single 'ColumnName'. PostgreSQL will use+   the column to infer which index to check for conflicts.++@since 1.1.0.0+-}+conflictTargetForIndexColumn :: QualifiedOrUnqualified ColumnName -> Maybe WhereClause -> ConflictTargetExpr+conflictTargetForIndexColumn colName mbWhere =+  let+    parensCol = RawSql.parenthesized $ RawSql.toRawSql colName+  in+    ConflictTargetExpr $+      case mbWhere of+        Nothing -> parensCol+        Just whereClause -> parensCol <> RawSql.space <> RawSql.toRawSql whereClause++{- | Build a 'ConflictTargetExpr' that would conflict on an 'IndexBodyExpr'. This can be used to check+   for more than a single column. PostgreSQL will use the expression to infer which index to check for+   conflicts.++   Note that this function assumes that the 'IndexBodyExpr' is parenthesized.+@since 1.1.0.0+-}+conflictTargetForIndexExpr :: IndexBodyExpr -> Maybe WhereClause -> ConflictTargetExpr+conflictTargetForIndexExpr idxBody mbWhere =+  let+    rawIdxBody = RawSql.toRawSql idxBody+  in+    ConflictTargetExpr $+      case mbWhere of+        Nothing -> rawIdxBody+        Just whereClause -> rawIdxBody <> RawSql.space <> RawSql.toRawSql whereClause++{- | Build a 'ConflictTargetExpr' for conflicting on the given 'ConstraintName'. For conflicing on an+   index, see 'conflictTargetForIndexColumn' or 'conflictTargetForIndexExpr' instead.++@since 1.1.0.0+-}+conflictTargetForConstraint :: ConstraintName -> ConflictTargetExpr+conflictTargetForConstraint constraintName =+  ConflictTargetExpr $ RawSql.fromString "ON CONSTRAINT " <> RawSql.toRawSql constraintName++{- | Type to represent the action portion of the SQL 'ON CONFLICT target action'++@since 1.1.0.0+-}+newtype ConflictActionExpr+  = ConflictActionExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | A 'ConflictActionExpr' for the SQL 'DO NOTHING'.++@since 1.1.0.0+-}+doNothingActionExpr :: ConflictActionExpr+doNothingActionExpr =+  ConflictActionExpr $ RawSql.fromString "DO NOTHING"++{- | A 'ConflictActionExpr' for the SQL 'DO UPDATE SET', that will use the given 'ConflictSetItemExpr'+   to determine which columns to update and the optional 'WhereClause' to peform filtering.++@since 1.1.0.0+-}+doUpdateSetActionExpr :: NonEmpty ConflictSetItemExpr -> Maybe WhereClause -> ConflictActionExpr+doUpdateSetActionExpr setItems mbWhere =+  let+    commaSeparatedItems = RawSql.intercalate RawSql.comma setItems+  in+    ConflictActionExpr $+      RawSql.fromString "DO UPDATE SET "+        <> case mbWhere of+          Nothing -> commaSeparatedItems+          Just whereClause -> commaSeparatedItems <> RawSql.space <> RawSql.toRawSql whereClause++{- | Type to represent the item to be set in an 'ON CONFLICT DO UPDATE'. E.G.++> ON CONFLICT DO UPDATE SET item++@since 1.1.0.0+-}+newtype ConflictSetItemExpr+  = ConflictSetItemExpr RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | Builds a 'ConflictSetItemExpr' that will set the given 'ColumnName' to the excluded value using+the special pseudo-table 'EXCLUDED'.++@since 1.1.0.0+-}+setColumnNameExcluded :: QualifiedOrUnqualified ColumnName -> ConflictSetItemExpr+setColumnNameExcluded colName =+  let+    rawName = RawSql.toRawSql colName+  in+    ConflictSetItemExpr $+      rawName+        <> RawSql.fromString " = "+        <> RawSql.fromString "EXCLUDED"+        <> RawSql.dot+        <> rawName

@@ -0,0 +1,41 @@+{-# LANGUAGE GeneralizedNewtypeDeriving #-}++{- |+Copyright : Flipstone Technology Partners 2024+License   : MIT+Stability : Stable++@since 1.1.0.0+-}+module Orville.PostgreSQL.Expr.OrReplace+  ( OrReplace+  , orReplace+  )+where++import qualified Orville.PostgreSQL.Raw.RawSql as RawSql++{- | Type to represent a SQL "OR REPLACE" expression. E.G.++> OR REPLACE++'OrReplace' provides a 'RawSql.SqlExpression' instance. See+'RawSql.unsafeSqlExpression' for how to construct a value with your own custom+SQL.++@since 1.1.0.0+-}+newtype OrReplace+  = OrReplace RawSql.RawSql+  deriving+    ( -- | @since 1.1.0.0+      RawSql.SqlExpression+    )++{- | A value of the SQL "OR REPLACE".++@since 1.1.0.0+-}+orReplace :: OrReplace+orReplace =+  OrReplace $ RawSql.fromString "OR REPLACE"

@@ -1,7 +1,7 @@ {-# LANGUAGE GeneralizedNewtypeDeriving #-}  {- |-Copyright : Flipstone Technology Partners 2023+Copyright : Flipstone Technology Partners 2023-2025 License   : MIT Stability : Stable @@ -14,6 +14,7 @@   , appendOrderByExpr   , orderByColumnName   , orderByColumnsExpr+  , orderByValueExpression   , OrderByDirection   , NullsOrder (NullsFirst, NullsLast)   , ascendingOrder@@ -25,11 +26,12 @@  import qualified Data.List.NonEmpty as NEL -import Orville.PostgreSQL.Expr.Name (ColumnName)+import Orville.PostgreSQL.Expr.Name (ColumnName, QualifiedOrUnqualified)+import qualified Orville.PostgreSQL.Expr.ValueExpression as ValueExpression+import qualified Orville.PostgreSQL.Internal.Extra.NonEmpty as ExtraNonEmpty import qualified Orville.PostgreSQL.Raw.RawSql as RawSql -{- |-Type to represent a SQL order by clause. E.G.+{- | Type to represent a SQL order by clause. E.G.  > ORDER BY foo, bar @@ -41,13 +43,19 @@ -} newtype OrderByClause   = OrderByClause RawSql.RawSql-  deriving (RawSql.SqlExpression)+  deriving+    ( -- | @since 1.0.0.0+      RawSql.SqlExpression+    ) +{- | Builds a full 'OrderByClause' with the given ordering described in the 'OrderByExpr'++@since 1.0.0.0+-} orderByClause :: OrderByExpr -> OrderByClause orderByClause expr = OrderByClause (RawSql.fromString "ORDER BY " <> RawSql.toRawSql expr) -{- |-Type to represent a SQL order by expression (the part that follows the @ORDER+{- | Type to represent a SQL order by expression (the part that follows the @ORDER BY@ in SQL). E.G.  > foo, bar@@ -64,9 +72,7 @@       RawSql.SqlExpression     ) -{- |-@since 1.0.0.0--}+-- | @since 1.0.0.0 instance Semigroup OrderByExpr where   (<>) = appendOrderByExpr @@ -83,26 +89,26 @@  @since 1.0.0.0 -}-orderByColumnsExpr :: NEL.NonEmpty (ColumnName, OrderByDirection) -> OrderByExpr-orderByColumnsExpr =-  OrderByExpr . RawSql.intercalate RawSql.commaSpace . fmap columnOrdering- where-  columnOrdering :: (ColumnName, OrderByDirection) -> RawSql.RawSql-  columnOrdering (columnName, orderByDirection) =-    RawSql.toRawSql columnName <> RawSql.space <> RawSql.toRawSql orderByDirection+orderByColumnsExpr :: NEL.NonEmpty (QualifiedOrUnqualified ColumnName, OrderByDirection) -> OrderByExpr+orderByColumnsExpr = ExtraNonEmpty.foldMap1' (uncurry orderByColumnName) -{-- |-  Orders a query by the given column name in the given order direction.+{- | Orders a query by the given column name in the given order direction.  @since 1.0.0.0 -}-orderByColumnName :: ColumnName -> OrderByDirection -> OrderByExpr-orderByColumnName =-  curry (orderByColumnsExpr . pure)+orderByColumnName :: QualifiedOrUnqualified ColumnName -> OrderByDirection -> OrderByExpr+orderByColumnName = orderByValueExpression . ValueExpression.columnReference -{- |-Type to represent a SQL order by direction expression. E.G.+{- | Create an 'OrderByExpr' for the given 'ValueExpression.ValueExpression' and 'OrderByDirection'. The caller must ensure that the 'ValueExpression.ValueExpression' is valid as an order by expression. +@since 1.1.0.0+-}+orderByValueExpression :: ValueExpression.ValueExpression -> OrderByDirection -> OrderByExpr+orderByValueExpression value direction =+  OrderByExpr $ RawSql.toRawSql value <> RawSql.space <> RawSql.toRawSql direction++{- | Type to represent a SQL order by direction expression. E.G.+ > ASC  'OrderByDirection' provides a 'RawSql.SqlExpression' instance. See@@ -112,10 +118,12 @@ @since 1.0.0.0 -} newtype OrderByDirection = OrderByDirection RawSql.RawSql-  deriving (RawSql.SqlExpression)+  deriving+    ( -- | @since 1.0.0.0+      RawSql.SqlExpression+    ) -{- |-Type to represent the ordering of Null, intended to be used with 'OrderByDirection'.+{- | Type to represent the ordering of Null, intended to be used with 'OrderByDirection'.  @since 1.0.0.0 -}