Maintaining your Amazon Neptune DB Cluster - Amazon Neptune
Version numbersRelease typesEngine version life-spansUpgrade processUpgrading to 1.2.0.0 or above
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Maintaining your Amazon Neptune DB Cluster

Neptune performs maintenance periodically on all the resources it uses, including:

  • Replacing the underlying hardware as necessary. This happens in the background, without your having to take any action, and generally has no affect on your operations.

  • Updating the underlying operating system. Operating system upgrades of the instances in your DB cluster are undertaken to improve performance and security, so you should generally complete them as soon as possible. Typically, the updates take about 10 minutes. Operating system updates don't change the DB engine version or DB instance class of a DB instance.

    It's generally best to update the reader instances in a DB cluster first, and then the writer instance. Updating the readers and the writer at the same time can cause downtime in the event of a failover. Note that DB instances are not automatically backed up before an operating-system update, so be sure to make manual backups before you apply an operating-system update.

  • Updating the Neptune database engine. Neptune regularly releases a variety of engine updates to introduce new features and improvements and to fix bugs.

Engine version numbers

Version numbering before engine release 1.3.0.0

Before November 2019, Neptune only supported one engine version at a time, and engine version numbers all took the form, 1.0.1.0.200<xxx>, where xxx was the patch number. All new engine versions were released as patches to earlier versions.

In November 2019, Neptune started supporting multiple versions, allowing customers better control over their upgrade paths. As a result, engine release numbering changed.

From November 2019 up until engine release 1.3.0.0, engine version numbers have 5 parts. Take version number 1.0.2.0.R2 as an example:

  • The first part was always 1.

  • The second part, 0 in 1.0.2.0.R2), was the database major version number.

  • The third and fourth parts, 2.0 in 1.0.2.0.R2) were both minor version numbers.

  • The fifth part (R2 in 1.0.2.0.R2) was the patch number.

Most updates were patch updates, and the distinction between patches and minor version updates was not always clear.

Version numbering from engine release 1.3.0.0 on

Starting with engine release 1.3.0.0, Neptune changed the way engine updates are numbered and managed.

Engine version numbers now have four parts, each of which corresponds to a type of release, as follows:

    product-version.major-version.minor-version.patch-version

Non-breaking changes of the sort that were previously released as patches are now released as minor versions that you can manage using the AutoMinorVersionUpgrade instance setting.

This means that if you want you can receive a notification every time a new minor version is released, by subscribing to the RDS-EVENT-0156 event (see Subscribing to Neptune event notification).

Patch releases are now reserved for urgent targeted fixes, and are numbered using the last part of the version number (*.*.*.1, *.*.*.2, and so forth).

Different types of engine release in Amazon Neptune

The four types of engine release that correspond to the four parts of an engine version number are as follows:

  • Product version   –   This only changes if the product undergoes sweeping, fundamental changes in functionality or interface. The current Neptune product version is 1.

  • Major version   –   Major versions introduce important new features and breaking changes, and generally have a useful lifespan of at least two years.

  • Minor version   –   Minor versions can contain new features, improvements, and bug fixes but do not contain any breaking changes. You can choose whether or not to have them applied them automatically during the next maintenance window, and you can also choose to be notified whenever one is released.

  • Patch version   –   Patch versions are released only to address urgent bug fixes or critical security updates. They seldom contain breaking changes, and they are automatically applied during the next maintenance window following their release.

Amazon Neptune major version updates

A major version update generally introduces one or more important new features and often contains breaking changes. It usually has a support lifetime of around two years. Neptune major versions are listed in Engine releases, along with the date they were released and their estimated end of life.

Major version updates are entirely optional until the major version that you're using reaches its end of life. If you do choose to upgrade to a new major version, you must install the new version yourself using the Amazon CLI or the Neptune console as described in Major version upgrades.

If the major version that you're using reaches its end of life, however, you'll be notified that you are required to upgrade to a more recent major version. Then, if you don't upgrade within a grace period after the notification, an upgrade to the most recent major version is automatically scheduled to occur during the next maintenance window. See Engine version life-spans for more information.

Amazon Neptune minor version updates

Most Neptune engine updates are minor version updates. They happen quite frequently and do not contain breaking changes.

If you have the AutoMinorVersionUpgrade field set to true in the writer (primary) instance of your DB cluster, minor version updates are applied automatically to all instances in your DB cluster during the next maintenance window after they are released.

If you have the AutoMinorVersionUpgrade field set to false in the writer instance of your DB cluster, they are applied only if you explicitly install them.

Note

Minor version updates are self-contained (they don't depend on previous minor version updates to the same major version), and cumulative (they contain all the features and fixes introduced in previous minor version updates). This means that you can install any given minor version update whether or not you have installed previous ones.

It's easy to keep track of minor-version releases by subscribing to the RDS-EVENT-0156 event (see Subscribing to Neptune event notification). You will then be notified every time a new minor version is released.

Also, whether or not you subscribe to notifications, you can always check to see what updates are pending.

Amazon Neptune patch version updates

In the case of security issues or other serious defects that affect instance reliability, Neptune deploys mandatory patches. They are applied to all instances in your DB cluster during your next maintenance window without any intervention on your part.

A patch release is only deployed when the risks of not deploying it outweigh any risks and downtime associated with deploying it. Patch releases happen infrequently (typically once every few months) and seldom require more than a fraction of your maintenance window to apply.

Planning for Amazon Neptune major engine version life-span

Neptune engine versions almost always reach their end of life at the end of a calendar quarter. Exceptions occur only when important security or availability issues arise.

When an engine version reaches its end of life, you will be required to upgrade your Neptune database to a newer version.

In general, Neptune engine versions continue to be available as follows:

  • Minor engine versions: Minor engine versions remain available for at least 6 months following their release.

  • Major engine versions: Major engine versions remain available for at least 12 months following their release.

At least 3 months before an engine version reaches its end of life, Amazon will send an automated email notification to the email address associated with your Amazon account and post the same message to your Amazon Health Dashboard. This will give you time to plan and prepare to upgrade.

When an engine version reaches its end of life, you will no longer be able to create new clusters or instances using that version, nor will autoscaling be able to create instances using that version.

An engine version that actually reaches its end of life will automatically be upgraded during a maintenance window. The message sent to you 3 months before the engine version's end of life will contain details about what this automatic update would involve, including the version to which you would be automatically upgraded, the impact on your DB clusters, and actions that we recommend.

Important

You are responsible for keeping your database engine versions current. Amazon urges all customers to upgrade their databases to the latest engine version in order to benefit from the most current security, privacy, and availability safeguards. If you operate your database on an unsupported engine or software past the deprecation date ("Legacy Engine"), you face a greater likelihood of security, privacy, and operational risks, including downtime events.

Operation of your database on any engine is subject to the Agreement governing your use of the Amazon Services. Legacy Engines are not Generally Available. Amazon no longer provides support for the Legacy Engine, and Amazon may place limits on the access to or use of any Legacy Engine at any time, if Amazon determines the Legacy Engine poses a security or liability risk, or a risk of harm, to the Services, Amazon, its Affiliates, or any third party. Your decision to continue running Your Content in a Legacy Engine could result in Your Content becoming unavailable, corrupted, or unrecoverable. Databases running on a Legacy Engine are subject to Service Level Agreement (SLA) Exceptions.

DATABASES AND RELATED SOFTWARE RUNNING ON A LEGACY ENGINE CONTAIN BUGS, ERRORS, DEFECTS, AND/OR HARMFUL COMPONENTS. ACCORDINGLY, AND NOTWITHSTANDING ANYTHING TO THE CONTRARY IN THE AGREEMENT OR THE SERVICE TERMS, Amazon IS PROVIDING THE LEGACY ENGINE "AS IS."

Installing updates to your Neptune engine manually

Installing a major version engine upgrade

Major engine releases must always be installed manually. To minimize downtime and provide for plenty of time for testing and validation, the best way to install a new major version is generally to use the Neptune Blue-Green deployment solution.

In some cases you can also use the Amazon CloudFormation template with which you created your DB cluster to install a major version upgrade (see Using a Amazon CloudFormation template to update the engine version of your Neptune DB Cluster).

If you want to install a major version update immediately, you can use a CLI command like the following:

aws neptune modify-db-cluster \
  --db-cluster-identifier (identifier for your neptune cluster) \
  --engine neptune \
  --engine-version (the new engine version) \
  --apply-immediately

Be sure to specify the engine version to which you want to upgrade. If you don't, your engine may be upgraded to a version that is not the most recent one or the one you expect.

Instead of --apply-immediately, you can specify --no-apply-immediately.

If your cluster uses a custom cluster parameter group, be sure to specify using this paramater:

  --db-cluster-parameter-group-name (name of the custom DB cluster parameter group)

Similarly, if any instances in the cluster use a custom DB parameter group, be sure to specify it using this parameter:

  ---db-instance-parameter-group-name (name of the custom instance parameter group)

Installing a minor version engine upgrade using the Amazon Web Services Management Console

To perform a minor version upgrade using the Neptune console

  1. Sign in to the Amazon Management Console, and open the Amazon Neptune console at https://console.aws.amazon.com/neptune/home.

  2. In the navigation pane, choose Databases, and then choose the DB cluster that you want to modify.

  3. Choose Modify.

  4. Under Instance specifications, choose the new version to which you want to upgrade.

  5. Choose Next.

  6. If you want to apply the changes immediately, choose Apply immediately.

  7. Choose Submit to update your DB cluster.

Installing a minor version engine upgrade using the Amazon CLI

You can use a command like the following to perform a minor version upgrade without waiting for the next maintenance window:

aws neptune modify-db-cluster \
  --db-cluster-identifier (your-neptune-cluster) \
  --engine-version (new-engine-version) \
  --apply-immediately

If you are manually upgrading using the Amazon CLI, be sure to include the engine version to which you want to upgrade. If you do not, your engine may be upgraded to a version that is not the most recent one or the one you expect.

Upgrading to engine version 1.2.0.0 or above from a version earlier than 1.2.0.0

Engine release 1.2.0.0 introduced several significant changes that can make upgrading from an earlier version more complicated than usual:

  • Engine release 1.2.0.0 introduced a new format for custom parameter groups and custom cluster parameter groups. As a result, if you are upgrading from an engine version earlier than 1.2.0.0 to engine version 1.2.0.0 or above, you must re-create all your existing custom parameter groups and custom cluster parameter groups using parameter group family neptune1.2. Earlier releases used parameter group family neptune1, and those parameter groups won't work with release 1.2.0.0 and above. See Amazon Neptune parameter groups for more information.

  • Engine release 1.2.0.0 also introduced a new format for undo logs. As a result, any undo logs created by an earlier engine version must be purged and the UndoLogsListSize CloudWatch metric must fall to zero before any upgrade from a version earlier than 1.2.0.0 can get started. If there are too many undo log records (200,000 or more) when you try to start an update, the upgrade attempt may time out while waiting for purging of the undo logs to complete.

    You can speed up the purge rate by upgrading the cluster's writer instance, which is where the purging occurs. Doing that before trying to upgrade can bring down the number of undo logs before you start. Increasing the size of the writer to a 24XL instance type can increase your purge rate to more than a million records per hour.

    If the UndoLogsListSize CloudWatch metric is extremely large, opening a support case may help you explore additional strategies for bringing it down.

  • Finally, there was a breaking change in release 1.2.0.0 affecting earlier code that used the Bolt protocol with IAM authentication. Starting with release 1.2.0.0, Bolt needs a resource path for IAM signing. In Java, setting the resource path might look like this: request.setResourcePath("/openCypher"));. In other languages, the /openCypher can be appended to the endpoint URI. See Using the Bolt protocol for examples.