Migrating GraphDB configurations

To migrate from one GraphDB version to another, follow the instructions in the last column of the table below, and then the steps described further down in this page.

Compatibility between the versions of GraphDB, Connectors, and third-party connectors

GraphDB

RDF4J

Connectors

Elasticsearch

OpenSearch

Lucene

Solr

Kafka

11.5.x

5.3.1

16.7.0

9.1.3

3.1.0

10.4.0

9.4.1

Solr connector will be removed in GraphDB 12.

3.9.2

GraphDB 11.5 changes the terminology used in the user roles and permissions mechanism, introducing the concept of additional permissions, which were previously known as repository access roles. Since this change is only with the names of these concepts and the underlying security mechanism has not been altered or affected in any way, no special attention or additional actions are required.

The Lucene connector has been updated to the current latest official version 10.4.0. If your Lucene connector was created with Lucene 8 (in other words, if your Lucene connector was created under GraphDB 10.8 or an earlier version), it must be recreated.

The repositories/<repo_name>/health no longer show YELLOW status if there are long running queries. In addition to that, a cluster configuration where one or more of the nodes are syncing no longer results in the cluster health being shown as YELLOW in the Workbench. These changes do not require special attention by default but may affect existing workflows.

GraphDB 11.5 is the last version that supports the Solr connector, which has been deprecated since GraphDB 11.4.0 and will be removed in GraphDB 12. No special actions are required at the moment, but if you are using Solr, please contact us via the available support channels to discuss the alternatives.

11.4.x

5.2.2

16.7.0

9.1.3

3.1.0

9.12.0

9.4.1

Solr connector will be removed in GraphDB 12.

3.9.2

Starting with GraphDB 11.4, the Assistants API is no longer supported and Talk to Your Graph will be unusuable if graphdb.llm.api is set to openai-assistants. The Assistants API will be officially deprecated by OpenAI on 26 August 2026. The default value for graphdb.llm.api — the property which configures the LLM model used by GraphDB — is now openai-completions.

You can automatically migrate existing Talk to Your Graph agents and conversations that use the Assistants API. When graphdb.llm.api is set to openai-assistants, GraphDB automatically converts the agents and conversations into an internal format compatible with the Completions API and are persisted locally in the GraphDB data directory. This conversion is possible only before the official shutdown of OpenAI Assistant API on 26 August. Once converted, agents and conversations will be accessible once graphdb.llm.api is set to openai-assistants .

Note

When doing the migration GraphDB respects configuration properties, such as graphdb.ttyg.installation.id, graphdb.openai.project, graphdb.openai.organization, and only agents visible to this GraphDB instance will be converted.

On every subsequent restart before August 25, 2026, the system checks for and retrieves any new agents. The default behavior is to migrate the agents without deleting them from the Assistant API. You can customize this behavior using the property graphdb.ttyg.migration.mode and the following values:

  • copy: copies agents and conversation from Assistant API to the Completions API without deleting them from the Assistants API.

  • move: migrates agents and conversation from Assistant API to the Completions API and deletes them from the Assistants API. Since Assistants API agents are stored in OpenAI and shared between GraphDB instances with the same API Key, deleting the agents from the Assistants API means deleting them for all instances using this key.

  • none: no migration of agents and conversations occurs.

After the deprecation date, you must rely entirely on previously persisted data.

11.3.x

5.2.2

16.6.0

9.1.3

3.1.0

9.12.0

9.4.1

3.9.1

Starting with GraphDB 11.3, the default transport mode used by the MCP server is now streamable HTTP transport, in accordance with the changes to the MCP protocol. Communication through the transport is now done through HTTP POST and GET requests. SSE transport, which was the default mode prior to GraphDB 11.3, is still supported, and can be enabled through the graphdb.mcp.transport.mode configuration property. For more information, check the Using GraphDB’s LLM tools with MCP clients documentation, as well as the list of MCP server properties.

GraphDB 11.3 fixes an issue with the op:subtract-dates operations. Prior to GraphDB 11.3, when calculating the substraction of two dates, GraphDB returned type of xs:duration, which is incompliant with the W3C specification on XPath and XQuery Functions and Operators. These operations should now return xs:dayTimeDuration as prescribed by the SPARQL specification.

The following endpoints in RecoveryController which were deprecated in GraphDB 10.8 have now been removed:

  • @GetMapping(value = "/backups")

  • @GetMapping(value = "/backups/{name}")

  • @PostMapping(value = "/backups/{name}")

  • @PutMapping(value = "/backups/{name}")

  • @DeleteMapping(value = "/backups/{name}")

  • @PostMapping(value = "/cloud-restore", consumes = "application/json")

  • @PostMapping(value = "/cloud-backup", consumes = "application/json")

  • @PostMapping(value = "/restore/{name}")

Starting with version 10.8, the backupOptions object is no longer supported. Users must move its properties to the top level of the request payload. Before 10.8:

{
    "backupOptions": {
        "backupSystemData": true
    },
    "bucketUri": "s3:///<bucket-name>/<backup-name>?region=<region>&ACCESS_KEY_ID=<key-id>&_ACCESS_KEY=<key>"
}

From 10.8 onward:

{
    "backupSystemData": true,
    "bucketUri": "s3:///<bucket-name>/<backup-name>?region=<region>&ACCESS_KEY_ID=<key-id>&_ACCESS_KEY=<key>"
}

Users should update their requests accordingly, as the backupOptions wrapper is no longer recognized.

The default value for graphdb.ttyg.model.context.window.size in GraphDB 11.3 has been changed from 128,000 to 1,000,000.

11.2.x

5.1.6

16.5.0

9.1.13

3.1.0

9.12.0

9.4.1

3.9.1

GraphDB 11.1 fixes an issue where SHACL constraints might not be replicated across the cluster, leading to inconsistencies or missing constraint enforcement on follower nodes. Since the default RDF4J SHACL graph cannot be queried using SPARQL, you can verify whether this problem affects you navigatin to the Graphs overview view and selecting the default RDF4J SHACL graph. If there was a leader change and new shapes were added the shapes graph could be filled with different shapes.

Before upgrading to GraphDB 11.2, to ensure all SHACL constraints are replicated and active on all nodes, you need to follow the steps below:

  1. Before upgrading, delete your cluster in the previous version of GraphDB

  2. For each of the nodes, export the content of the default SHACL graph in that node

  3. Delete the default SHACL graph on all of the nodes

  4. Upgrade the instances to GraphDB 11.2 version

  5. Recreate the cluster on GraphDB 11.2

  6. Import all exported SHACL graphs back into the cluster checking the Preserve bNode Ids

This will guarantee that the SHACL shapes are now replicated across all nodes. If any duplicates exist, no issues occur, as the system is idempotent. The refresh flag is automatically triggered, so preloaded shapes are active.

The names of two properties that configure the truststore were changed in GraphDB 11.2:

  • graphdb.connector.truststoreFile is now graphdb.connector.ssl.truststoreFile

  • graphdb.conector.truststorePass is now graphdb.connector.ssl.trustorePassword

If your deployment is using either of these properties, you need to update your configuration file to reflect this change and use the new property names.

GraphDB 11.2 fixes an issue where X.509 client certificate authentication was not functioning correctly from version 11.0. This means that users relying on X.509 based authentication may experience failed client authentication after upgrading from GraphDB 10 to 11. To avoid this issue, users upgrading from version 10 who depend on X.509 support must upgrade directly to GraphDB 11.2 or later, where the functionality is restored.

As of RDF4J 5.1.6, the SPARQL TSV writer adheres more strictly to the official TSV specification. Unlike CSV, the TSV format requires IRIs, blank nodes, and literals to be encoded following Turtle rules. Previously, RDF4J produced unquoted xsd:string literals, but from 5.1.6 onward all literals are output using quotation marks. This change may affect users who rely on the old unquoted literal format.

Warning

Due to a known bug in GraphDB 11.2 and 11.3, a cluster cannot be created if the properties graphdb.connector.ssl.truststoreFile and graphdb.connector.ssl.truststorePassword are configured through the graphdb.properties file. This behavior is not intentional and will be fixed in GraphDB 11.3.3.

You can still create a cluster if you pass those configuration properties as JAVA arguments: -Djavax.net.ssl.trustStore=<path-to-truststore> -Djavax.net.ssl.trustStorePassword=<password> instead of having them in the graphdb.properties file. We recommend using this workaround until this bug is fixed.

11.1.x

5.1.4

16.4.0

9.0.2

3.1.0

9.12.0

9.4.1

3.9.1

GraphDB 11.1 enhances the Talk to Your Graph feature and other mechanisms that use Large Language Models (LLMs) to support alternatives to OpenAI LLMs. As a result, several configuration properties related to those mechanisms have been deprecated and replaced with new properties:

  • graphdb.llm.api is a new property that configures the LLM API that will be used by GraphDB.

  • graphdb.openai.api-key has been replaced by graphdb.llm.api-key.

  • graphdb.openai.url has been replaced by graphdb.llm.url.

  • graphdb.openai.auth has been replaced by graphdb.llm.auth.

  • graphdb.llm.model is a new property that configures the default LLM model for TTYG and GPT functions and SPARQL explain.

While we strongly suggest updating your configuration properties to reflect those changes, the deprecated properties are still supported. For more information, check the configuration properties documentation section in Talk to Your Graph and LLM properties.

GraphDB no longer supports non-global cache. As a result, graphdb.global.page.cache has been deprecated and has no effect.

The verificationTimeout configuration property used by the cluster mechanism has a new default value of 300 (it was previously 1500). This does not affect already existing cluster configurations.

GraphDB 11.1.1 fixes a bug which caused a fingerprint mismatch when using connectors. Since the issue can leave invalid data in dynamic_settings.json, it is advised to recreate and reindex the connector instances to the indexing of unrelated documents.

11.0.x

5.1.2

16.3.1

8.14.3

2.18.0

9.12.0

9.4.1

3.9.0

GraphDB 11 comes with a higher Java version requirement (Java 21). You need to upgrade your version of Java to Java 21.

GraphQL support is now part of GraphDB 11. It was previously supported in Semantic Objects. If you want to migrate from Semantic Objects to GraphDB 11, check the Migrating GraphQL configurations from Semantic Objects to GraphDB documentation.

GraphDB 11 now uses Logback 1.5, which affects the format of the logback.xml file:

  • In configuration files, <if> elements can no longer be nested within an <appender>, <logger> or <root> elements.

  • <jmxConfigurator /> was removed from Logback and is no longer supported in GraphDB.

Some GraphDB configuration properties have been deprecated and replaced with new ones:

  • default.min.distinct.threshold has been deprecated and replaced by graphdb.query.memory.threshold.

  • Due to the migration to Tomcat 11.0.5, some network configuration properties have been renamed. Check the Network properties documentation for full information on those properties.

  • SSL can now be enabled with a single property graphdb.connector.ssl.enabled. Setting this property to true is equal to this configuration used in versions prior to GraphDB 11:

    graphdb.connector.SSLEnabled = true
graphdb.connector.scheme = https
graphdb.connector.secure = true

Starting with GraphDB 11, subtree search is available and enabled by default for both users and roles. Previously, subtree search was available by default only for users, without an option to control it. For more information, check the LDAP user database documentation.

The following licensing and feature changes affect GraphDB Free:

  • License requirement: The built-in license for GraphDB Free has been removed. Users upgrading to GraphDB Free 11 must request a free license from the Graphwise website and manually install it before use.

  • Repository limit: GraphDB Free now supports up to 5 repositories.

  • Authentication and Authorization: LDAP, OpenID/OAuth, Kerberos, and X.509 authentication and authorization methods are no longer available in GraphDB Free.

  • Entity ID restriction: Support for 40-bit entity IDs has been removed.

All these features remain available in GraphDB Enterprise and GraphDB Standard.

If you are upgrading from GraphDB 10.x or older, please upgrade to GraphDB 10.8 before you upgrade to GraphDB 11.0.

See compatibility for GraphDB versions 10.x and older.

Migrating GraphDB

To migrate your GraphDB configuration and data, follow the steps below.

Warning

Keep in mind that after that, you cannot automatically revert to GraphDB 10.x.

  1. Stop the GraphDB 10.x instance.

  2. Back up your repositories and configuration — this will ensure you can revert safely if something goes wrong during the upgrade.

    1. To back up all repositories, copy the data directory. See also Backing up and Restoring a Repository for additional ways to backup repository data.

    2. To back up all configuration, copy the work and conf directories.

  3. Your existing GraphDB 10.x home directory (containing the conf, data, and work directories) can be used directly as the GraphDB 11.0 home directory.

    Tip

    You can also copy the conf, data, and work directories from the GraphDB 10.x home directory to a new directory to use as the GraphDB 11.0 home directory. In this case, your GraphDB 10.x home directory is also the backup so you may skip the backup steps.

    The various directories are described in detail in the Structure of the distribution package section.

  4. Start GraphDB 11.0.

Migrating plugins in a cluster

When upgrading to a newer GraphDB version, it might contain plugins that are not present in the older version. In this case, and when using a cluster, the Plugin Manager disables the newly detected plugins, so you need to enable them by executing the following SPARQL query:

insert data {
    [] <http://www.ontotext.com/owlim/system#startplugin> "plugin-name"
}

Then create your plugin following the steps described in the corresponding documentation, and also make sure to not delete the database in the plugin you are using.

You can also stop a plugin before the migration in case you deem it necessary:

insert data {
    [] <http://www.ontotext.com/owlim/system#stopplugin> "plugin_name"
}