Skip to main content
Version: Deploy 25.3

Database setup and migration guidance

This topic provides high-level guidance for selecting a database setup for Deploy and planning database migration when changes are required. It explains recommended database configurations, common migration scenarios, and key considerations when moving to a different database setup.

It introduces the Live (operational) database and the Reporting database used by Deploy, describing their purpose and how they can be separated when needed.

Deploy supports separate database configurations for Live (operational) data and Reporting data:

  • The Live database stores the primary Deploy repository data required for day-to-day operation.
  • The Reporting database stores reporting data and archived task information.

These databases can be configured either as:

  • Separate schemas within the same database, or
  • Two completely separate databases.

For more information, see:

Supported Databases and Production Recommendations​

For production environments, Deploy supports external enterprise-grade databases. The supported databases are:

  • PostgreSQL
  • Oracle
  • Microsoft SQL Server
  • MySQL

For supported database versions, see Installation Prerequisites.

PostgreSQL is recommended for production use.

Using an external database server is also recommended for production environments.

The following documentation provides details on supported databases, versions, and production setup recommendations:

Before installation, an empty database must be created and configured. During installation, Deploy automatically creates the required database schema.

Deploy allows artifact storage to be configured independently using the repository configuration. Artifacts can be stored in different locations depending on operational needs.

Maven or HTTP(S)-based repositories are commonly used in production environments and help keep large binary artifacts outside the Deploy database.

Database Storage​

Artifacts can be stored in a relational database and are fully supported, but this option may impact database size, performance, and backup operations.

Shared Filesystem​

Artifacts can also be stored on a shared filesystem accessible to all Deploy master nodes in a clustered setup.

Recommendation​

For production environments, guidance gives preference to using external artifact repositories or shared file storage rather than storing large binary artifacts directly in the Deploy database.

For more information, see:

Additional Recommendations​

When Migration May Be Needed​

Database migration may be required when:

  • Moving away from non-production-oriented setups
  • Switching to a supported external database for production use
  • Separating repository and reporting storage
  • Upgrading from older storage models
  • Changing infrastructure or deployment models

The exact migration path depends on the current setup, target setup, Deploy version, and whether repository data, reporting data, or both are involved.

Types of Database Migration​

Deploy database migration can involve different types of data and target configurations. The appropriate approach depends on what data is migrated and how the source and target databases are configured. For more information, see Separate Databases for Reporting and Repository in Deploy.

When changing database setups or updating Deploy, installer and updater scripts do not migrate databases automatically. Database migration must be performed manually by the customer according to documented guidance.

Main Live Database Migration​

This applies when the primary Deploy repository data needs to move to a different operational database setup, such as moving from an embedded or internal database to a supported external database, or moving the main repository to a new database environment.

Reporting or Archived Task Database Migration​

Migration of reporting or archived task data when stored separately from the main repository. For more information, see Migrate Archived Tasks to SQL Database.

Legacy Storage Migration​

This applies when upgrading from older storage models or historical Deploy configurations that require a transition to SQL-backed storage. For more information, see Migrate Deploy Data Storage to SQL Database.

Infrastructure-level Database Migration​

This applies when the migration is mainly handled through infrastructure or platform operations, such as backup and restore into a new database environment followed by product reconfiguration.

General Migration Recommendations​

Before Migration​

  • Identify the current database and artifact storage configuration
  • Identify the target database and artifact storage configuration
  • Confirm the target database is supported for the Deploy version
  • Determine which data sets are being migrated
  • Back up all data before changes
  • Validate the migration approach in non-production environments where possible

During Migration Planning​

  • Confirm migration ownership and responsibilities
  • Confirm expected downtime
  • Ensure JDBC drivers, database access, and credentials are ready
  • Define verification steps

After Migration​

  • Verify Deploy starts successfully
  • Validate data availability
  • Test key product workflows
  • Verify reporting access
  • Maintain rollback options until validation is complete
important

A database backup before upgrade is strongly recommended. For more information, see Upgrade Deploy.

Moving Away from Derby​

caution

The Apache Derby Project was officially retired in October 2025 and no longer receives bug fixes or security updates.

Derby database is not recommended for production use. Customers may need to move away from Derby when adopting a production-ready database strategy or aligning with recommended production setups.

At a high level, this usually means preparing a supported external target database, moving the required data, updating the Deploy database configuration, and validating the environment after the move.

The exact migration steps may vary by product version and environment.