How to update Sonarqube through some automation?

Must-share information (formatted with Markdown):

  • which versions are you using (SonarQube, Scanner, Plugin, and any relevant extension)
    Sonarqube 8.6.1-EE
  • what are you trying to achieve
    Update Sonarqube across versions through some pipeline/automation
  • what have you tried so far to achieve this
    Read the instructions unfortunately they are not very automation friendly. Here are my queries:
  1. I am currently running SQ 8.6.1-EE with PostgreSQL 12.5.1 using AWS Fargate. E.g. currently 8.7.0-EE is out. I was hoping to get step-by-step guide to upgrade from 8.6.1-EE to 8.7.0-EE.
  2. What about the Database? Does DB require a separate upgrade? or Just the base SQ image upgrade shall take care of DB? Steps?
  3. I believe next LTS version is coming in Q2, 2021. What would the step-by-step upgrade instructions look like, when upgrading from 8.7.0-EE to upcoming LTS version? Any difference than 8.6 to 8.7 upgrade?
    Thanks in advance!

Amit Saxena

Hi @actuallyamitsq ,

the upgrade is rather manual by design as you should always prepare a backup of your database prior to upgrading as well as inform your users about it specially when it comes to upgrading to an LTS as it can take quiet some time to do so.
nevertheless there are a few points that might help you to design a pipeline that updates your instance automatically:

There are tools that search for newer images on the docker hub and deploy them automatically, but i am not aware of any that run on fargate. you could still store the sha256 hash of the image and compare it against a manual pull in a pipeline to check if there is a new image available on the docker hub. for this you should use the tag sonarqube:8-enterprise. of cause you need to change this when we release the 9.x series in the future, but there will of cause be an announcement from our side about that.

So now that you are aware of a new image and re deployed sonarqube using this new image is the question of database migrations on the table. to trigger a database migration via the api you can use the following api endpoint:


a documentation to this api endpoint can be found in the embedded documentation in your sonarqube instance (questionmark → web api), but this one only needs a POST and that’s it. if this call is needed can be checked using


if you need to migrate your database it will return DB_MIGRATION_NEEDED.
The database migration can take some time.

For the LTS upgrade as you are already on the 8.x release this should be yet another normal update for you. when you jump from LTS to LTS the procedure will be the same, but will take longer.

As a last note you should check that, if you are using 3rd party plugins, they are compatible with the new version. for the embedded language analyzers you can assume that there will be no issue but for community plugins you have to manually check.

hope this helps you to get a better picture of how to automate the update procedure of sonarqube :slight_smile:

1 Like

Hello @Tobias_Trabelsi
Please pardon me for my ignorance. I still have few related queries.

  • Why would I need a DB migration, even though I am going to use the same RDS instance?
  • At what stage the DB upgrade should be triggered? I guess, once the app is updated with new image, right?
  • Is DB upgrade a manual step triggered from GUI? What is used for?
  • What type of cautions shall we take before thinking of upgrades?

Thanks in advance!

Hi @actuallyamitsq

no problem i am happy to help :slight_smile:

A DB Migration includes structural changes to the data of the database (add new columns, change names etc.). the update of the version of your database and a DB Migration during a sonarqube update are two different things.

When /api/system/status returns DB_MIGRATION_NEEDED. There will also be a notice of this in the logs that the database needs to be migrated with the URL to a web UI where you could trigger this migration manually as well.

Always have a backup and a restore plan at hand. we are trying our best to ensure that the upgrade process is as smooth and reliable as possible, but as with every on premise software we can not 100% estimate the environment sonarqube is running in.
Also you have to check with your users as database migrations can take a long time (depending on the database size) and check for compatibility issues with plugins that you have installed via the marketplace.

does this answer your questions?

1 Like

Hello @Tobias_Trabelsi,
Thanks a lot for your patience!

So this is what I understood. Please correct me if I am wrong.

  • SQ Upgrade basically has two parts
  1. App update to a new version
  2. DB update to match to new app version
  • App Update is:
  1. Finding out, if a new image version is available or not(Either by some automation or Manually)
  2. Use new version in your automation and upgrade your app
  • DB Update is:
  1. Once app upgrade is finished, check if API call /api/system/status returns “DB_MIGRATION_NEEDED” or not
  2. If YES, use /setup & follow GUI instructions to upgrade DB
  3. If NOT, then nothing to do.
  • LTS to LTS jump takes extra time, otherwise the process remains the same
  • Time taken in DB migration depends upon the size of DB

Thanks in advance!
Amit Saxena

No Problem :sweat_smile:

In general your understanding is correct, but there are a few remarks.

Sonarqube will not let users log in until the database migration is finished, so keep this in mind

Also i am missing the point regarding plugins that i stated

other than that it looks good :+1:

1 Like

Hi @Tobias_Trabelsi,
Thank you for you prompt responses!

So far we discussed the happy path. I have some queries related to not-so-happy path.

Situation 1:

  • App version got updated just fine
  • API call /api/system/status returned “DB_MIGRATION_NEEDED”
  • DB migration triggered using api call /setup but FAILED for some reason.
  • What should be done, apart from troubleshooting?
  • Should we revert the app to previous version and re-run /api/system/status to check DB state for any inconsistencies?
  • What kind of support/control SQ has in this situation? Is there any API or something, which can bring back the DB to last working stage in case of app version revert?

Situation 2:

  • App version update failed
  • Should we just revert the app to previous version and everything should be okay as before, right?

I would also request if you can help me with some documentation/tickets about the general/not-so-happy-path issues happen during the regular updates.

Thanks in advance!
Amit Saxena

Hi @actuallyamitsq ,

let’s step back for a moment and reiterate over the “App version update”.

You see if you deploy and start a new version of sonarqube there will not be any change to your data YET. The data will only be touched when you start the migration process, so your understanding of the rollback procedure is not correct.

When describing the not so happy path you can assume that there is no persistent data on the sonarqube application. All persistent data is stored in the database.
Now what do you do when something goes south during a database migration? you have to roll back your database and deploy the original version of sonarqube that you had prior the upgrade and all should be fine. If you are facing a situation like this, we would also appreciate to hear about that to fix possible migration issues. you could then just create a post in this forum about that and we will have a look.

does this make sense to you?

1 Like


Thanks for your prompt reply. Yeah the argument makes sense. Currently, I am working on designing the upgrade and rollback solution, so do not have real life issue, only doubts.
For now, I think I am good with all my doubts cleared so far.
Thanks again for your patience and help!

Amit Saxena

No problem and let’s hope that you don’t have to walk the not so happy path :sweat_smile:

good luck with your pipeline design

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.