persistent-2.12.1.1: ChangeLog.md

# Changelog for persistent

## 2.12.1.1

* [#1231](https://github.com/yesodweb/persistent/pull/1231)
    * Simplify Line type in Quasi module, always use NonEmpty
* [#1229](https://github.com/yesodweb/persistent/pull/1229)
    * The `#id` labels are now generated for entities.

## 2.12.1.0

* [#1218](https://github.com/yesodweb/persistent/pull/1218)
    * Refactoring name generating functions in TH
* [#1226](https://github.com/yesodweb/persistent/pull/1226)
    * Expose the `filterClause` and `filterClauseWithValues` functions to support
      the `upsertWhere` functionality in `persistent-postgresql`.

## 2.12.0.2

* [#1123](https://github.com/yesodweb/persistent/pull/1223)
    * Fix JSON encoding for `PersistValue`

## 2.12.0.1

* Refactoring token parsing in quasi module [#1206](https://github.com/yesodweb/persistent/pull/1206)
* Removing duplication from TH output [#1202](https://github.com/yesodweb/persistent/pull/1202)
* Refactor [] to NonEmpty in Quasi module [#1193](https://github.com/yesodweb/persistent/pull/1193)
* [#1162](https://github.com/yesodweb/persistent/pull/1162)
  * Replace `askLogFunc` with `askLoggerIO`
* Decomposed `HaskellName` into `ConstraintNameHS`, `EntityNameHS`, `FieldNameHS`. Decomposed `DBName` into `ConstraintNameDB`, `EntityNameDB`, `FieldNameDB` respectively. [#1174](https://github.com/yesodweb/persistent/pull/1174)
* Use `resourcet-pool` to break out some `Data.Pool` logic [#1163](https://github.com/yesodweb/persistent/pull/1163)
* [#1178](https://github.com/yesodweb/persistent/pull/1178)
  * Added 'withBaseBackend', 'withCompatible' to ease use of base/compatible backend queries in external code.
* Added GHC 8.2.2 and GHC 8.4.4 back into the CI and `persistent` builds on 8.2.2 again [#1181](https://github.com/yesodweb/persistent/issues/1181)
* [#1179](https://github.com/yesodweb/persistent/pull/1179)
  * Added `Compatible`, a newtype for marking a backend as compatible with another. Use it with `DerivingVia` to derive simple instances based on backend compatibility.
  * Added `makeCompatibleInstances` and `makeCompatibleKeyInstances`, TemplateHaskell invocations for auto-generating standalone derivations using `Compatible` and `DerivingVia`.
* [#1207](https://github.com/yesodweb/persistent/pull/1207)
    * @codygman discovered a bug in [issue #1199](https://github.com/yesodweb/persistent/issues/1199) where postgres connections were being returned to the `Pool SqlBackend` in an inconsistent state.
      @parsonsmatt debugged the issue and determined that it had something to do with asynchronous exceptions.
      Declaring it to be "out of his pay grade," he ripped the `poolToAcquire` function out and replaced it with `Data.Pool.withResource`, which doesn't exhibit the bug.
      Fortunately, this doesn't affect the public API, and can be a mere bug release.
    * Removed the functions `unsafeAcquireSqlConnFromPool`, `acquireASqlConnFromPool`, and `acquireSqlConnFromPoolWithIsolation`.
      For a replacement, see `runSqlPoolNoTransaction` and `runSqlPoolWithHooks`.
* Renaming values in persistent-template [#1203](https://github.com/yesodweb/persistent/pull/1203)
* [#1214](https://github.com/yesodweb/persistent/pull/1214):
    * Absorbed the `persistent-template` package. `persistent-template` will receive a 2.12 release with a warning and a deprecation notice.
    * Remove the `nooverlap` flag. It wasn't being used anymore.
* [#1205](https://github.com/yesodweb/persistent/pull/1205)
    * Introduce the `PersistLiteral_` constructor, replacing the `PersistLiteral`, `PersistLiteralEscaped`, and `PersistDbSpecific`.
    * The old constructors are now pattern synonyms. They don't actually differentiate between the various escaping strategies when consuming them! If you pattern match on multiple of `PersistDbSpecific`, `PersistLiteral`, or `PersistLiteralEscaped` , then you should use the `PersistLiteral_` constructor to differentiate between them.

## 2.11.0.2
* Fix a bug where an empty entity definition would break parsing of `EntityDef`s. [#1176](https://github.com/yesodweb/persistent/issues/1176)

## 2.11.0.1

* Docs/Bugs fixes [#1153](https://github.com/yesodweb/persistent/pull/1153)
  * Fix documentation on `FieldDef.fieldAttrs`.
  * Postgresql backend: Add a space in cascade clause of generated SQL.

## 2.11.0.0

* Foreign Key improvements [#1121](https://github.com/yesodweb/persistent/pull/1121)
  * It is now supported to refer to a table with an auto generated Primary Kay
  * It is now supported to refer to non-primary fields, using the keyword `References`
  * It is now supported to have cascade options for simple/single-field Foreign Keys
* Introduces a breaking change to the internal function `mkColumns`, which can now be passed a record of functions to override its default behavior. [#996](https://github.com/yesodweb/persistent/pull/996)
* Added explicit `forall` notation to make most API functions play nice when using `TypeApplications`. (e.g. instead of `selectList @_ @_ @User [] []`, you can now write `selectList @User [] []`) [#1006](https://github.com/yesodweb/persistent/pull/1006)
* [#1060](https://github.com/yesodweb/persistent/pull/1060)
  * The QuasiQuoter now supports `OnDelete` and `OnUpdate` cascade options.
* [#1044](https://github.com/yesodweb/persistent/pull/1044)
  * Field and constraint labels generated by TH can now be customized.
  * mpsPrefixFields is deprecated in favor of using these customisation functions.
* [#1032](https://github.com/yesodweb/persistent/pull/1032)
  * Instance for `Natural` is removed. See `OverflowNatural` for a
    replacement and rationale on why.
* [#1063](https://github.com/yesodweb/persistent/pull/1063)
  * A new class member `keyFromRecordM` allows you to construct a `Key
    record` from a `record` if it was defined with `Primary`.
* [#1036](https://github.com/yesodweb/persistent/pull/1036)
  * The method `entityIdFromJSON` that is used to parse entities now correctly works for entities that define a custom `Primary` key.
* [#856](https://github.com/yesodweb/persistent/pull/856)
  * Modify `upsertBy` to use backend-specific implementation (if any).
* [#1066](https://github.com/yesodweb/persistent/pull/1066)
  * You can set a column's `sql=id` for a non `Id` column.
* Fix a bug where unsafe migration error messages were being shown using `Show` prior to printing, resulting in less helpful output. [#1080](https://github.com/yesodweb/persistent/pull/1080)
* [#1087](https://github.com/yesodweb/persistent/pull/1087)
  * `RawSql` now has tuple instances up to GHC's max tuple size (62)
* [#1076](https://github.com/yesodweb/persistent/pull/1076)
  * `Loc` is now imported from `monad-logger` as opposed to `template-haskell`. Removes `template-haskell` as an explicit dependency.
* [#1114](https://github.com/yesodweb/persistent/pull/1114)
  * Remove unnecessary deriving of `Typeable`.
* [#1128](https://github.com/yesodweb/persistent/pull/1128)
  * Remove `Monad` constraint on `entityDef`
* [#1127](https://github.com/yesodweb/persistent/pull/1127)
  * Remove deriving of `Show` for uniques. Users that need a `Show` instance can put a standalone deriving instance:

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

* [#1131](https://github.com/yesodweb/persistent/pull/1131)
  * Add an `exists` function to the `PersistQueryRead` type class.
* [#1117](https://github.com/yesodweb/persistent/issues/1117)
  * Allow parsing UTCTimes from sqlite with the format "%F %T%Q" as well, instead of only "%FT%T%Q".
* [#1140](https://github.com/yesodweb/persistent/pull/1140)
  * A new function `checkUniqueUpdateable` allows you to check uniqueness
    constraints on an entity update without having to update it.
* [#1142](https://github.com/yesodweb/persistent/pull/1142)
    * Deprecate `hasCompositeKey` in favor of `hasCustomPrimaryKey` and `hasCompositePrimaryKey` functions.
* [#1098](https://github.com/yesodweb/persistent/pull/1098)
  * Add support for configuring the number of stripes and idle timeout for connection pools
    * For functions that do not specify an idle timeout, the default has been bumped to 600 seconds.
      * This change is based off the experience of two production codebases. See [#775](https://github.com/yesodweb/persistent/issues/775)
    * Add a new type `ConnectionPoolConfig` to configure the number of connections in a pool, their idle timeout, and stripe size.
    * Add `defaultConnectionPoolConfig` to create a `ConnectionPoolConfig`
    * Add `createSqlPoolWithConfig` and `withSqlPoolWithConfig`, which take this new data type
* [#1122](https://github.com/yesodweb/persistent/pull/1122), [#1152](https://github.com/yesodweb/persistent/pull/1152)
  * Adds a new constructor, `PersistLiteral ByteString` to `PersistValue` to support unescaped SQL literals.
    * Obviously, this is highly unsafe, and you should never use it with user input.
  * Adds a new field, `cGenerated :: Maybe Text` to `Column` for backend-specific support of generated columns.
    * Express generated fields in the Persistent DSL

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

    * Support for MySQL >= 5.7. (No version checking is performed! Using this feature with older versions of MySQL will cause runtime SQL exceptions!)
    * Support for Postgresql >= 12. (No version checking is performed! Using this feature with older versions of Postgresql will cause runtime SQL exceptions!)
    * Support for SQLite >= 3.31 (same caveat applies; support added in #1152 )
* [#1151](https://github.com/yesodweb/persistent/pull/1151)
  * Allow `OverloadedLabels` to be used with the `EntityField` type.

## 2.10.5.2

* [#1041](https://github.com/yesodweb/persistent/pull/1041)
  * Explicit foreign keys can now reference tables with custom sql name
  * Add qualified names to the stock classes list.

## 2.10.5.1

* [#1024](https://github.com/yesodweb/persistent/pull/1024)
    * Add the ability to do documentation comments in entity definition syntax. Unfortunately, TemplateHaskell cannot add documentation comments, so this can't be used to add Haddocks to entities.
    * Add Haddock explainers for some of the supported entity syntax in `Database.Persist.Quasi`

## 2.10.5

* Add the `EntityWithPrefix` type to allow users to specify a custom prefix for raw SQL queries. [#1018](https://github.com/yesodweb/persistent/pull/1018)
* Added Acquire based API to `Database.Persist.Sql` for working with
  connections/pools in monads which aren't MonadUnliftIO. [#984](https://github.com/yesodweb/persistent/pull/984)

## 2.10.4

* Log exceptions when closing a connection fails. See point 1 in [yesod #1635](https://github.com/yesodweb/yesod/issues/1635#issuecomment-547300856). [#978](https://github.com/yesodweb/persistent/pull/978)

## 2.10.3

* Added support for GHC 8.8 about MonadFail changes [#976](https://github.com/yesodweb/persistent/pull/976)

## 2.10.2

* Added `runMigrationQuiet` and `runMigrationUnsafeQuiet` to `Database.Persist.Sql.Migration` as safer alternatives to `runMigrationSilent`. [#971](https://github.com/yesodweb/persistent/pull/971)
  This functions as workaround/fix for: [#966](https://github.com/yesodweb/persistent/issues/966), [#948](https://github.com/yesodweb/persistent/issues/948), [#640](https://github.com/yesodweb/persistent/issues/640), and [#474](https://github.com/yesodweb/persistent/issues/474)
* Added RawSql instances for 9, 10, 11 and 12-column results. [#961](https://github.com/yesodweb/persistent/pull/961)

## 2.10.1

* Added `constraint=` attribute to allow users to specify foreign reference constraint names.

## 2.10.0

* Added two type classes `OnlyOneUniqueKey` and `AtLeastOneUniqueKey`. These classes are used as constraints on functions that expect a certain amount of unique keys. They are defined automatically as part of the `persistent-template`'s generation. [#885](https://github.com/yesodweb/persistent/pull/885)
* Add the `entityComments` field to the `EntityDef` datatype, and `fieldComments` fields to the `FieldDef` datatype. The QuasiQuoter does not currently know how to add documentation comments to these types, but it can be expanded later. [#865](https://github.com/yesodweb/persistent/pull/865)
* Expose the `SqlReadT` and `SqlWriteT` constructors. [#887](https://github.com/yesodweb/persistent/pull/887)
* Remove deprecated `Connection` type synonym. Please use `SqlBackend` instead. [#894](https://github.com/yesodweb/persistent/pull/894)
* Remove deprecated `SqlPersist` type synonym. Please use `SqlPersistT` instead. [#894](https://github.com/yesodweb/persistent/pull/894)
* Alter the type of `connUpsertSql` to take a list of unique definitions. This paves the way for more efficient upsert implementations. [#895](https://github.com/yesodweb/persistent/pull/895)

## 2.9.2

* Add documentation for the `Migration` type and some helpers. [#860](https://github.com/yesodweb/persistent/pull/860)

## 2.9.1

* Fix [#847](https://github.com/yesodweb/persistent/issues/847): SQL error with `putMany` on Sqlite when Entity has no unique index.

## 2.9.0

* Added support for SQL isolation levels to via SqlBackend. [#812]
* Move `Database.Persist.Sql.Raw.QQ` to a separate `persistent-qq` package [#827](https://github.com/yesodweb/persistent/issues/827)
* Fix [832](https://github.com/yesodweb/persistent/issues/832): `repsertMany` now matches `mapM_ (uncurry repsert)` and is atomic for supported sql back-ends.

## 2.8.2

* Added support for `sql=` to the unique constraints quasi-quoter so that users can specify the database names of the constraints.

## 2.8.1

* DRY-ed up and exposed several util functions in `Database.Persist.Sql.Util`.
	* Upstream-ed `updatePersistValue`, `mkUpdateText`, and `commaSeparated` from `Database.Persist.MySQL`.
	* De-duplicated `updatePersistValue` from various `Database.Persist.Sql.Orphan.*` modules.
* Batching enhancements to reduce db round-trips.
	* Added `getMany` and `repsertMany` for batched `get` and `repsert`.
	* Added `putMany` with a default/slow implementation. SqlBackend's that support native UPSERT should override this for batching enhancements.
	* Updated `insertEntityMany` to replace slow looped usage with batched execution.
* See [#770](https://github.com/yesodweb/persistent/pull/770)

## 2.8.0

* Switch from `MonadBaseControl` to `MonadUnliftIO`
* Reapplies [#723](https://github.com/yesodweb/persistent/pull/723), which was reverted in version 2.7.3.

## 2.7.3.1

 * Improve error messages when failing to parse database results into Persistent records. [#741](https://github.com/yesodweb/persistent/pull/741)
 * A handful of `fromPersistField` implementations called `error` instead of returning a `Left Text`. All of the implementations were changed to return `Left`. [#741](https://github.com/yesodweb/persistent/pull/741)
 * Improve error message when a SQL insert fails with a custom primary key [#757](https://github.com/yesodweb/persistent/pull/757)

## 2.7.3

* Reverts [#723](https://github.com/yesodweb/persistent/pull/723), which generalized functions using the `BackendCompatible` class. These changes were an accidental breaking change.
* Recommend the `PersistDbSpecific` docs if someone gets an error about converting from `PersistDbSpecific`

## 2.7.2 [DEPRECATED ON HACKAGE]

* Many of the functions have been generalized using the `BackendCompatible` class. [#723](https://github.com/yesodweb/persistent/pull/723)
	* This change was an accidental breaking change and was reverted in 2.7.3.
	* These change will be released in a future version of Persistent with a major version bump.
* Add raw sql quasi quoters [#717](https://github.com/yesodweb/persistent/pull/717)

## 2.7.1

* Added an `insertUniqueEntity` function [#718](https://github.com/yesodweb/persistent/pull/718)
* Added `BackendCompatible` class [#701](https://github.com/yesodweb/persistent/pull/701)

## 2.7.0

* Fix upsert behavior [#613](https://github.com/yesodweb/persistent/issues/613)
* Atomic upsert query fixed for arithmatic operations [#662](https://github.com/yesodweb/persistent/issues/662)
* Haddock and test coverage improved for upsert

## 2.6.1

* Fix edge case for `\<-. [Nothing]`
* Introduce `connMaxParams`
* Add 'getJustEntity' and 'insertRecord' convenience function
* Minor Haddock improvment

## 2.6

* Add `connUpsertSql` type for providing backend-specific upsert sql support.

## 2.5

* read/write typeclass split
* add insertOrGet convenience function to PersistUnique

## 2.2.4.1

* Documentation updates [#515](https://github.com/yesodweb/persistent/pull/515)

## 2.2.4

* Workaround for side-exiting transformers in `runSqlConn` [#516](https://github.com/yesodweb/persistent/issues/516)

## 2.2.3

* PersistField instance for Natural
* better oracle support in odbc

## 2.2.2

* Add liftSqlPersistMPool function
* support http-api-data for url serialization

## 2.2.1

* Migration failure message with context
* Fix insertKey for composite keys

## 2.2

* Add a `RawSql` instance for `Key`. This allows selecting primary keys using functions like `rawSql`. [#407](https://github.com/yesodweb/persistent/pull/407)
* SqlBackend support for an optimized `insertMany`

## 2.1.6

Important! If persistent-template is not upgraded to 2.1.3.3
you might need to make sure `Int64` is in scope for your model declarations.

* add showMigration function
* explicitly use Int64 for foreign key references

## 2.1.5

Add `dbIdColumnsEsc` to Sql.Utils.
Used in persistent-postgresql 2.1.5.2

## 2.1.4

* Fix getBy with a primary key. #342

## 2.1.3

* Break self-referencing cycles in the entity declarations

## 2.1.2

* Error with `Double`s without a decimal part [#378](https://github.com/yesodweb/persistent/issues/378)
* `runSqlPool` does not perform timeout checks.

## 2.1.1.6

* One extra feature for #939: use `logDebugN` instead

## 2.1.1.5

* Better SQL logging [Yesod issue #939](https://github.com/yesodweb/yesod/issues/939)

## 2.1.1.3

Parse UTCTime in 8601 format [#339](https://github.com/yesodweb/persistent/issues/339)

## 2.1.1.1

Support for monad-control 1.0