> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/10.1/instance-administration/sonarqube-db-copy-tool.md).
# SonarQube Server DB Copy Tool
The SonarQube Server 10.1 database copy tool helps you migrate your database between vendors.
{% hint style="info" %}
**For AI agents:** You're in the SonarQube Server 10.1 documentation. For a list of all 10.1 pages, see the [SonarQube Server 10.1 page index](https://931701944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FguPtldYmKsIetAs13CP3%2Fuploads%2F8YxeTnX7jettMg9K19a8%2Fsonarqube-server-10.1-llms.txt?alt=media). For the whole site, see the [page index](https://docs.sonarsource.com/llms.txt) or the [full text](https://docs.sonarsource.com/llms-full.txt). For another version, replace 10.1 in the URL with that version. The [latest version](https://docs.sonarsource.com/sonarqube-server/) has no version number in its URL.
{% endhint %}
*Customers can download the* [*SonarQube DB Copy Tool*](https://binaries.sonarsource.com/CommercialDistribution/sonar-db-copy/sonar-db-copy-1.7.0.5273-jar-with-dependencies.jar)*.*
We provide this tool to help you migrate your SonarQube Server database from one database vendor to another. For example, if you’ve been using your SonarQube Server instance with Oracle and want to migrate to PostgreSQL, the **SonarQube DB Copy Tool** will help. DB Copy is preferred for database migration because it does SonarQube Server-specific checks, ensures data consistency, and outputs meaningful logs.
On this page, *source* refers to your current database and *target* refers to the database you are moving to.
## 1. DB Copy - preparation phase
DB Copy only copies data, not the schema. This is why the purpose of this step is to populate the *target* with an empty SonarQube Server schema. For this, you have to install a temporary SonarQube Server instance.
{% hint style="info" %}
As creating the database schema is a quick operation, you don’t need to provision a specific server to do this. A workstation or any non-production server with Java 17 available would be enough.
{% endhint %}
1. Make sure you can connect to your *target* database.
2. [Download](https://www.sonarsource.com/products/sonarqube/downloads/historical-downloads/) a SonarQube Server that matches the version and edition of your *source* instance.
3. Unzip SonarQube Server and put it in a relevant place on the machine.
4. Configure SonarQube Server to connect to your *target* database (ie. provide JDBC parameters in the `$SONAR_HOME/conf/sonar.properties` file).
5. Start SonarQube Server using the script matching your operating system:
* On Linux: `$SONAR_HOME/bin/linux-x86-64/sonar.sh start`
* On macOS: `$SONAR_HOME/bin/macosx-universal-64/sonar.sh start`
* On Windows: `%SONAR_HOME\bin\windows-x86-64\StartSonar.bat`
6. Verify that the SonarQube Server schema was correctly created. To do this, look at the `logs/web.log` file to see the line *"Executed DB migrations: success"*. Once this is done, it means that your *target* database had been populated with the SonarQube Server schema.
7. Stop SonarQube Server:
* On Linux: `$SONAR_HOME/bin/linux-x86-64/sonar.sh stop`
* On macOS: `$SONAR_HOME/bin/macosx-universal-64/sonar.sh stop`
* On Windows: terminate the `StartSonar.bat` script
8. You can now delete this temporary SonarQube Server instance.
## 2. DB Copy - execution phase
Because this step is about copying data from *source* to *target*, the overall performance makes a difference. Make sure you execute this on a powerful machine that has fast network access to both database servers.
1. Unzip the DB Copy package provided by Sonar Support on the machine where it will be executed. Java is required.
2. Stop the SonarQube Server instance connected to your *source* database. This is to ensure that we don’t have records being inserted/updated while copying.
3. Execute the base command with the correct parameters. See below how to do it.
4. If you see something else other than the success message \*\**THE COPY HAS FINISHED SUCCESSFULLY\*\** please open a [Sonar Support ticket](mailto:undefined) and provide the complete DB Copy logs for investigation (logs are just the standard output of the tool).
### Base command and parameters
**Migrating with an Oracle database**
If you wish to migrate with an Oracle database, you need to include the Oracle driver in the classpath so it is available to the sonar-db-copy tool. In this case, the syntax is:
```css-79elbk
java -cp ojdbc11-21.8.0.0.jar:sonar-db-copy-1.7.0.5273.jar com.sonar.dbcopy.StartApp
```
{% hint style="warning" %}
On Windows, the classpath arguments separator is a semicolon (;), while on a Unix system (like in the example) it is a colon (:).
{% endhint %}
**Migrating with all other databases**
If you are not migrating from or to an Oracle database, then the syntax is:
```css-79elbk
java -jar sonar-db-copy-1.7.0.5273-jar-with-dependencies.jar
```
| | | |
| -------------------- | --------------------------------- | ------------ |
| **Parameter** | **Description** | **Required** |
| `-help` | Print this help information | no |
| `-urlSrc JDBC_URL` | JDBC URL of the *source* database | yes |
| `-userSrc USERNAME` | Username of the *source* database | yes |
| `-pwdSrc PASSWORD` | Password of the *source* database | yes |
| `-urlDest JDBC_URL` | JDBC URL of the *target* database | yes |
| `-userDest USERNAME` | Username of the *target* database | yes |
| `-pwdDest PASSWORD` | Password of the *target* database | yes |
Here is an example of a copy from an Oracle to a Postgres database. Note that each parameter is on one line and there are \ (backslash) characters to continue the command. While this works on most shell command-line interpreters, it is not necessarily the case. Use only one line and remove backslashes in that case.
```css-79elbk
java \
-cp ojdbc11-21.8.0.0.jar:sonar-db-copy-1.7.0.5273.jar com.sonar.dbcopy.StartApp \
-urlSrc jdbc:oracle:thin:@10.18.51.1:1521/XEPDB1 \
-userSrc sonar \
-pwdSrc 05xlAz1EhgQb9Pl8 \
-urlDest jdbc:postgresql://10.10.1.138/sonarqube \
-userDest sonar \
-pwdDest Ck23L1OpqF4BdwJv
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.sonarsource.com/sonarqube-server/10.1/instance-administration/sonarqube-db-copy-tool.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.