About the Read-only Replica Database
Many complex operations, such as data exports and report generation, require reading data from the database. To reduce the load on the main database, you can configure a read-only database for these long-running operations. Any changes made to the main database are automatically replicated to the replica database.
 |
Codebeamer supports a single read-only replica database.
|
This read-only replica can be set up on a single node or in a cluster environment and can work in combination with a worker node. Once configured, the worker node is able to use the read-only replica database for specific operations. For the list of operations supported on the read-only replica database, see the Operations Performed Using the Read-only Replica Database section.
For more information on worker nodes, see Worker Nodes in a Cluster.
Background job waits for 5 minutes for the data between the main database and replica database to sync. If the sync does not happen in 5 minutes, the background job fails to execute, and the following error message is displayed:
Database synchronization timed out, the database is not in sync.
You can configure the waiting time for the background job using the CB_MAXIMUM_READONLY_WAITING_SECONDS environment variable. This variable can be configured in the environment variables file.
|
|
As the database administrator, you are responsible for the configuration and maintenance of the read-replica database. You should configure the syncing of the read-replica database based on your requirements. PTC does not handle the maintenance of your replica database. For configuration details, see Configuring the Read-only Replica Database.
|
To start using the configured read-only replica database through API, you need to pass the CB-USE-READ-ONLY-DATA-SOURCE=true extra header in the API, using a third-party tool. Once the read-only database has been successfully configured, based on the value of the header, the application decides whether to send the request to the main database or to the read-only database instance.
|
|
• This additional setting has been introduced only as a Beta feature.
• To use the feature efficiently, ensure the replica database is synchronized with the latest data by using the GET /api/database/master/sync and GET /api/database/readonly/sync API calls.
• The read-only replica database can be used with GET requests only. Other types of requests, for example, POST, DELETE, and so on cannot be used, as the database is read only.
|
Operations Performed Using the Read-only Replica Database
List of operations performed using the read-only replica database:
• Scheduled reports
• Project Export for Deployment
• Coverage Browser Excel export (Release coverage | Requirement coverage | Test coverage)
• Traceability Excel export
• Item Word Export
• ReqIF Export
◦ Project level
◦ Tracker level
• Document Merge Word Export
• Workflow action Export to Word
Identifying Jobs Executed Using the Read-only Replica Database
Operations executed using the read replica database can be identified by the DB#=RO tag, which appears as a prefix to the JobID in the cb.txt log file. This tag indicates that the operation was performed using the read replica database. Conversely, operations that do not have this prefix indicates that they were executed using the main database. Following is an image of a sample log file:
You can download the cb.txt log file from > > .
Considerations When Using the Read-only Replica Database
Consider the following when using the read-only replica database for executing operations:
• Data in the replica databases could be stale if the sync time is earlier than the time when the operation is initiated.
• When generating reports or exporting data, if your background job fails repeatedly due to database sync issues, it is recommended to use the APIs GET /database/master/sync and GET /database/readonly/sync to verify the last sync time between the main database and the replica database. These API calls provide the exact time difference between the operation initiation and the last data sync.
|
|
The time returned by the GET /database/master/sync and GET /database/readonly/sync APIs is in the form of epochTime. You can use any online free converters to convert the epochTime into a human date.
|
• If the sync time is greater than the time of the operation execution, the operation is added to the server queue.