# Using a CloudFormation template to update the engine version of your Neptune DB Cluster
You can re-use the Neptune CloudFormation template that you used to create your Neptune DB Cluster to update its engine version.
Neptune engine version upgrades can be minor or major. Using an CloudFormation template can help with major version upgrades, which often contain significant changes. Since major version upgrades can contain database changes that are not backward-compatible with existing applications, you may also need to make changes to your applications when upgrading. Always [test before upgrading](engine-maintenance-management.md#always-test-before-upgrading), and we strongly recommend that you always create a manual snapshot of your DB cluster before upgrading.
Note that you have to do a separate engine upgrade for each major version. You can't skip a major version and upgrade directly to the major version following.
Prior to May 17, 2023, if you used the Neptune CloudFormation stack to upgrade your engine version, it simply created a new, empty DB cluster in place your current one. As of May 17, 2023, however, the Neptune CloudFormation stack now supports in-place engine upgrades that preserve your existing data.
**Note**
If you are using the AWS Cloud Development Kit (AWS CDK), ensure that the AWS CDK version being used is 2.82.0 or later. Versions prior to 2.82.0 do not support in-place Neptune engine upgrades.
For a major version upgrade, your template should set the following properties in `DBCluster`:
+ `DBClusterParameterGroup` (Custom or Default)
+ `DBInstanceParameterGroupName`
+ `EngineVersion`
Similarly, for DBInstances attached to DBCluster you should set:
+ `DBParameterGroup` (Custom/Default)
Make sure that all your parameter groups are defined in the template, whether they are default or custom.
In the case of a custom parameter group, make sure that the family of your existing custom parameter group is compatible with the new engine version. Engine versions earlier than [1.2.0.0](engine-releases-1.2.0.0.md) used parameter group family `neptune1`, whereas engine releases from 1.2.0.0 forward require parameter group family `neptune1.2`. See [Amazon Neptune parameter groups](parameter-groups.md) for more information.
For major engine version upgrades, specify a parameter group with the appropriate family in the `DBCluster` `DBInstanceParameterGroupName` field.
A default parameter group should be upgraded to one that is compatible with the new engine version.
Note that Neptune automatically reboots DB instances after an engine upgrade.
**Topics**
+ [Example: Minor engine upgrade from 1.2.0.1 to 1.2.0.2](cfn-engine-update-1201-1202.md)
+ [Example: Major version upgrade from 1.1.1.0 to 1.2.0.2 with default parameter groups](cfn-engine-update-1110-1202-default.md)
+ [Example: Major version upgrade from 1.1.1.0 to 1.2.0.2 with custom parameter groups](cfn-engine-update-1110-1202-custom.md)
+ [Example: Major version upgrade from 1.1.1.0 to 1.2.0.2 with a mix of default and custom parameter groups](cfn-engine-update-1110-1202-mixed.md)
# Example: Minor engine upgrade from 1.2.0.1 to 1.2.0.2
Find the DB cluster that you want to upgrade, and the template you used to create it. For example:
```
Description: Base Template to create Neptune Stack with Engine Version 1.2.0.1 using custom Parameter Groups
Parameters:
DbInstanceType:
Description: Neptune DB instance type
Type: String
Default: db.r5.large
Resources:
NeptuneDBClusterParameterGroup:
Type: 'AWS::Neptune::DBClusterParameterGroup'
Properties:
Family: neptune1.2
Description: test-cfn-neptune-db-cluster-parameter-group-description
Parameters:
neptune_enable_audit_log: 0
NeptuneDBParameterGroup:
Type: 'AWS::Neptune::DBParameterGroup'
Properties:
Family: neptune1.2
Description: test-cfn-neptune-db-parameter-group-description
Parameters:
neptune_query_timeout: 20000
NeptuneDBCluster:
Type: 'AWS::Neptune::DBCluster'
Properties:
EngineVersion: 1.2.0.1
DBClusterParameterGroupName:
Ref: NeptuneDBClusterParameterGroup
DependsOn:
- NeptuneDBClusterParameterGroup
NeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DBParameterGroupName:
Ref: NeptuneDBParameterGroup
DependsOn:
- NeptuneDBCluster
- NeptuneDBParameterGroup
Outputs:
DBClusterId:
Description: Neptune Cluster Identifier
Value:
Ref: NeptuneDBCluster
```
Update the `EngineVersion` property from `1.2.0.1` to `1.2.0.2`:
```
Description: Template to upgrade minor engine version to 1.2.0.2
Parameters:
DbInstanceType:
Description: Neptune DB instance type
Type: String
Default: db.r5.large
Resources:
NeptuneDBClusterParameterGroup:
Type: 'AWS::Neptune::DBClusterParameterGroup'
Properties:
Family: neptune1.2
Description: test-cfn-neptune-db-cluster-parameter-group-description
Parameters:
neptune_enable_audit_log: 0
NeptuneDBParameterGroup:
Type: 'AWS::Neptune::DBParameterGroup'
Properties:
Family: neptune1.2
Description: test-cfn-neptune-db-parameter-group-description
Parameters:
neptune_query_timeout: 20000
NeptuneDBCluster:
Type: 'AWS::Neptune::DBCluster'
Properties:
EngineVersion: 1.2.0.2
DBClusterParameterGroupName:
Ref: NeptuneDBClusterParameterGroup
DependsOn:
- NeptuneDBClusterParameterGroup
NeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DBParameterGroupName:
Ref: NeptuneDBParameterGroup
DependsOn:
- NeptuneDBCluster
- NeptuneDBParameterGroup
Outputs:
DBClusterId:
Description: Neptune Cluster Identifier
Value:
Ref: NeptuneDBCluster
```
Now use CloudFormation to run the revised template.
# Example: Major version upgrade from 1.1.1.0 to 1.2.0.2 with default parameter groups
Find the `DBCluster` that you want to upgrade, and the template you used to create it. For example:
```
Description: Base Template to create Neptune Stack with Engine Version 1.1.1.0 using default Parameter Groups
Parameters:
DbInstanceType:
Description: Neptune DB instance type
Type: String
Default: db.r5.large
Resources:
NeptuneDBCluster:
Type: 'AWS::Neptune::DBCluster'
Properties:
EngineVersion: 1.1.1.0
NeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DependsOn:
- NeptuneDBCluster
Outputs:
DBClusterId:
Description: Neptune Cluster Identifier
Value:
Ref: NeptuneDBCluster
```
+ Update the default `DBClusterParameterGroup` to the one in the parameter group family used by the new engine version (here `default.neptune1.2`).
+ For each `DBInstance` attached to the `DBCluster`, update the default `DBParameterGroup` to the one in the family used by new engine version (here `default.neptune1.2`).
+ Set the `DBInstanceParameterGroupName` property to the default parameter group in that family (here `default.neptune1.2`).
+ Update the `EngineVersion` property from `1.1.0.0` to `1.2.0.2`.
The template should look like this:
```
Description: Template to upgrade major engine version to 1.2.0.2 by using upgraded default parameter groups
Parameters:
DbInstanceType:
Description: Neptune DB instance type
Type: String
Default: db.r5.large
Resources:
NeptuneDBCluster:
Type: 'AWS::Neptune::DBCluster'
Properties:
EngineVersion: 1.2.0.2
DBClusterParameterGroupName: default.neptune1.2
DBInstanceParameterGroupName: default.neptune1.2
NeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DBParameterGroupName: default.neptune1.2
DependsOn:
- NeptuneDBCluster
Outputs:
DBClusterId:
Description: Neptune Cluster Identifier
Value:
```
Now use CloudFormation to run the revised template.
# Example: Major version upgrade from 1.1.1.0 to 1.2.0.2 with custom parameter groups
Find the `DBCluster` that you want to upgrade, and the template you used to create it. For example:
```
Description: Base Template to create Neptune Stack with Engine Version 1.1.1.0 using custom Parameter Groups
Parameters:
DbInstanceType:
Description: Neptune DB instance type
Type: String
Default: db.r5.large
Resources:
NeptuneDBClusterParameterGroup:
Type: 'AWS::Neptune::DBClusterParameterGroup'
Properties:
Name: engineupgradetestcpg
Family: neptune1
Description: 'NeptuneDBClusterParameterGroup with family neptune1'
Parameters:
neptune_enable_audit_log: 0
NeptuneDBParameterGroup:
Type: 'AWS::Neptune::DBParameterGroup'
Properties:
Name: engineupgradetestpg
Family: neptune1
Description: 'NeptuneDBParameterGroup1 with family neptune1'
Parameters:
neptune_query_timeout: 20000
NeptuneDBCluster:
Type: 'AWS::Neptune::DBCluster'
Properties:
EngineVersion: 1.1.1.0
DBClusterParameterGroupName:
Ref: NeptuneDBClusterParameterGroup
DependsOn:
- NeptuneDBClusterParameterGroup
NeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DBParameterGroupName:
Ref: NeptuneDBParameterGroup
DependsOn:
- NeptuneDBCluster
- NeptuneDBParameterGroup
Outputs:
DBClusterId:
Description: Neptune Cluster Identifier
Value:
Ref: NeptuneDBCluster
```
+ Update the custom `DBClusterParameterGroup` family to the one used by the new engine version here `default.neptune1.2`).
+ For each `DBInstance` attached to the `DBCluster`, update the custom `DBParameterGroup` family to the one used by the new engine version (here `default.neptune1.2`).
+ Set the `DBInstanceParameterGroupName` property to the parameter group in that family (here `default.neptune1.2`).
+ Update the `EngineVersion` property from `1.1.0.0` to `1.2.0.2`.
The template should look like this:
```
Description: Template to upgrade major engine version to 1.2.0.2 by modifying existing custom parameter groups
Parameters:
DbInstanceType:
Description: Neptune DB instance type
Type: String
Default: db.r5.large
Resources:
NeptuneDBClusterParameterGroup:
Type: 'AWS::Neptune::DBClusterParameterGroup'
Properties:
Name: engineupgradetestcpgnew
Family: neptune1.2
Description: 'NeptuneDBClusterParameterGroup with family neptune1.2'
Parameters:
neptune_enable_audit_log: 0
NeptuneDBParameterGroup:
Type: 'AWS::Neptune::DBParameterGroup'
Properties:
Name: engineupgradetestpgnew
Family: neptune1.2
Description: 'NeptuneDBParameterGroup1 with family neptune1.2'
Parameters:
neptune_query_timeout: 20000
NeptuneDBCluster:
Type: 'AWS::Neptune::DBCluster'
Properties:
EngineVersion: 1.2.0.2
DBClusterParameterGroupName:
Ref: NeptuneDBClusterParameterGroup
DBInstanceParameterGroupName:
Ref: NeptuneDBParameterGroup
DependsOn:
- NeptuneDBClusterParameterGroup
NeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DBParameterGroupName:
Ref: NeptuneDBParameterGroup
DependsOn:
- NeptuneDBCluster
- NeptuneDBParameterGroup
Outputs:
DBClusterId:
Description: Neptune Cluster Identifier
Value:
Ref: NeptuneDBCluster
```
Now use CloudFormation to run the revised template.
# Example: Major version upgrade from 1.1.1.0 to 1.2.0.2 with a mix of default and custom parameter groups
Find the `DBCluster` that you want to upgrade, and the template you used to create it. For example:
```
Description: Base Template to create Neptune Stack with Engine Version 1.1.1.0 using custom Parameter Groups
Parameters:
DbInstanceType:
Description: Neptune DB instance type
Type: String
Default: db.r5.large
Resources:
NeptuneDBClusterParameterGroup:
Type: 'AWS::Neptune::DBClusterParameterGroup'
Properties:
Family: neptune1
Description: 'NeptuneDBClusterParameterGroup with family neptune1'
Parameters:
neptune_enable_audit_log: 0
NeptuneDBParameterGroup:
Type: 'AWS::Neptune::DBParameterGroup'
Properties:
Family: neptune1
Description: 'NeptuneDBParameterGroup with family neptune1'
Parameters:
neptune_query_timeout: 20000
NeptuneDBCluster:
Type: 'AWS::Neptune::DBCluster'
Properties:
EngineVersion: 1.1.1.0
DBClusterParameterGroupName:
Ref: NeptuneDBClusterParameterGroup
DependsOn:
- NeptuneDBClusterParameterGroup
CustomNeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DBParameterGroupName:
Ref: NeptuneDBParameterGroup
DependsOn:
- NeptuneDBCluster
- NeptuneDBParameterGroup
DefaultNeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DependsOn:
- NeptuneDBCluster
Outputs:
DBClusterId:
Description: Neptune Cluster Identifier
Value:
Ref: NeptuneDBCluster
```
+ For a custom cluster parameter group, update the `DBClusterParameterGroup` family to the one corresponding to new engine version, namely `neptune1.2`.
+ For a default cluster parameter group, update the `DBClusterParameterGroup` to the default corresponding to new engine version, namely `default.neptune1.2`.
+ For each `DBInstance` attached to the `DBCluster`, update a default `DBParameterGroup` to the one in the family used by new engine version (here `default.neptune1.2`), and a custom parameter group to one that uses the family supported by the new engine version (here `neptune1.2`).
+ Set the `DBInstanceParameterGroupName` property to the parameter group in the family supported by the new engine version.
The template should look like this:
```
Description: Template to update Neptune Stack to Engine Version 1.2.0.1 using custom and default Parameter Groups
Parameters:
DbInstanceType:
Description: Neptune DB instance type
Type: String
Default: db.r5.large
Resources:
NeptuneDBClusterParameterGroup:
Type: 'AWS::Neptune::DBClusterParameterGroup'
Properties:
Family: neptune1.2
Description: 'NeptuneDBClusterParameterGroup with family neptune1.2'
Parameters:
neptune_enable_audit_log: 0
NeptuneDBParameterGroup:
Type: 'AWS::Neptune::DBParameterGroup'
Properties:
Family: neptune1.2
Description: 'NeptuneDBParameterGroup1 with family neptune1.2'
Parameters:
neptune_query_timeout: 20000
NeptuneDBCluster:
Type: 'AWS::Neptune::DBCluster'
Properties:
EngineVersion: 1.2.0.2
DBClusterParameterGroupName:
Ref: NeptuneDBClusterParameterGroup
DBInstanceParameterGroupName: default.neptune1.2
DependsOn:
- NeptuneDBClusterParameterGroup
CustomNeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DBParameterGroupName:
Ref: NeptuneDBParameterGroup
DependsOn:
- NeptuneDBCluster
- NeptuneDBParameterGroup
DefaultNeptuneDBInstance:
Type: 'AWS::Neptune::DBInstance'
Properties:
DBClusterIdentifier:
Ref: NeptuneDBCluster
DBInstanceClass:
Ref: DbInstanceType
DBParameterGroupName: default.neptune1.2
DependsOn:
- NeptuneDBCluster
Outputs:
DBClusterId:
Description: Neptune Cluster Identifier
Value:
Ref: NeptuneDBCluster
```
Now use CloudFormation to run the revised template.