Payload CMS Release: 2.11.2

TL;DR

PayloadCMS v2.11.2 Release

This release introduces custom schema support for PostgreSQL databases and fixes several critical bugs related to database operations, UI components, and API functionality. Key improvements include better handling of localized fields in PostgreSQL, proper error handling in hooks, and fixes for API key management. This update enhances stability and flexibility for both MongoDB and PostgreSQL database adapters.

Highlight of the Release

• Added support for configurable custom schemas in PostgreSQL
• Fixed unique constraints for non-required fields in MongoDB
• Improved handling of nested localized fields in PostgreSQL
• Fixed API key management when disabling keys
• Enhanced error handling in config-level afterError hooks
• Fixed transaction errors from access endpoints
• Improved UI components with proper context providers

Migration Guide

This release doesn't contain breaking changes that require complex migration steps. However, there are a few things to be aware of:

For PostgreSQL Users

If you want to use the new custom schema feature:

1. Ensure your database user has the necessary permissions to create or use the specified schema
2. Update your database configuration to include the schema property:

postgresAdapter({
  pool: {
    connectionString: process.env.DATABASE_URI,
  },
  schema: 'your_schema_name', // Add this line
})

3. If you're migrating existing data to a new schema, you'll need to manually move your data or use PostgreSQL's schema management tools

For MongoDB Users with Unique Fields

The fix for sparse indexing on non-required unique fields will be applied automatically. However, if you've implemented workarounds for this issue, you may want to review and remove them to avoid conflicts.

For API Key Users

If you've been experiencing issues with disabled API keys still being valid, this release fixes that problem. No action is required, but you may want to review your API keys and ensure that any previously disabled keys are properly invalidated.

Upgrade Recommendations

Recommendation Level: Recommended for all users

This release contains important bug fixes and a valuable new feature for PostgreSQL users. We recommend all Payload CMS users upgrade to v2.11.2, especially:

• Users experiencing any of the specific issues addressed in this release
• PostgreSQL users who would benefit from custom schema support
• MongoDB users with unique non-required fields
• Anyone using API keys in their application

How to Upgrade

1. Update your Payload CMS dependency:

npm install [email protected]
# or
yarn add [email protected]
# or
pnpm add [email protected]

2. If you're using the PostgreSQL adapter, update it as well:

npm install @payloadcms/db-postgres@latest
# or
yarn add @payloadcms/db-postgres@latest
# or
pnpm add @payloadcms/db-postgres@latest

3. Test your application thoroughly after upgrading, especially if you rely on the specific features or fixes included in this release.

Bug Fixes

Database Fixes

MongoDB

• Sparse Indexing for Non-Required Fields: Fixed an issue where unique constraints on non-required fields weren't properly implemented as sparse indexes, causing problems when fields were left empty (#5114)

PostgreSQL

• Nested Localized Fields: Fixed an issue where _parentID wasn't being properly set for array nested localized fields, which caused problems with data relationships and lookups (#5117)
• Locale Data Loss: Resolved an issue where using afterRead with fallbackLocale could cause locale data loss

Admin UI Fixes

• Drawer Content Replacement: Fixed a bug where the drawer content was being replaced with the full edit component even when it didn't exist, causing UI rendering issues (#5144)
• EditMany Component Context: Added missing Context Provider in the EditMany component, ensuring proper state management when editing multiple items (#5005)

API and Authentication Fixes

• API Key Management: Fixed an issue where disabling an API Key didn't properly remove the key from the system, leaving it potentially accessible (#5145)
• Error Handling: Improved handling of thrown errors in config-level afterError hooks, preventing unhandled exceptions (#5147)
• Transaction Errors: Fixed transaction errors occurring in access endpoints that could cause operations to fail (#5156)

New Features

PostgreSQL Custom Schema Support

The PostgreSQL database adapter now supports configurable custom schemas. This feature allows you to specify which schema to use for your Payload data, providing more flexibility in database organization and multi-tenant applications.

import { buildConfig } from 'payload/config';
import { postgresAdapter } from '@payloadcms/db-postgres';

export default buildConfig({
  db: postgresAdapter({
    pool: {
      connectionString: process.env.DATABASE_URI,
    },
    // Specify a custom schema
    schema: 'my_custom_schema',
  }),
  // rest of your config
});

This enhancement is particularly valuable for:

• Multi-tenant applications where data separation is important
• Organizations with specific database organization requirements
• Projects that need to integrate with existing PostgreSQL database structures

Security Updates

• API Key Management: Fixed a security vulnerability where disabling an API Key didn't properly remove the key from the system (#5145). This fix ensures that when an API key is disabled, it can no longer be used to authenticate with the system, improving overall security posture.

• Error Handling Improvements: Enhanced error handling in config-level afterError hooks (#5147) helps prevent potential information leakage through unhandled exceptions, which could expose sensitive system details in error messages.

Performance Improvements

• MongoDB Indexing: The implementation of sparse indexes for non-required unique fields improves query performance by creating more efficient indexes that only include documents where the field exists.

• PostgreSQL Schema Organization: The new custom schema support allows for better database organization, which can lead to improved query performance in complex database setups by reducing the scope of table scans.

• Transaction Handling: Fixed transaction errors from access endpoints, which not only improves reliability but also enhances performance by preventing unnecessary transaction retries and failures.

• UI Rendering Optimization: The fix for drawer content replacement ensures that components are only rendered when needed, reducing unnecessary DOM operations and improving UI responsiveness.

Impact Summary

PayloadCMS v2.11.2 delivers significant improvements across both MongoDB and PostgreSQL database adapters, along with important fixes to the admin UI and API functionality.

The standout feature is the addition of custom schema support for PostgreSQL, which provides greater flexibility for database organization and multi-tenant applications. This allows developers to better integrate Payload with existing database structures and organizational requirements.

Several critical bugs have been addressed, including:

• Proper handling of unique constraints for non-required fields in MongoDB
• Fixing parent-child relationships in nested localized fields for PostgreSQL
• Resolving issues with API key management where disabled keys weren't properly invalidated
• Improving error handling in hooks and transaction management

These fixes collectively enhance the stability, security, and reliability of Payload CMS, particularly for applications with complex data structures, localization requirements, or those using API keys for authentication.

The release also includes several UI improvements that enhance the admin experience, particularly when working with drawers and editing multiple items simultaneously.

Overall, this is a solid maintenance release that addresses specific pain points reported by the community while adding valuable new functionality for PostgreSQL users.

Full Release Notes