Payload CMS Release: 2.28.0

TL;DR

Payload CMS v2.28.0 introduces custom database operations for collections, allowing developers to override default database behaviors. This release also includes important PostgreSQL database fixes for migration exit codes and query handling, along with improved logging for the cloud plugin.

Highlight of the Release

• Custom database operations for collections
• Fixed PostgreSQL migration exit codes
• Improved query handling for hasMany relationships in PostgreSQL
• Enhanced logging for cloud plugin static handler

Migration Guide

Upgrading to v2.28.0

This release doesn't contain breaking changes, making it straightforward to upgrade from v2.27.0.

1. Update your Payload CMS dependency:

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

2. If using PostgreSQL:

   • The fixes for migration exit codes and hasMany query handling will be automatically applied
   • No additional configuration is required

3. If using the cloud plugin:

   • The improved logging for static handlers will be automatically enabled
   • No additional configuration is required

4. To use the new custom database operations feature:

   • This is an opt-in feature that requires explicit configuration
   • See the "New Features" section for implementation details

5. Issue Template Updates:

   • When reporting issues, note that the payload info command now uses a textarea
   • Individual version fields are no longer required/enforced

Upgrade Recommendations

Recommendation: Standard Upgrade

This release is recommended for all Payload CMS users, especially those using PostgreSQL or the cloud plugin.

• PostgreSQL users will benefit from critical fixes to migration exit codes and query handling for hasMany relationships
• Cloud plugin users will gain improved logging capabilities for static handlers
• All developers can take advantage of the new custom database operations feature for collections

The release contains no breaking changes, making it a safe upgrade from v2.27.0. The improvements to PostgreSQL functionality and the addition of custom database operations provide significant value with minimal upgrade risk.

For projects with critical PostgreSQL functionality or those requiring custom database handling, this upgrade should be prioritized.

Bug Fixes

PostgreSQL Database Fixes

1. Fixed Migration Exit Codes (#7873)

   • Resolves issue #7031 for v2
   • Ensures proper exit codes are returned during database migrations
   • Critical for CI/CD pipelines that rely on accurate exit codes

2. Improved Query Handling for hasMany Relationships (#8033)

   • Fixes issue #7671
   • Properly handles queries for hasMany text/number fields in arrays and blocks
   • Ensures consistent query results when working with complex data structures

Cloud Plugin Enhancement

• Better Logging on Static Handler (#7924)
  • Improves logging capabilities for the static handler in the cloud plugin
  • Makes debugging and troubleshooting easier with more detailed logs

Documentation and Template Improvements

• Fixed typo in documentation (modifing → modifying) (#7846)
• Updated incorrect plurality in Italian translations (#7866)
• Changed import in ecommerce template to be type-only to resolve linter errors (#8019)

New Features

Custom Database Operations for Collections

Payload CMS now allows developers to override default database operations for collections. This powerful feature gives you complete control over how your collection interacts with the database.

You can now customize the following operations:

• create
• deleteMany
• deleteOne
• find
• findOne
• updateOne

Example usage:

import { CollectionConfig } from 'payload/types';

export const Collection: CollectionConfig = {
  slug: 'example-collection',
  // Database operations for this collection  
  db: {
    create: () => {},
    deleteMany: () => {},
    deleteOne: () => {},
    find: () => {},
    findOne: () => {},
    updateOne: () => {}
  },
  fields: [
    {
      name: 'someField',
      type: 'text',
    },
  ],
}

This feature enables advanced use cases such as:

• Custom data validation logic
• Integration with external data sources
• Specialized caching strategies
• Custom data transformation during CRUD operations

Security Updates

No specific security fixes were included in this release.

Performance Improvements

While this release doesn't explicitly focus on performance enhancements, several changes contribute to improved system performance:

1. Custom Database Operations

   • The new ability to override default database operations allows developers to implement performance optimizations tailored to their specific use cases
   • Custom implementations can include specialized indexing strategies, caching mechanisms, or optimized query patterns

2. PostgreSQL Query Handling

   • The fix for hasMany text/number fields in arrays and blocks improves query efficiency by ensuring proper handling of complex data structures
   • This prevents potential performance degradation that could occur with incorrect query handling

3. Migration Process Improvements

   • Fixed exit codes for PostgreSQL migrations contribute to more reliable and efficient CI/CD processes
   • Proper error handling prevents unnecessary pipeline reruns and resource consumption

Impact Summary

Payload CMS v2.28.0 delivers a significant enhancement to the database layer by introducing custom database operations for collections. This feature fundamentally changes how developers can interact with the database, providing unprecedented flexibility to override default behaviors for create, read, update, and delete operations.

The PostgreSQL fixes address important issues that could affect system reliability. The migration exit code fix ensures that CI/CD pipelines correctly interpret the success or failure of database migrations, preventing potential deployment issues. The query handling improvements for hasMany relationships ensure consistent and correct data retrieval in complex data structures.

For cloud plugin users, the improved logging on static handlers enhances observability and makes troubleshooting easier, which is particularly valuable in production environments.

Overall, this release balances new capabilities with important fixes, making it a valuable upgrade for most Payload CMS implementations. The custom database operations feature opens up new possibilities for advanced use cases, while the bug fixes ensure more reliable operation, particularly for PostgreSQL users.

Full Release Notes