Backend for the persistent library using sqlite3.

Version on this page:
LTS Haskell 22.30:
Stackage Nightly 2024-07-21:
Latest on Hackage:

See all snapshots persistent-sqlite appears in

MIT licensed and maintained by Michael Snoyman
This version can be pinned in stack with:persistent-sqlite-,5155

Module documentation for

This package includes a thin sqlite3 wrapper based on the direct-sqlite package, as well as the entire C library, so there are no system dependencies.


Changelog for persistent-sqlite

  • #1459
    • Make use of CautiousMigration type alias for clarity.

  • #1341
    • Add SqlBackendHooks to allow for instrumentation of queries.
  • #1327
    • Update backend to support new StatementCache interface

  • aeson-2.0 support #1351

  • Somehow failed to properly release the safe-to-remove changes.

  • #1225
    • Support persistent-2.13 changes for SqlBackend being made internal.

  • Decomposed HaskellName into ConstraintNameHS, EntityNameHS, FieldNameHS. Decomposed DBName into ConstraintNameDB, EntityNameDB, FieldNameDB respectively. #1174

  • Add checkForeignKeys operation to verify no foreign key constraints are violated by the database contents.
  • Fix the migration for primary keys that was broken in #1184

  • Foreign Key improvements [#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
  • #1060
    • The QuasiQuoter now supports OnDelete and OnUpdate cascade options.
  • #1131
    • Provide exists function as required by PersistQueryRead type class.
  • Remove unnecessary deriving of Typeable #1114
  • #1134
    • Update the SQLite amalgamation to 3.33.0

  • Move template haskell splices to be correct (and GHC 8.10 compatible) #1034

  • Missing includes and install-includes cabal fields added, to allow packages depending on persistent-sqlite access to the header files.


  • Bump SQLite amalgamation to version 3.30.1 #991
  • Add createRawSqlitePoolFromInfo, createRawSqlitePoolFromInfo_, withRawSqlitePoolInfo, and withRawSqlitePoolInfo_ to match the existing pool functions for regular SqlBackend. #983

  • Compatibility with latest persistent-template for test suite #1002

  • a fix for template-haskell 2.16, GHC 8.10 alpha #993 @simonmichael


  • Foreign keys table constraints are correctly generated #945 @kderme


  • Fix bug with 2.10.3 and 2.10.2 that caused the RawSqlite loop. #934 @merijn


  • Unique constraints are correctly generated. #922 @kderme


  • Add a new RawSqlite type and withRawSqliteConnInfo function that allow access to the underlying Sqlite Connection type. #772
  • Expose the internals of Connection in an Internal module, allowing the user to call SQLite functions via the C FFI. #772
  • Add a flag for SQLITE_STAT4 and enable it by default, allowing for better query optimisation when using ANALYZE. This breaks the query planner stability guarantee, but the required flag for that isn’t enabled or exposed by persistent. Only affects the vendored SQLite library, has no effect when using system SQLite.
  • Add support for migrating entities with composite primary keys. Fixes #669
  • Fix a bug when using the Filter datatype directly. See #915 for more details.


  • Add support for reading text values with null characters from the database. Fixes #921


  • Updated for persistent-2.10.0 compatibility.


  • Add retry-on-busy support, automatically retrying when sqlite returns a busy error on enabling WAL mode, and providing helper retryOnBusy and waitForDatabase identifiers.


  • Add enableExtendedResultCodes and disableExtendedResultCodes functions



  • Added support for SQL isolation levels to via SqlBackend. [#812] SQLite technically only supports Serializable.
  • Update the vendored SQLite C library from 3.22.0 to 3.25.2. See the SQLite changelog for details.
  • Fix 832: repsertMany now matches mapM_ (uncurry repsert) and is atomic.


  • Add the extraPragmas setting

  • Add flag to enable full-text search extensions (enabled by default)
  • Add flag to enable URI filename support (enabled by default)
  • Add flag to enable using usleep (enabled by default)
    • Enabling usleep allows sqlite to use a finer granularity when sleeping (reduces time between locks)
  • Add flag to enable json1 extension (enabled by default)


  • Updated SqlBackend definition to set connPutManySql. #770


  • Switch from MonadBaseControl to MonadUnliftIO


  • Adds a new function stepConn, which uses an additional parameter to give more detailed error messages #750
  • Restores the previous function signature of step, which was accidentally changed in

  • This release accidentally broke API, and is deprecated on Hackage.
  • Provide more detailed error messages when using the step function #730

  • Fix migration to avoid creating foreign-key constraints in temporary tables #736


  • Add ‘use-pkgconfig’ flag to use pkg-config to find system SQLite library.


  • Turned on foreign key constraints #646
  • Added new SqliteConnectionInfo-based API


  • Added functions to monitor (status) and control (softHeapLimit) process-wide SQLite memory usage.

  • Ensure connection is closed if wrapConnectionWal fails


Compatibility for backend-specific upsert functionality. A lucky contributor could try to add upsert to the sqlite backend now. It would definitely be tricky though because sqlite does not really have this feature.


  • changes for read/write typeclass split


  • Upgrade to SQLite 3.12.1 #551


  • Upgrade to SQLite #444


Update to persistent 2.2

  • Add missing source files #382


  • Add log support to persistent-sqlite #381


  • Added a Show instance for SqliteConf.
  • Use SqliteException instead of calling fail #364


  • Turn on write-ahead log #363
    • Prepending WAL=off to your connection string will recover the previous behavior.

Fix rendering of UTCTime to match SQLite requirements (see issue #328).


Provide a FromJSON instance for SqliteConf.