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. Please note, that Sophora 6 requires PostgreSQL 17 or newer.
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 methods 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. |
| 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. |
XPath / JCR search
Searches using XPath will be no longer supported.
In versions up to and including Version 5, IQuerys could be mapped to either XPath or Solr queries.
XPath queries were executed using the Jackrabbit internal Lucene index, which is always up to date. But Solr might be outdated by a couple of seconds.
This affects, for example, use cases where a query is executed immediately after a DocumentChangedEvent. If the query is performed on Solr, it might not see the content change that triggered the DocumentChangedEvent. IQuerys are still possible, but they are always executed on Solr.
Please make sure to migrate all XPath queries to Solr queries and to review all implementations that rely on com.subshell.sophora.api.search.SearchParameters#forceRepositorySearch, since this boolean is ignored from Version 6 onward.
Please make sure to update all QuerySelectValues to use SoQL instead of XPath.
Adopt all your ITimingActionScript implementations to use the method getAdditionalIQuery instead of getAdditionalXPath.
gRPC is now the main communication protocol between the server and clients
In Version 6, the server supports both the legacy HTTP protocol (default port: 1196) and the new gRPC protocol (default port: 2026). Clients in Version 5 can still work with a Version 6 server by using the HTTP protocol. However, clients in Version 6 rely on the new gRPC port. Therefore, the gRPC port must be made available for them, and connection URLs must be adapted accordingly.
Things to do
- Update to Java 21
- Update PostgreSQL to version 17 oder later.
- 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.
- Before you begin the update, ensure that you're using sisi version 5.3.0 or later and server version 5.7.0 or later.
