Ghost Release: 4.38.0

TL;DR

Ghost v4.38.0 introduces several new features and improvements including date-based filters for the members list, new comparison operators for the match helper, and a new tiers helper for themes. The update also includes important bug fixes for the {{access}} property in theme helpers, missing index pages in sitemaps, and improvements to the member page layout. Under the hood, Ghost has switched from the mysql library to mysql2 for better performance and compatibility with MySQL 8, and added support for non-versioned API endpoints in preparation for future major releases.

This release enhances both the admin experience and theme development capabilities while addressing several important bugs that affected site functionality.

Highlight of the Release

• Added date-based filters for members list including 'Created', 'Paid start date', and 'Next billing date'
• Added comparison operators (>, <, >=, <=) to the match helper for more flexible theme logic
• Added new {{tiers}} theme helper for displaying tier information in post contexts
• Switched from mysql to mysql2 library for better performance and MySQL 8 compatibility
• Added support for non-versioned API endpoints in preparation for future major releases
• Fixed incorrect {{access}} property when using get/next-post/prev-post helpers

Migration Guide

API Versioning Changes

Ghost is preparing to drop API versioning in a future major release. This version adds support for non-versioned API endpoints:

• /ghost/api/admin
• /ghost/api/content

If you're developing integrations or custom code that interacts with Ghost's API, you should begin updating your code to use these non-versioned endpoints to ensure compatibility with future Ghost versions.

Database Driver Change

Ghost has switched from the mysql library to mysql2. This should be transparent to most users, but if you have custom code that interacts directly with Ghost's database configuration:

• The system now uses mysql2 but maintains backwards compatibility with configs using "client": "mysql"
• The timezone setting has been updated from UTC to Z for better compatibility
• If you encounter any database connection issues after upgrading, check your database configuration

Theme Development

If you're developing themes:

• You can now use the new comparison operators (>, <, >=, <=) in the match helper
• The new {{tiers}} helper is available behind the multipleProducts flag
• The {{access}} property now works correctly with the get/next-post/prev-post helpers

Upgrade Recommendations

This is a standard feature release with several useful enhancements and bug fixes. We recommend all users upgrade to Ghost 4.38.0, especially if you:

• Manage a large member base and would benefit from improved filtering options
• Use custom themes that rely on the {{access}} property or need more flexible conditional logic
• Have experienced issues with missing index pages in your sitemap
• Need to work with the Media and Files APIs programmatically
• Are developing integrations that will need to work with future Ghost versions

The upgrade process should be straightforward with no breaking changes reported. As always, it's recommended to:

1. Back up your database before upgrading
2. Test the upgrade in a staging environment if possible
3. Check your theme functionality after upgrading, especially if you use custom themes

For those using the managed Ghost(Pro) service, this update will be automatically applied to your site.

Bug Fixes

• Fixed missing index page from sitemaps: Corrected a regression that caused the index page (/) to be missing from sitemaps.xml
• Fixed {{access}} property: Corrected the {{access}} property which was incorrectly returning false for non-public content when using get/next-post/prev-post helpers
• Fixed include option for tiers: Fixed the include option not working properly when fetching tiers via the #get helper
• Fixed empty benefits: Now removing empty benefits before saving tiers
• Fixed non-integer prices: Corrected issues with sending non-integer prices to tiers API
• Fixed members table dates: Corrected members table showing dates in UTC rather than site timezone
• Fixed cache invalidation: Updated to always invalidate cache on tier edit to ensure sites don't see old tier values
• Fixed error handling: Added extra handling for errors when adding foreign key in database migrations

New Features

Enhanced Member Management

• Date-based filters for members list: Added "Created", "Paid start date", and "Next billing date" filters to the members list screen for better member segmentation
• Member's tier name on Portal: Added tier name display on the account home page for logged-in members in Portal
• Last seen tracking: Added last_seen_at updates when members open emails or view pages

Theme Development Improvements

• New comparison operators: Added >, <, >=, and <= operators to the match helper for more flexible theme logic
• New {{tiers}} theme helper: Added behind multipleProducts flag to output a string with list of tiers that have access to specific posts
• Tiers API in Content API: Added /tiers endpoint to Content API so themes can access Tiers via the {{#get}} helper

API Enhancements

• Non-versioned API support: Added support for non-versioned API endpoints (/ghost/api/admin and /ghost/api/content) in preparation for future major releases
• Include option for members browse API: Added include as a valid option for members browse API
• Media and Files APIs: Added to API key allowlist for use with Admin-API SDK
• JWT authentication for non-versioned API: Added support for non-versioned token audience

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

• Switched to mysql2 library: Replaced the mysql library with mysql2 for several benefits:

  • More active maintenance
  • Native support for the default auth plugin on MySQL 8
  • Better performance
  • Enabled decimalNumbers to maintain the same functionality as before

• Database connection improvements: Cleaned up DB connection fallback in migrations commands for better reliability and type safety

• Removed public cache-control header: Removed caching for member site endpoint to prevent issues with Portal preview and ensure changes to tiers and Portal settings display promptly

Impact Summary

Ghost 4.38.0 delivers significant improvements to member management with new date-based filters and last seen tracking, while enhancing theme development capabilities through new comparison operators and a dedicated tiers helper. The release addresses several important bugs, including fixes for the {{access}} property in theme helpers and missing index pages in sitemaps.

Under the hood, Ghost has made important infrastructure improvements by switching to the mysql2 library for better performance and MySQL 8 compatibility, and adding support for non-versioned API endpoints in preparation for future major releases.

For administrators, the improved member filtering and page layout enhancements provide better tools for member management. Developers benefit from more flexible theme logic options and better API access. Content creators will appreciate the improved tier information display and SEO benefits from fixed sitemaps. Members will experience a more personalized Portal experience with their tier name displayed on the account home page.

Overall, this release represents a solid step forward in Ghost's evolution, with thoughtful improvements to both user-facing features and underlying infrastructure.

Full Release Notes