Database Version Upgrade Policies

Engine Yard stack upgrades often include minor version upgrades to MySQL and PostgreSQL databases. However, if you have a highly sensitive application with critical uptime requirements, you might want to control exactly when even minor version upgrades are applied to your database. You also might need the ability to roll back a database upgrade on a specific environment if you encounter a regression.

Database versions on Engine Yard

This document describes the version upgrade policies for MySQL and PostgreSQL databases running on Engine Yard.

PostgreSQL and MySQL versioning policies on Engine Yard

Note: For general PostgreSQL and MySQL versioning information, see PostgreSQL and MySQL Versioning Policies.

Working out a database versioning policy that fits thousands of customers is tricky business. Engine Yard works hard to balance policies and functionality that addresses the database needs of all our customers, including:

  • Agile, smaller, or new customers who want the latest and greatest to try a great new database feature with their app.
  • Customers, with risk-averse apps, who need to test and plan before implementing a database upgrade.
  • Customers, with limited manpower or seasonal apps, who need to schedule database upgrades at specific times.

We believe that the policies outlined below do a good job of providing flexibility across the spectrum of apps and customer needs:

Major versions of PostgreSQL and MySQL on Engine Yard

Engine Yard links a given major release to an environment's database stack, which can be set when first creating the environment.



If you want to move to a newer (or roll back to an older) major version, there are three options:

  1. Update your environment to the latest stack release.
  2. Stop your app (your web service like Unicorn or Passenger and your background jobs).
  3. Backup your database.
  4. Stop the environment (using the "Terminate" button).
  5. Change the Database Stack and disable the Database Version Lock in the environment’s Edit Environment view (see below).
  6. Reboot the environment (Boot it again).

    Note: If you use an existing snapshot when rebooting, your existing data will not be upgraded or converted. Instead, a new empty database will be set up running the new major version or database type (if you change from PostgreSQL to MySQL or vice versa) next to the old data. You can then restore a backup of the old data or begin with the new empty database.

  • Perform an in-place upgrade and change to the environment's database stack. Contact the Engine Yard Professional Services team to assist in this process.
  • Note: Engine Yard has a general Support policy of not immediately supporting new GA (Generally Available) releases ("point oh" releases) of new major versions of PostgreSQL or MySQL (for example, 9.3.0 or 5.6.0). This is because those are the first releases that really make it out "into the wild" and usually see a new X.Y.1 release within weeks that shore up lots of minor bugs that are discovered once the general public is using the new version.

    Engine Yard adds new database stacks for new major versions of PostgreSQL and/or MySQL when creating a new full tech stack distribution, which happens about once a year. We want to be sure that the new version is fully tested on our platform and that anything that links against the database libraries will also continue to work as expected (that is, a new major version of MySQL may work fine for your application but may break some other software that we need to keep working). This means that it might be months between the time of a GA major release from MySQL or PostgreSQL and when it is supported at Engine Yard.

    Minor versions of PostgreSQL and MySQL on Engine Yard

    Minor version upgrades are generally considered safe to perform on existing installations and will often be included on our weekly stack upgrades. And it is best practice to upgrade the stack regularly for the latest security and product updates.

    However, sometimes regressions can be introduced by a minor database version release's bug fixes that affect all or just some installations. As such, it's important to have the option to prevent these upgrades from being processed for applications that are highly sensitive to uptime requirements as well as to be able to roll back an upgrade on a given installation if it does hit a regression.

    How to prevent minor database version changes

    Note: You must upgrade to the August 27, 2013 (or later) Engine Yard Gentoo 12.11 stack or the August 29, 2013 (or later) Engine Yard Gentoo stack release to activate the database version lock feature in the UI.

    On the New environment or the Edit Environment page, you can select this option:


    • If the option is selected (checked), then stack upgrades on that environment will not include processing any minor database version upgrades included in the general stack upgrades (that is, your database’s version will be locked at whatever it currently is).
    • If the option is not selected, then minor database version upgrades will be processed whenever they are included in the weekly stack release.
      Note: This is the preferred choice.

    How database version policies affect your environments

    Note: You must upgrade to the August 27, 2013 (or later) Engine Yard Gentoo 12.11 stack or the August 29, 2013 (or later) Engine Yard Gentoo stack release to activate the database version lock feature in the UI.

    The default for all new and existing environments is to lock the minor database version (that is, the Prevent minor database version changes option is selected). However, the preferred policy is to allow minor database version changes whenever possible.

    All the following situations check the database version policy setting:

    • New application, when you create the environment.
    • Existing environment, when you upgrade the stack.
    • Existing environment, when you boot based on a snapshot of a terminated database master.
    • Cloned environment, when you boot based on a snapshot of the cloned database master.

    ... if the Prevent minor database version changes option is selected, the minor database version will remain unchanged. Otherwise, the database will be updated to the latest supported minor version.

    Note these special situations:

    • New environment, if you need to run an earlier minor database version (for example, to match another existing environment), contact Engine Yard Support.
    • Existing environment, when you reboot using a new volume - because there is no snapshot to reference, Engine Yard cannot know the previous database master version; the new volume provisions with the latest supported minor version.
    • Database replica (slave) instances always boot with the same database version as the database master.

    Important considerations about database versioning

    Review the following important notes about database versioning on Engine Yard.

    • You must upgrade to the August 27, 2013 (or later) Engine Yard Gentoo 12.11 stack or the August 29, 2013 (or later) Engine Yard Gentoo stack release to activate the database version lock feature in the UI.
    • In order for any new database version to take effect, you must restart your database server. If you need help, contact Engine Yard Support.
    • Engine Yard does not, and sometimes will not, support all versions of a given database platform (for example, the X.Y.0, or first GA of a new major release).
    • Engine Yard does not support installing or running alpha, beta, RC (Release Candidate), or any other type of non-GA database software.
    • Minor database version locking only applies to db_master, db_slave, and single instance environments (that is, those that actually run database servers). All other instance types will always process minor version upgrades included in the environment stack upgrades. This is considered to be safe since neither PostgreSQL nor MySQL introduce changes to their client protocols or libraries in minor version releases.

    Contact Engine Yard Support if you:

    • Need assistance with restarting your database, which requires some down time.
    • Need your new environment to run an earlier minor version (for example, to match another existing environment).
    • Have encountered a regression bug with the minor version you are using in your environment and need to roll back to a previous version.

    The Support team can help you get the database version you need, and you can lock in that version, until you’re ready to upgrade.

    More information

    This table provides other resources related to database versioning.

    For more information about... See...
    Upgrading your environment stack Upgrade an Environment
    When upcoming database upgrades are announced Upcoming Releases
    Where database upgrades are included in stack releases Release Notes
    PostgreSQL and MySQL versioning PostgreSQL and MySQL Versioning Policies

    If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.


    Article is closed for comments.