feat(db-sqlite): add WAL mode support by r1tsuu · Pull Request #15278 · payloadcms/payload

r1tsuu · 2026-01-20T15:33:05Z

Adds support for WAL mode.
Fixes #9290

import { sqliteAdapter } from '@payloadcms/db-sqlite'
export default buildConfig({
  // Your config goes here
  collections: [
    // Collections go here
  ],
  // Configure the SQLite adapter here
  db: sqliteAdapter({
    wal: true, // Enable WAL mode with default settings,
    wal: { synchronous: 'NORMAL' }, // with configurable settings
    client: {
      url: process.env.DATABASE_URL,
    },
  }),
})

Settings for the wal option:

Setting	Description	Default
`journalSizeLimit`	Max size of the WAL file before checkpointing to the main DB.	`67108864` (64MB)
`synchronous`	WAL sync mode: `EXTRA`, `FULL`, `NORMAL`, `OFF`. Controls balance of performance vs. data safety.	`'FULL'`

github-actions · 2026-01-20T15:40:24Z

📦 esbuild Bundle Analysis for payload

This analysis was generated by esbuild-bundle-analyzer. 🤖

Meta File	Out File	Size (raw)	Note
packages/next/meta_index.json	esbuild/index.js	945.32 KB	🆕 Added
packages/payload/meta_index.json	esbuild/index.js	1.31 MB	🆕 Added
packages/payload/meta_shared.json	esbuild/exports/shared.js	168.42 KB	🆕 Added
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	281.40 KB	🆕 Added
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.17 MB	🆕 Added
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	16.32 KB	🆕 Added

Largest paths

These visualization shows top 20 largest paths in the bundle.

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████████▋ }}}$ 82.5%, 776.25 KB
dist/views/Version	${{\color{Goldenrod}{ █▎ }}}$ 5.4%, 50.45 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 16.48 KB
dist/views/Document	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 16.00 KB
dist/views/List	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 11.27 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 9.03 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 6.16 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.08 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 5.53 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 5.46 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.81 KB
dist/views/Login	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.41 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 3.09 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.3%, 2.91 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.3%, 2.81 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.3%, 2.63 KB
dist/views/BrowseByFolder	${{\color{Goldenrod}{ }}}$ 0.3%, 2.56 KB
dist/views/CollectionFolders	${{\color{Goldenrod}{ }}}$ 0.3%, 2.44 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 2.40 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.2%, 1.94 KB
(other)	${{\color{Goldenrod}{ ████▍ }}}$ 17.5%, 164.39 KB

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████▉ }}}$ 67.9%, 887.58 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.3%, 43.58 KB
dist/collections/operations	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 38.51 KB
dist/versions/migrations	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 18.50 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.46 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.92 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.84 KB
dist/queues/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.80 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 12.04 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.54 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.61 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 8.35 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.74 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.69 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.50 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.83 KB
dist/collections/endpoints	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.21 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ }}}$ 0.4%, 5.58 KB
dist/auth/strategies	${{\color{Goldenrod}{ }}}$ 0.4%, 5.49 KB
dist/auth/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 5.42 KB
(other)	${{\color{Goldenrod}{ ████████ }}}$ 32.1%, 419.63 KB

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▎ }}}$ 77.1%, 127.13 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▌ }}}$ 6.4%, 10.54 KB
dist/config/orderable	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 3.13 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 2.54 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 1.42 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.28 KB
dist/utilities/getVersionsConfig.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 1.04 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 943 B
dist/folders/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 916 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.4%, 651 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.3%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.3%, 561 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 525 B
dist/fields/getFieldPaths.js	${{\color{Goldenrod}{ }}}$ 0.3%, 485 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.3%, 423 B
dist/utilities/deepMerge.js	${{\color{Goldenrod}{ }}}$ 0.3%, 413 B
(other)	${{\color{Goldenrod}{ █████▋ }}}$ 22.9%, 37.68 KB

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
dist/features/blocks	${{\color{Goldenrod}{ ███▏ }}}$ 12.6%, 35.14 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▉ }}}$ 11.5%, 32.00 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▏ }}}$ 8.8%, 24.36 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██▏ }}}$ 8.5%, 23.70 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▋ }}}$ 6.8%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▋ }}}$ 6.5%, 18.11 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▌ }}}$ 6.4%, 17.75 KB
dist/features/upload	${{\color{Goldenrod}{ █▎ }}}$ 5.0%, 13.77 KB
dist/features/textState	${{\color{Goldenrod}{ █ }}}$ 4.0%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 9.03 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▊ }}}$ 3.0%, 8.22 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 7.39 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 7.15 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.05 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.08 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.00 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 3.46 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.17 KB
dist/lexical/theme	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.62 KB
dist/features/indent	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.50 KB
(other)	${{\color{Goldenrod}{ █████████████████████▊ }}}$ 87.4%, 243.00 KB

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████▍ }}}$ 49.7%, 578.70 KB
dist/elements/FolderView	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 29.29 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 27.61 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 16.96 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 16.68 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.79 KB
dist/elements/Table	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.74 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.26 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 14.20 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 13.70 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 10.33 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 9.05 KB
dist/providers/Folders	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.45 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/elements/ListHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.90 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.81 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.73 KB
dist/views/CollectionFolder	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.38 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.34 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.99 KB
(other)	${{\color{Goldenrod}{ ████████████▌ }}}$ 50.3%, 584.54 KB

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████ }}}$ 20.0%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▎ }}}$ 17.0%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▍ }}}$ 9.8%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▏ }}}$ 8.5%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 862 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▎ }}}$ 5.2%, 814 B
dist/utilities/getGlobalData.js	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 762 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▏ }}}$ 4.8%, 756 B
dist/elements/Translation	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 440 B
dist/utilities/traverseForLocalizedFields.js	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 399 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 339 B
dist/utilities/getVisibleEntities.js	${{\color{Goldenrod}{ ▌ }}}$ 2.1%, 329 B
dist/utilities/getNavGroups.js	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 301 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 180 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 159 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 152 B
dist/forms/Form	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 146 B
(other)	${{\color{Goldenrod}{ ████████████████████ }}}$ 80.0%, 12.51 KB

Details

Next to the size is how much the size has increased or decreased compared with the base branch of this PR.

‼️: Size increased by 20% or more. Special attention should be given to this.
⚠️: Size increased in acceptable range (lower than 20%).
✅: No change or even downsized.
🗑️: The out file is deleted: not found in base branch.
🆕: The out file is newly found: will be added to base branch.

VlatkoGoljevacki · 2026-01-21T09:35:10Z

@r1tsuu Thanks for this, I was just looking at Payload SQLite for the functionality.

Can I suggest you also add a busy_timeout config together with this?

A few additional pragmas would make this fully production-ready:

Pragma	Suggested Option	Default	Why
`busy_timeout`	`busyTimeout: 5000`	0	Without this, concurrent writes fail immediately with "database is locked" instead of waiting.
`cache_size`	`cacheSize: -65536`	-2000 (2MB)	64MB cache improves read performance. Negative value = KB.
`mmap_size`	`mmapSize: 134217728`	0	128MB memory-mapped I/O for faster reads via OS page cache.
`temp_store`	`tempStore: 'MEMORY'`	'DEFAULT'	Keep temp tables in RAM instead of disk.
`auto_vacuum`	`autoVacuum: 'INCREMENTAL'`	'NONE'	Auto-reclaim space from deleted rows without full VACUUM.

busyTimeout is the most important - it's what prevents "database is locked" errors under any concurrent load. The others are performance optimizations.

Example config with all options:

db: sqliteAdapter({                                                                                                                                                                               
  client: { url: process.env.DATABASE_URI },                                                                                                                                                      
  wal: true,                                                                                                                                                                                      
  synchronous: 'NORMAL',                                                                                                                                                                          
  journalSizeLimit: 67108864,                                                                                                                                                                     
  busyTimeout: 5000,                                                                                                                                                                              
  cacheSize: -65536,                                                                                                                                                                              
  mmapSize: 134217728,                                                                                                                                                                            
  tempStore: 'MEMORY',                                                                                                                                                                            
  autoVacuum: 'INCREMENTAL',                                                                                                                                                                      
})

One question: are session pragmas (synchronous, busy_timeout, etc.) set once on client creation, or on each connection?

This reverts commit 28789f1.

r1tsuu · 2026-01-22T15:39:25Z

@VlatkoGoljevacki I opened a separate PR for busy timeout since it's not related to WAL #15317

VlatkoGoljevacki · 2026-01-23T14:08:50Z

@VlatkoGoljevacki I opened a separate PR for busy timeout since it's not related to WAL #15317

Thanks man, great job!

github-actions · 2026-01-23T20:51:05Z

🚀 This is included in version v3.73.0

feat(db-sqlite): add WAL mode support

1c3ca9e

github-actions bot added the created-by: Payload team label Jan 20, 2026

r1tsuu requested a review from DanRibbens January 21, 2026 01:03

add busy timeout

28789f1

r1tsuu changed the title ~~feat(db-sqlite): add WAL mode support~~ feat(db-sqlite): add WAL mode support and busyTimeout option Jan 22, 2026

Revert "add busy timeout"

f46b50a

This reverts commit 28789f1.

DanRibbens changed the title ~~feat(db-sqlite): add WAL mode support and busyTimeout option~~ feat(db-sqlite): add WAL mode support Jan 22, 2026

DanRibbens approved these changes Jan 22, 2026

View reviewed changes

r1tsuu merged commit 3357aa6 into main Jan 22, 2026
198 of 200 checks passed

r1tsuu deleted the feat/WAL-mode-SQLite branch January 22, 2026 15:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(db-sqlite): add WAL mode support#15278

feat(db-sqlite): add WAL mode support#15278
r1tsuu merged 3 commits intomainfrom
feat/WAL-mode-SQLite

r1tsuu commented Jan 20, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 20, 2026 •

edited

Loading

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Uh oh!

VlatkoGoljevacki commented Jan 21, 2026 •

edited

Loading

Uh oh!

Uh oh!

r1tsuu commented Jan 22, 2026

Uh oh!

VlatkoGoljevacki commented Jan 23, 2026

Uh oh!

github-actions bot commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

r1tsuu commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 esbuild Bundle Analysis for payload

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Uh oh!

VlatkoGoljevacki commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

r1tsuu commented Jan 22, 2026

Uh oh!

VlatkoGoljevacki commented Jan 23, 2026

Uh oh!

github-actions bot commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

r1tsuu commented Jan 20, 2026 •

edited

Loading

github-actions bot commented Jan 20, 2026 •

edited

Loading

VlatkoGoljevacki commented Jan 21, 2026 •

edited

Loading