# 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`, 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-releases-1.3.0.0.md), 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](engine-releases-1.3.0.0.md), 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`](engine-maintenance-management.md#using-amvu) 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-lists.md#RDS-EVENT-0156) event (see [Subscribing to Neptune event notification](events-subscribing.md)).
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) – Major versions introduce important new features and breaking changes, and generally have a useful lifespan of at least two years.
+ [**Minor version**](#minor-versions) – 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-version-updates) – 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](engine-releases.md), 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 AWS CLI or the Neptune console as described in [Major version upgrades](engine-updates-manually.md).
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](engine-updates-eol-planning.md) 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`](engine-maintenance-management.md#using-amvu) 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`](engine-maintenance-management.md#using-amvu) field set to `false` in the writer instance of your DB cluster, they are applied only if you [explicitly install them](engine-updates-manually.md).
**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-lists.md#RDS-EVENT-0156) event (see [Subscribing to Neptune event notification](events-subscribing.md)). 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](engine-maintenance-management.md#check-pending-updates).
## 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, AWS will send an automated email notification to the email address associated with your AWS account and post the same message to your [AWS Health Dashboard](https://docs.aws.amazon.com/health/latest/ug/aws-health-dashboard-status.html). 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. AWS 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 AWS Services. Legacy Engines are not Generally Available. AWS no longer provides support for the Legacy Engine, and AWS may place limits on the access to or use of any Legacy Engine at any time, if AWS determines the Legacy Engine poses a security or liability risk, or a risk of harm, to the Services, AWS, 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, AWS IS PROVIDING THE LEGACY ENGINE "AS IS."
# Managing engine updates to your Neptune DB cluster
**Note**
Updates are applied to all instances in a DB cluster simultaneously. An update requires a database restart on those instances, so you experience downtime ranging from 20 or 30 seconds to several minutes, after which you can resume using the DB cluster. On rare occasions a Multi-AZ failover might be required for a maintenance update on an instance to complete.
For major version upgrades that can take longer to apply, you can use a [blue-green deployment strategy](neptune-BG-deployments.md) to minimize downtime.
## Determining which engine version you are currently using
You can use the AWS CLI [`get-engine-status`](access-graph-status.md) command to check which engine release version your DB cluster is currently using:
```
aws neptunedata get-engine-status
```
The [JSON output](access-graph-status.md#access-graph-status-sample-output) includes a `"dbEngineVersion"` field like this:
```
"dbEngineVersion": "1.3.0.0",
```
## Check to see what updates are pending and available
You can check pending updates to your DB cluster using the Neptune console. Select **Databases** in the left column and then select your DB cluster in the databases pane. Pending updates are listed in the **Maintenance** column. If you select **Actions** and then **Maintenance**, you have three choices about what to do:
+ Upgrade now.
+ Upgrade at next window.
+ Defer upgrade.
You can list pending engine updates using the AWS CLI as follows:
```
aws neptune describe-pending-maintenance-actions \
--resource-identifier (ARN of your DB cluster)
--region (your region) \
--engine neptune
```
You can also list available engine updates using the AWS CLI as follows:
```
aws neptune describe-db-engine-versions \
--region (your region) \
--engine neptune
```
The list of available engine releases includes only those releases that have a version number higher than the current one and for which an upgrade path is defined.
## Always test before you upgrade
When a new major or minor Neptune engine version is released, always test your Neptune applications on it first before upgrading to it. A minor upgrade could introduce new features or behavior that would affect your code even without any breaking change.
Start by comparing the release notes pages from your current version to those of the targeted version to see if there will be changes in query language versions or other breaking changes.
The best way to test a new version before upgrading your production DB cluster is to use the [Neptune Blue-Green deployment solution](neptune-BG-deployments.md). That way you can run applications and queries on the new version without affecting your production DB cluster.
## Always create a manual snapshot before you upgrade
Before performing an upgrade, we strongly recommend that you always create a manual snapshot of your DB cluster. Having an automatic snapshot only offers short-term protection, whereas a manual snapshot remains available until you explicitly delete it.
In certain cases Neptune creates a manual snapshot for you as a part of the upgrade process, but you should not rely on this, and should create your own manual snapshot in any case.
When you are certain that you won't need to revert your DB cluster to its pre-upgrade state, you can explicitly delete the manual snapshot that you created yourself, as well as the manual snapshot that Neptune might have created. If Neptune creates a manual snapshot, it will have a name that begins with `preupgrade`, followed by the name of your DB cluster, the source engine version, the target engine version, and the date.
## Neptune Maintenance Window
The weekly maintenance window is a 30-minute period during which scheduled engine updates and other system changes are applied. Most maintenance events complete during the 30-minute window, although larger maintenance events might sometimes longer to complete.
Every DB cluster has a weekly 30-minute maintenance window. If you don't specify a preferred time for it when you create the DB cluster, Neptune randomly picks a day of the week and then randomly assigns a 30-minute period within it from an 8-hour block of time that varies with the region.
Here, for example, are the 8-hour time blocks for maintence windows used in several AWS regions:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/neptune/latest/userguide/engine-maintenance-management.html)
The maintenance window determines when pending operations start, and most maintenance operations complete within the window, but larger maintenance tasks can continue beyond the window's end time.
### Moving your DB cluster maintenance window
Ideally, the your maintenance window should fall at a time when you cluster is at its lowest usage. If that isn't true of your current window, you can move it to a better time, like this:
**To change your DB cluster maintenance window**
1. Sign in to the AWS Management Console, and open the Amazon Neptune console at [https://console.aws.amazon.com/neptune/home](https://console.aws.amazon.com/neptune/home).
1. In the navigation pane, choose **databases**.
1. Choose the DB cluster for which you want to change the maintenance window.
1. Choose **Modify**.
1. Choose **Show more** at the bottom of the **Modify cluster** page.
1. In the **Preferred maintenance window** section, set the day, time and duration of the maintenance window as you prefer.
1. Choose **Next**.
On the confirmation page, review your changes.
1. To apply the changes to the maintenance window immediately, select **Apply immediately**.
1. Choose **Submit** to apply your changes.
To edit your changes, choose **Previous**, or to cancel your changes, choose **Cancel**.
## Using AutoMinorVersionUpgrade to control automatic minor version updates
**Important**
`AutoMinorVersionUpgrade` is only effective for minor version upgrades above [engine release 1.3.0.0](engine-releases-1.3.0.0.md).
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](engine-updates-manually.md#engine-minor-updates-using-console).
**Note**
Patch releases (`*.*.*.1`, `*.*.*.2`, etc.) are always installed automatically during your next maintenance window, regardless of how the `AutoMinorVersionUpgrade` parameter is set.
You can set `AutoMinorVersionUpgrade` using the AWS Management Console as follows:
**To set `AutoMinorVersionUpgrade` using the Neptune console**
1. Sign in to the AWS Management Console, and open the Amazon Neptune console at [https://console.aws.amazon.com/neptune/home](https://console.aws.amazon.com/neptune/home).
1. In the navigation pane, choose **Databases**.
1. Choose the primary (writer) instance of the DB cluster for which you want to set `AutoMinorVersionUpgrade`.
1. Choose **Modify**.
1. Choose **Show more** at the bottom of the **Modify cluster** page.
1. At the bottom of the expanded page, choose either **Turn on auto minor version upgrade** or **Turn off auto minor version upgrade**.
1. Choose **Next**.
On the confirmation page, review your changes.
1. To apply the changes to auto minor version upgrade, select **Apply immediately**.
1. Choose **Submit** to apply your changes.
To edit your changes, choose **Previous**, or to cancel your changes, choose **Cancel**.
You can also use the AWS CLI to set the `AutoMinorVersionUpgrade` field. For example, to set it to `true`, you can use a command like this:
```
1. aws neptune modify-db-instance \
2. --db-instance-identifier (the ID of your cluster's writer instance) \
3. --auto-minor-version-upgrade \
4. --apply-immediately
```
Similarly, to set it to `false`, use a command like this:
```
1. aws neptune modify-db-instance \
2. --db-instance-identifier (the ID of your cluster's writer instance) \
3. --no-auto-minor-version-upgrade \
4. --apply-immediately
```
# 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](neptune-BG-deployments.md).
In some cases you can also use the CloudFormation template with which you created your DB cluster to install a major version upgrade (see [Using a CloudFormation template to update the engine version of your Neptune DB Cluster](cfn-engine-update.md)).
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 AWS Management Console
**To perform a minor version upgrade using the Neptune console**
1. Sign in to the AWS Management Console, and open the Amazon Neptune console at [https://console.aws.amazon.com/neptune/home](https://console.aws.amazon.com/neptune/home).
1. In the navigation pane, choose **Databases**, and then choose the DB cluster that you want to modify.
1. Choose **Modify**.
1. Under **Instance specifications**, choose the new version to which you want to upgrade.
1. Choose **Next**.
1. If you want to apply the changes immediately, choose **Apply immediately**.
1. Choose **Submit** to update your DB cluster.
## Installing a minor version engine upgrade using the AWS 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 AWS 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](engine-releases-1.2.0.0.md) introduced several significant changes that can make upgrading from an earlier version more complicated than usual:
+ [Engine release 1.2.0.0](engine-releases-1.2.0.0.md) 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](parameter-groups.md) for more information.
+ Engine release 1.2.0.0 introduced a new format for undo logs. Consequently, if you are upgrading to version 1.2.0.0 or higher from a version earlier than 1.2.0.0, the [`UndoLogListSize`](cw-metrics.md#cw-metrics-UndoLogListSize) metric must be below a certain threshold. Otherwise, the patch will roll back and fail. The thresholds are based on instance type: the default limit is 40k for 4xlarge or larger instances, and 10k for instances smaller than 4xlarge. If the `UndoLogListSize` exceeds the limit when you attempt to upgrade, the patch process will roll back, the upgrade will be canceled, and an event with the reason will be visible on the cluster event page. These limits can change for operational reasons without prior warning.
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 help bring down the `UndoLogListSize` below the applicable threshold. 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 `UndoLogListSize` CloudWatch metric is extremely large, opening a support case may help you explore additional strategies for bringing it down below the required limit.
+ 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](access-graph-opencypher-bolt.md) for examples.