ARTIFACTORY: How to Migrate from Derby to an External Database in Artifactory 7.x

Introduction:

This guide walks you through migrating from Artifactory's default Derby database to a fully supported external database on the JFrog Unified Platform (7.x).



Migration Scope:

Any Supported Database: This method is not limited to Derby. You can use these exact steps to migrate between any supported databases (e.g., from MySQL to PostgreSQL).

Same Application Server: This process covers changing the database server only. To migrate both the database and the Artifactory application server to a new host, please see Artifactory Migration with Manual Filestore Transfer.

JFrog Recommendation:

JFrog highly recommends using PostgreSQL for all production instances. It is the only database shared across all JFrog products, simplifying infrastructure and offering enhanced performance. For more information, please see JFrog's official Database Configuration recommendations.



Step 1: Provision the Database Server

Before altering your Artifactory instance, provision the new external database server on a dedicated server.
Please follow our official sizing recommendations here: JFrog System Requirements and Sizing.



Step 2: Configure Firewall Rules

Ensure that the network allows traffic between your Artifactory instance and the new database. Make sure to open port 5432 on your firewall from the Artifactory server to the database server.



Step 3: Set Up the PostgreSQL Database

Create the database and grant Artifactory the necessary connection permissions. 

Below is an example for PostgreSQL:

(For other database types please refer to our docs)

CREATE USER artifactory WITH PASSWORD 'password';
CREATE DATABASE artifactory WITH OWNER=artifactory ENCODING='UTF8';
GRANT ALL PRIVILEGES ON DATABASE artifactory TO artifactory;



Step 4: Export System Configurations

Export your current configurations and database entries from the running instance.

Navigate to Administration > Artifactory > Import & Export > System in the Artifactory UI.

Check the Exclude Content box.

Note:

Excluding content ensures you only export configurations and database metadata, skipping your heavy binary data.

Make sure to check the “Output Verbose Log” to have the full logging on the operation.

Validation of a successful export: Check the Artifactory logs to confirm the export was successful. You should see the following phrase:

“Full system export completed successfully”



Step 5: Perform a Graceful Shutdown

Safely shut down your Artifactory service to prevent any new data from being written to the old Derby database.



Step 6: Update the Configuration (system.yaml)

Access your Artifactory server via SSH and edit the $JFROG_HOME/var/etc/system.yaml file to point to your new database.

PostgreSQL Example:

shared:
  database:
    type: postgresql
    driver: org.postgresql.Driver
    url: jdbc:postgresql://your_db_url_here:5432/artifactory
    username: artifactory
    password: password

(You can reference $JFROG_HOME/var/etc/system.full-template.yaml for database-specific configuration templates).



Step 7: Additional Steps ONLY for Non-PostgreSQL Databases

For Postgresql database skip to step 8.

If you are migrating to a database other than PostgreSQL (e.g., MySQL, Oracle, MS SQL), you must complete these two additional steps:

Allow Non-PostgreSQL Databases: Add the following flag to your system.yaml file under the shared.database section:

shared:
  database:
    allowNonPostgresql: true

Install the JDBC Driver:

Download the JDBC driver corresponding to your specific database type.

Place the driver file in the following directory: $JFROG_HOME/artifactory/var/bootstrap/artifactory/tomcat/lib

Grant the appropriate read permissions to the file:

chmod +r <your_driver_file>



Step 8: Start Artifactory

Start the Artifactory service. Because you changed the database connection details in system.yaml, Artifactory will spin up and connect to your newly configured external database.

The UI will be blank, but this is expected - since the UI data is being pulled from the DB.



Step 9: Import System Configurations

Once Artifactory is back up and running, navigate to the UI and perform a System Import using the directory you exported in Step 4. This will populate your new database with your saved data.

Make sure to check the “Output Verbose Log” to have the full logging on the operation.
Do not exclude the content or metadata:

Validation: Check the Artifactory logs to confirm the import was successful. 
You should see the following phrase:

### Full system import finished ###



Step 10: Validation Checks

To verify that the connection to the new database is fully operational, perform a quick functionality test:

Download an artifact to confirm it can be retrieved successfully.

Upload an Artifact to see the writing to the DB works as expected.

If you have any questions or require further clarification during your migration process, please contact JFrog Support at Support@JFrog.com



Migration Scope & Zero Downtime:

This guide focuses strictly on replacing the database backend while retaining your existing application server and filestore. If you are migrating your entire environment (server and filestore) or require a zero-downtime strategy, please consult our Comprehensive Migration Guide to select the best approach for your architecture.



Post-Migration Cleanup

After verifying your data integrity on the new database, you should delete the obsolete Derby data to free up disk space. Derby saves data locally per microservice (e.g., Artifactory, Access, Config, Topology).

Assuming a default Artifactory 7.x installation, locate and remove the derby folders for all existing microservices here: $JFROG_HOME/artifactory/var/data/<name_of_microservice>/derby