Ghost Release: 3.31.3

TL;DR

Ghost 3.31.3 is a maintenance release that fixes a critical bug in the Tags API v2 where post counts were not being returned properly. It also includes significant improvements to member import error handling, performance optimizations for large queries, and several dependency updates. This release ensures data consistency and improves the reliability of the platform for content creators and developers.

Highlight of the Release

• Fixed Tags API v2 to properly return post counts when using include=posts.count parameter
• Added robust error handling and retry logic for failed member imports
• Improved query performance for large datasets by skipping unnecessary count queries
• Refactored member importer in preparation for future job-based processing

Migration Guide

No migration steps are required for this release. This is a maintenance release that fixes bugs and improves performance without introducing breaking changes.

Users should update to this version to ensure proper functionality of the Tags API v2 and to benefit from the improved member import reliability and performance optimizations.

Upgrade Recommendations

This release is recommended for all Ghost users, especially those who:

1. Use the Tags API v2 with the include=posts.count parameter
2. Regularly import members into their Ghost installation
3. Work with large datasets where query performance is important

The update is backward compatible and should not cause any disruption to existing functionality. Standard upgrade procedures apply.

Bug Fixes

Tags API v2 Post Count Fix

• Fixed a critical bug where Tags API v2 was ignoring the include=posts.count parameter
• This regression was introduced in a previous update and is now properly resolved
• Added comprehensive regression tests across all Content API versions to prevent similar issues

Member Import Fixes

• Fixed boolean values validations for member uploads
• Removed redundant date handling validation in members importer logic as it's already handled by JSON schema validation
• Improved import_label creation logic to avoid creating unnecessary generic labels when custom labels are provided

New Features

Error Handling for Member Imports

• Added robust error handling for failed member imports with retry logic
• Implemented an iterative one-by-one insert retry approach when bulk operations fail
• Added detailed debug logs to improve debugging experience and performance measurements
• Improved handling for unrecognized errors during imports

Query Performance Improvements

• Skipped separate count query in .findPage() for limit="all" requests, improving performance for large result sets
• Allowed custom and search queries to be used with .findAll() for more flexible querying
• Optimized member count queries using Bookshelf's native counting methods

Security Updates

No specific security fixes were included in this release.

Performance Improvements

Query Optimization

• Eliminated unnecessary count queries when limit="all" is specified, significantly improving performance for large datasets
• Extracted filtering of collections into a separate function for more efficient code reuse
• Optimized member count queries by using Bookshelf's native counting methods instead of raw queries

Member Import Performance

• Refactored model's bulkAdd & bulkDestroy methods to use a centralized 'bulk-operations' module
• Improved error handling with retry logic that maintains performance while ensuring data integrity
• Added debug logs for better performance measurement and optimization

Impact Summary

Ghost 3.31.3 addresses a critical bug in the Tags API v2 that prevented post counts from being returned correctly. This fix ensures data consistency for applications and themes that rely on accurate tag post counts.

The release also significantly improves the reliability of member imports by adding robust error handling, retry logic, and better logging. This makes the import process more resilient against failures and provides better visibility into any issues that may occur.

Performance optimizations for large datasets have been implemented, particularly for queries that fetch all records. By skipping unnecessary count queries and optimizing member count operations, the system will respond more efficiently when working with large amounts of data.

Several dependency updates are included to keep the platform secure and up-to-date. The refactoring of the member importer also lays groundwork for future improvements to the import process through job-based processing.

Full Release Notes