Transition to PostgreSQL and Phase-out of Apache Jackrabbit
With Sophora 6, we’re continuing the transition to PostgreSQL and moving away from the Apache Jackrabbit–based JCR implementation. In addition to the Version Store introduced in Sophora 5, all working and live versions of documents will now also be stored in PostgreSQL.
Cluster Sophora Servers
Cluster Sophora Servers can be deployed without any changes to their existing configuration. No adjustments are needed when upgrading to Sophora 6.
Staging Sophora Servers
With Sophora 6, each Sophora Staging will require its own PostgreSQL database.
This is particularly relevant for cloud deployments using Kubernetes, for example via our Helm chart at https://github.com/subshell/helm-charts/tree/main/charts/sophora-server, since we recommend scaling Sophora Staging Servers. There are several strategies for managing this in Kubernetes:
- Run a PostgreSQL instance as part of the
StatefulSet. Each pod includes its own database instance, useful for isolated environments or ephemeral test Sophora Staging Servers. - Use a dedicated Cloud SQL (external PostgreSQL) per Sophora Staging Server. Provides strict isolation and scaling flexibility, suitable for production-like environments.
- Use a shared Cloud SQL instance for a group of Sophora Staging Servers. Allows reuse of a single database instance across multiple staging nodes, reducing overhead but requiring careful data partitioning.
Prepare the strategy that best fits your operational model and scaling requirements.
Sophora Client: Changes
Sophora 6's API is based on gRPC instead of Spring Remoting. Some inefficient or otherwise outdated API methords were removed during the switch. Here's the list. Please check your custom code for the discontinued API methods.
Sophora Server: Breaking changes
With the introduction of the Document Store, there are no API changes—except for a few specific cases. From a client perspective, Sophora documents remain unchanged, even though they are now stored and accessed differently in Sophora 6. The exceptions are detailed in the table.
| Change | Type | Description |
|---|---|---|
| Exception on missing documents | Breaking | If a document can’t be found, the server now consistently throws an ItemNotFoundException for both working and live versions. Previously, methods such as getPublishedDocumentByUuid could return null. |
| XPath / JCR search | Breaking | Searches using XPath will be no longer supported. |
| SearchParameters#forceRepositorySearch | Breaking | The forceRepositorySearch option will be deprecated and ignored by the server. If used, the Client logs a warning in Sophora 6. All IQuery-based searches now require SolrCloud. Note that IQuery results may be stale due to asynchronous indexing in SolrCloud. |
| References | Breaking | There are two types of references:– UuidReferenceValue: Used when a reference can be resolved and allAsExternalReferences is set to false (default). No changes compared to Sophora 5. This type is planned for removal.– ExternalIdReferenceValue: Used when the reference cannot be resolved or allAsExternalReferences is set to true. If a corresponding document exists, its UUID is included. BREAKING: Unlike in Sophora 5, the isDeleted flag is always set to false, as this information is no longer stored in the database. |
Version saving behavior | Info | Versions are now saved asynchronously in a separate transaction. Previously, version updates occurred within the request. For example, a publish call would return only after versioning was complete. Now, the call returns as soon as the document is written to the Document Store. |
DerivedDocumentChangedEvents | Info | These events are now based on SolrCloud queries rather than JCR searches. After a change to selection values, affected documents are determined using delayed queries to ensure consistency. These events are primarily used to reindex affected documents in SolrCloud. |
Things to do
- Update to Java 21
- Replace all XPath queries: The XPath query language will be no longer supported in Sophora 6. Please replace all XPath queries in your scripts or custom tools with IQuerys or Solr queries prior to the update.
- Replace all discontinued Server and Client API methods: Sophora 6's API is based on gRPC instead of Spring Remoting. Some inefficient or otherwise outdated API methords were removed during the switch. Here's the list. Please check your custom code for the discontinued API methods.
- Install the Content API as a separate module: The Content API will be moved into a standalone Java / Spring application in Sophora 6, distinct from the Sophora Server. Please install the new application prior to the update.
