Ghost Release: 1.21.3

TL;DR

Ghost 1.21.3 delivers significant performance improvements to the importer, making it up to 30x faster while using less memory. This release also includes a major refactoring of the model layer to standardize the usage of include and withRelated parameters, along with improvements to the validation layer and password security. These changes provide a more stable foundation for future features while maintaining backward compatibility.

Highlight of the Release

• Dramatically improved importer performance - up to 30x faster with lower memory usage
• Standardized usage of include and withRelated parameters across the codebase
• Enhanced validation layer to catch errors earlier and provide better feedback
• Added dedicated password security library for better password handling
• Improved unit testing capabilities with knex mock

Migration Guide

API vs Model Layer Parameter Usage

If you're a developer working directly with Ghost's codebase, note the standardized approach to parameters:

When accessing the API layer:

• Use include parameter (comma-separated string format)
• Example: api.posts.browse({include: 'author,tags'})
• Also applies to theme API parameters: {{get ... include="author"}}

When accessing the model layer:

• Use withRelated parameter (array format)
• Example: models.Post.findPage({withRelated: ['tags']})

The convertOptions utility now properly transforms between these formats as needed.

No database migrations or configuration changes are required for this update.

Upgrade Recommendations

This is a minor release with performance improvements and bug fixes. We recommend all Ghost users upgrade to version 1.21.3, especially if you:

1. Regularly import content into your Ghost site
2. Have experienced memory issues during large imports
3. Have encountered validation errors when creating or updating users

The upgrade process follows the standard Ghost update procedure and should be straightforward with no breaking changes.

For developers working with the Ghost codebase directly, please review the migration guide regarding the standardized usage of include and withRelated parameters.

Bug Fixes

Validation Layer Fixes

• Fixed issue where adding a user without an email would result in a database error instead of a validation error
• Corrected validation behavior to properly catch null values in required fields
• Fixed broken import test where posts without a status would error instead of using the default value
• Removed redundant user model onValidate implementation that's no longer needed with the refactored validation approach

Model Layer Fixes

• Removed incorrect usage of isNew in the model layer (doesn't work with Ghost's non-auto-increment IDs)
• Extended knex mock to properly handle cases where no where clause is present
• Defined belongsToMany foreign keys for tags in the model layer to prevent future relation fetching issues
• Fixed nested tags handling in the importer

New Features

Improved Importer Performance

The Ghost importer has been significantly optimized, resulting in dramatic performance improvements:

• Import speed is up to 30x faster (e.g., 17MB import reduced from ~45 seconds to ~1.5 seconds)
• Much lower and more stable memory usage
• Can now handle larger imports (40MB imports that previously timed out now complete in 1.6 seconds)

New Password Security Library

• Added a dedicated lib.security.password library
• Centralizes password hashing and comparison functionality
• Includes unit tests for the new functionality
• Note: Password hashing takes approximately 100ms

Enhanced Testing Tools

• Added mock-knex as a development dependency for better unit testing
• Unit tests are now significantly faster compared to model integration tests (~70ms vs ~190ms)
• The mock can serve data generator test data by default or custom data as needed

Security Updates

Password Handling Improvements

• Moved password hashing and comparison to a dedicated security library (lib/security/password)
• Centralized password security functions for better maintainability and security
• Added unit tests to verify password security functionality

No critical security vulnerabilities were addressed in this release.

Performance Improvements

Importer Performance Boost

• Changed behavior to update user references before import rather than after
• Reduced import time for a 17MB file from ~45 seconds to ~1.5 seconds
• Successfully processes 40MB imports in 1.6 seconds (previously timed out)
• Significantly reduced memory usage during imports

Faster Unit Tests

• Unit tests now run approximately 2.7x faster than model integration tests
• Comparison shows unit tests taking ~70ms vs integration tests taking ~190ms for the same assertions

Impact Summary

Ghost 1.21.3 delivers substantial performance improvements to the content importer, making it up to 30x faster while using less memory. This is particularly valuable for sites that regularly import large amounts of content.

The release also includes significant refactoring of the model layer to standardize parameter usage (include vs withRelated), enhancing code consistency and maintainability. The validation layer has been improved to catch errors earlier and provide better feedback, particularly for user creation and updates.

For developers, the addition of a dedicated password security library and improved testing tools will make custom development more robust. The standardization of parameter usage between API and model layers provides clearer guidance for extending Ghost functionality.

Overall, this release focuses on performance, stability, and developer experience rather than introducing new user-facing features. The changes lay groundwork for future enhancements while providing immediate benefits for content importing workflows.

Full Release Notes