Your Upgrade Guide for NuoDB - 4 Simple Steps for Success
So you’ve been using the NuoDB database for a while now, and you love it! You heard that NuoDB came out with a new release that includes a bunch of new features and functionality. Sounds great — all you have to do is to upgrade your database software and protocol to the latest version. But what’s the best way to go through that upgrade process?
There are four steps that you need to go through, and I'll walk you through each one of them in more detail:
Step 1: Prepare for Upgrade
It’s best to start by validating that your archive has no issues that need to be repaired. To do that, stop a storage manager (SM) and run a check on the archive of each storage group served by that SM. (If SGs are being used, all SMs that cover all SGs must be stopped.)
- For nuoadmin, run "nuoarchive check" — read this article for more details.
- For nuoagent, run "nuochk --dry-run" — read this article for more details.
Please note that if the archive check recommends a repair for some reason, it's best to complete the repair before you start the upgrade process.
2. Make a backup of your database. Look at the options available (hot/cold) and select the one that works best for you. Just be sure to make a backup of your database — this step is essential.
3. Check the changes in the new release and all the changes in the releases between your current release and the one you are upgrading to. Once you're aware of the changes, analyze the impact of those changes to your current scripts or configuration files. Make any necessary updates to the scripts or configuration files (if needed) before you restart the NuoAdmin process on that host.
It's important to note that installation of the new NuoDB release will NOT overwrite any existing configuration files, specifically:
Only new sample files, such as jvm-options.sample, nuodb.config.sample, default.properties.sample, and nuodb-rest-api.yml.sample, are installed in the $NUODB_HOME/etc folder.
Step 2: Upgrade the Database Software for Every NuoDB Process
There are currently two ways to upgrade your database software (DS), while the DS is up and running (rolling upgrade) and while your database is down. You'll want to choose the best one for you based on your business and system structure. To help clarify your options, here are a few system structure examples.
Examples of situations when you need to use a modified rolling upgrade procedure:
- If you have only one transaction engine (TE): you could start a second TE before you shut down the first;
- If you have a storage group (SG) that is managed by only one SM: you could start a second SM, possibly from a backup, and let it complete SYNCing before shutting down the first;
- If all SMs or all transaction engines (TEs) run on the same host (which is also not best practice) you could perform the software upgrade first, and then restart the processes in sequence.
Now that you know whether or not you can consider a rolling upgrade, there are two options for this step:
1. Upgrade your database software while your database is offline. You set a window for maintenance and run the upgrade while your database is offline. Read more detailed information on upgrading while your database is offline in our documentation.
2. Upgrade your database software while your database is up and running. Using this option, your database is available and functioning during the whole process; this upgrade is called a Rolling Upgrade. Read our documentation for more details on performing a rolling upgrade.
Step 3: Upgrade the Database Protocol
The database protocol defines which database capabilities are available to be used in the database. In a new version, some new features or changes require a database protocol change to use. Not all new versions have database protocol changes. We limit database protocol changes to major or minor releases (X or Y in a version scheme of X.Y.Z-P).
Here's another question that I'm frequently asked as a Senior Customer Support Engineer: “When does NuoDB require that I upgrade the database protocol? And how can I upgrade it?” Run "show database version" (starting at 3.4) to see if you have available upgrade versions.
So, first, how do you upgrade your database protocol?
- When using nuoadmin, your syntax is: (example for upgrading to version 4.0)
nuocmd upgrade database-version --version 4.0
Read here for more information on upgrading the database protocol.
- When using nuoagent, you run the command via nuodbmgr, the syntax is: (example for upgrading to version 4.0)
nuodb [domain] > upgrade database
Step 4: After Upgrade - Tasks by Version
These are tasks that you need to do based on the version that you are upgrading to. For those upgrading from NuoDB 3.4 to NuoDB 4.0, good news! There are no tasks you need to perform. Read this article for more details on upgrades for each release.
Welcome to Your Latest NuoDB Release!
I’ve been working with NuoDB as a customer support engineer for many years, so I have spoken with many customers and helped them as they try out NuoDB and work to configure it to best suit the needs of their deployment. I think that the latest release, NuoDB 4.0, is one that offers a lot of really useful new features and benefits, and I hope you find this article helpful as you step through how to upgrade your NuoDB database. As always, I’m here to help, as are other members of the customer support team. Stay tuned for my next article on how to confirm that your upgrade completed successfully!