Ghost 5.0: Breaking Changes

[ErisDS]

The Ghost team has started working on preparations for 5.0, which will involve several breaking changes. There is no ETA or release date as yet, so please do not ask 😬

This issue serves as a living doc with all the known breaking changes as we decide on them. It is unlikely to be exhaustive until 5.0 actually drops.

---

Known Breaking Changes So Far

Database support changes:

• MySQL 5 is no longer supported in any environment
• SQLite3 is no longer supported in production
• MySQL 8 is supported in all environments & the only supported DB for production.

Note: MariaDB is not an officially supported database for Ghost. It just happened to work given the similarities with MySQL, but we optimize and test for MySQL 5 and 8. As of Ghost 5.0 we are clarifying that official support is purely for MySQL8 in production so that we can double down on DB optimizations. We strongly recommend changing to MySQL8 and a helpful guide can be found here.

API changes:

• Ghost no longer has multiple API versions per install
  • API versions are no longer included in the URL
  • An accept-version header is supported instead (optional, preferred, docs TBC)
• Admin API:
  • /mail has been deleted
  • /email_preview has been renamed to /email_previews
  • /authentication/reset_all_passwords has been renamed to /authentication/global_password_reset and returns a 204 upon success
  • /authentication/passwordreset has been renamed to /authentication/password_reset, and takes and returns a password_reset object
  • DELETE /settings/stripe/connect now returns a 204 upon success
  • POST /settings/members/email now returns a 204 upon success
  • /posts and /pages no longer accept page:(true|false) filter in the query parameters
• Content API:
  • GET /posts and GET /pages no longer return page:(true|false) attribute in the response
• Members
  • members/api/site & members/api/offers are gone, portal talks to the content API
  • all /products/ endpoints are replaced with /tiers/

Theme changes:

The easiest way to check your theme for breaking changes is to run it against 5.x in gscan.

• Card assets will now be included by default, including bookmark and gallery cards
• Many deprecated features have been removed:
  • @blog
  • single authors
  • all legacy product & price helpers @price, @products, @product and @member.product removed in favour of {{tiers}} and {{price}}
  • many smaller changes...

Misc

• Removed support for serving secure requests when config.url is set to http
• Removed support for configuring the server to connect to a socket instead of a port
• Deleting a user will no longer remove their posts but assign them to the site owner instead

---

API Versioning

In Ghost 5.0 there are no longer different API versions in a single install. The URLs for the api are now ghost/api/content and ghost/api/admin. The main reason for this is that for the most part the API is stable with only additions and changes to newer features. Breaking changes are always made in majors.

Instead of including the API version in the URL, you can now indicate the minimum version you expect a request to work with using accept-version: v{major}.{minor}. When this header is received Ghost will respond with a content-version: v{major}.{minor} header indicating the version that responded. In the case that accept-version is behind & a request either cannot be served or has changed significantly, Ghost will send an email to the site's administrators informing them of the problem.

Requests to the old versioned URLs are rewritten internally, as if they were unversioned and the accept-version header was set. These requests will return a deprecation header. We may choose to respond with either 207, 308 or 410 to these requests in future versions.

---

DB Support

Over the coming months we plan to deliver a range of DB optimisations and other improvements leveraging MySQL8 features. As a small team, we're not able to commit to providing optimisation and compatibility fixes across a wide range of databases where knex does not provide interoperability and therefore for 5.0 we are clarifying that we only officially support MySQL8.

If anyone is interested in contributing to the long term maintenance of interoperability with other databases, we'd love to work with you.

---

Please note: This is a record of what is being removed, it is not the right place for feature requests, please put those on the forum as per usual.

[JoshStrobl]

Why is the sqlite3 support being removed?

[naz]

@JoshStrobl it is not being removed. SQLite3 will not be supported in production. To answer your question, it takes a lot of effort to support different database versions. To make Ghost super-fast we need to optimize the codebase to be performant on MySQL. If optimizations breaks parts of SQLite, so be it.

[ErisDS]

Hey all 👋 , I've locked this thread to contributor comments only and updated the original post with an explanation around DB support.

I understand there's a lot of frustration around the clarification that MariaDB is not an officially supported database. As a small team we've always provided a very narrow set of environments that are officially supported to keep our maintenance overhead manageable: Ghost is intended for use with Ubuntu, MySQL, nginx & Node.js LTS.

We're not able to support every flavour of environment without differences being handled correctly in the upstream packages. The way to change what's supported would be to contribute the necessary fixes & improvements - we'd absolutely love to see more contributions around database interoperability in knex.

[ErisDS]

Closing this now as the official documentation has been published https://ghost.org/docs/changes/