Payload CMS Release: 3.6.0

TL;DR

Payload CMS v3.6.0 introduces several key features including direct database access in migrations, improved job management, and better hydration control in Next.js. This release also fixes numerous UI issues, enhances rich text editor functionality, and improves bulk editing operations. The update focuses on developer experience with better TypeScript support and more consistent behavior across the platform.

Highlight of the Release

• Direct database access in migrations with session and db parameters
• New job management features with payload.jobs.runByID and where filtering
• Improved bulk editing that preserves unedited field values
• Sequential autosave to prevent race conditions
• Next.js 15.1.0 compatibility and hydration warning control

Migration Guide

Accessing Database in Migrations

If you were previously using workarounds to access the database in migrations, you can now use the officially supported approach:

MongoDB:

import { type MigrateUpArgs } from '@payloadcms/db-mongodb'

export async function up({ session, payload, req }: MigrateUpArgs): Promise<void> {
  const posts = await payload.db.collections.posts.collection.find({ session }).toArray()
}

PostgreSQL:

import { type MigrateUpArgs, sql } from '@payloadcms/db-postgres'

export async function up({ db, payload, req }: MigrateUpArgs): Promise<void> {
  const { rows: posts } = await db.execute(sql`SELECT * from posts`)
}

SQLite:

import { type MigrateUpArgs, sql } from '@payloadcms/db-sqlite'

export async function up({ db, payload, req }: MigrateUpArgs): Promise<void> {
  const { rows: posts } = await db.run(sql`SELECT * from posts`)
}

Next.js 15.1.0 Compatibility

If you're using Next.js 15.1.0, this release includes compatibility fixes. No action is required on your part.

Hydration Warnings

If you want to suppress hydration warnings in the admin UI, you can now add:

admin: {
  suppressHydrationWarning: true
}

to your Payload config.

Upgrade Recommendations

This release includes several important bug fixes and new features that improve developer experience and admin UI functionality. It's recommended to upgrade to v3.6.0, especially if you:

1. Work with database migrations and need direct database access
2. Use job queues and need more control over job execution
3. Experience issues with bulk editing in the admin UI
4. Have encountered autosave race conditions
5. Use Next.js 15.1.0 and experienced compatibility issues

The upgrade should be straightforward with minimal risk as there are no breaking changes reported. As always, test thoroughly in a development environment before deploying to production.

Bug Fixes

UI Improvements

• Fixed unwanted data overrides when bulk editing that could reset fields to default values
• Ensured admin.disableListFilter is properly respected despite URL search parameters
• Refreshed column state during HMR and respected admin.disableListColumn despite preferences

Rich Text Editor Fixes

• Fixed field errors and descriptions not being displayed in rich text editors
• Added missing lexical-html export to the lexical-proxy exports

Next.js Compatibility

• Fixed Next.js 15.1.0 compatibility by updating import paths
• Stopped automatic formatting of top-level domains within admin.preview or livePreview.url functions
• Added default ServerProps to Edit and List view action slots

Other Important Fixes

• Ensured autosave only runs sequentially to prevent race conditions
• Fixed forgotPassword expiration time setting
• Upgraded PostgreSQL snapshot during v3 upgrade if needed
• Fixed website template infinite reload bug with 404s in production mode
• Fixed error when passing server-only props in custom field components

New Features

Direct Database Access in Migrations

Now you can directly access the database with the active transaction in migrations using the newly exposed session (MongoDB) and db (PostgreSQL/SQLite) parameters in the up and down functions. This makes it easier to execute raw SQL or perform complex database operations within migrations.

Enhanced Job Management

Two new features improve job management capabilities:

• payload.jobs.runByID: Run a specific job by its ID
• payload.jobs.run with where filtering: Filter jobs to run based on criteria like { where: { 'input.message': { equals: 'secret' } } }

Next.js Hydration Warning Control

Added a new suppressHydrationWarning property to the payload config admin options, allowing developers to control whether React hydration warnings are displayed when server-rendered HTML intentionally differs from client-rendered DOM.

Consolidated Create and Duplicate Operations

The create and duplicate operations have been consolidated for better consistency and code reuse.

Security Updates

No significant security fixes were included in this release.

Performance Improvements

Sequential Autosave

The autosave system has been improved to use a queue-based approach that prevents multiple autosaves from running in parallel. This ensures that only the latest autosave is performed and prevents inconsistent results from parallel fetches.

Better Type Testing

Added types testing with tstyche to ensure type definitions don't break between updates, improving the reliability of TypeScript integrations.

Optimized Database Operations

The exposure of session and db in migrations allows for more optimized database operations by using the active transaction directly, reducing overhead and potential connection issues.

Impact Summary

Payload CMS v3.6.0 delivers significant improvements to developer experience and admin UI functionality. The ability to directly access databases in migrations with transaction support solves a long-standing pain point for developers working with complex data migrations. The enhanced job management features provide more granular control over background tasks.

For content editors, the fixes to bulk editing, autosave, and rich text editor components create a more reliable and consistent editing experience. The sequential autosave implementation prevents potential data inconsistencies that could occur with parallel saves.

System administrators will appreciate the Next.js 15.1.0 compatibility fixes and the ability to upgrade PostgreSQL snapshots during v3 migration.

Overall, this release represents a solid improvement to Payload's core functionality with no breaking changes, making it a recommended upgrade for all users.

Full Release Notes