1.8.0 shared-foundation migration

The 1.8.0 shared-foundation migration changes Java imports and extension signatures, and requires Server, PD and Store to upgrade together. Use this guide to identify affected code, rebuild your integrations and check existing data before deployment.

Find the work that applies to you

This shared-foundation consolidation targets HugeGraph 1.8.0. Use matching Server, PD, Store and downstream artifacts when upgrading. See the source migration guide for Java mappings and compatibility fixtures.

Where shared code now lives

Server core and struct previously carried separate implementations of several IDs, schema types, queries, elements and codecs. The migration gives these shared types one owner so Server and Store can use the same implementation. hugegraph-core continues to run the graph engine, hugegraph-struct supplies shared models and codecs, and hugegraph-common supplies utilities.

Core retains graph execution and adapters, Store retains storage and schema lifecycle, and struct/common own the shared implementations. The arrows show shared ownership, not the full dependency tree.

The Server HStore adapter still needs PD and Store clients. Store retains its network, PD client and storage libraries. PD and Store must not depend on core, and struct must not depend on core or PD clients.

Core and Store implement HugeGraphSupplier to provide schema, configuration and clock access. Shared base elements hold state and adjacency. HugeVertex and HugeEdge retain engine behavior and wrapper identity over that same state; property mutation, cloning, removal, expiration and loading state must propagate through it. Core serializers retain backend adapters and delegate shared encoding. Shared index and OLAP selection receive schema candidates and result sinks from their callers; core keeps transaction writes and backend capability checks.

Update Java source and SPI implementations

Start with the types your code imports. This ID construction call keeps the same string value while its imports move.

Before, using the 1.7.0 core API

1import org.apache.hugegraph.backend.id.Id;
2import org.apache.hugegraph.backend.id.IdGenerator;
3
4Id vertexId = IdGenerator.of("vertex-1");

After, using the shared API

1import org.apache.hugegraph.id.Id;
2import org.apache.hugegraph.id.IdGenerator;
3
4Id vertexId = IdGenerator.of("vertex-1");

Recompile the application and its plugins after adapting source. Relocated types also change method descriptors, so editing imports cannot make an old compiled jar binary-compatible. Removed core classes have no general compatibility package. The plugin examples still describe 1.7.0; apply the following mappings when targeting the migrated API.

Only Id, IdGenerator, EdgeId, IdUtil and SplicingIdGenerator move from the ID package. SnowflakeIdGenerator remains in core under org.apache.hugegraph.backend.id; retain its existing import. The moved query types are Query, ConditionQuery, Condition, IdQuery, IdPrefixQuery, IdRangeQuery, BatchConditionQuery and Aggregate. QueryResults, ConditionQueryFlatten, EdgesQueryIterator, QueryBatch and QueryResultContext remain in core under org.apache.hugegraph.backend.query; retain their existing imports.

SchemaManager, schema mutation builders and backend-specific serializers remain in core, so apply these mappings only to affected types. Client REST DTOs remain independent, including Toolchain’s org.apache.hugegraph.structure.graph.Shard.

Keep element adapters on the shared state; do not restore removed engine state fields or add a second adjacency collection. For Gremlin classImports and scripts, replace org.apache.hugegraph.backend.id.IdGenerator with org.apache.hugegraph.id.IdGenerator. Configuration-only class names need a packaged Gremlin startup check; Java compilation does not exercise them.

The RPC interfaces org.apache.hugegraph.rpc.RpcServiceConfig4Client and RpcServiceConfig4Server now have one owner in common. Their names and signatures stay the same, so this move requires no RPC import or configuration change. org.apache.hugegraph.auth.TokenGenerator also belongs to common. Callers supply the signing secret and map JWT failures to their service responses. Common’s JWT dependencies are optional; direct JWT consumers must declare their required libraries.

Adapt downstream exceptions when matching artifacts are available

Update constructors and catch clauses along with imports. HubbleException keeps its RuntimeException parent and string constructor. ClientNotSupportException keeps its ClientException parent and message/cause and message/arguments constructors. Computer’s HgkvDirImpl is one affected client-exception caller. Struct’s similarly named exceptions have different contracts. Loader’s REST boundary and independent client DTOs do not need an overall conversion to struct.

The Toolchain and Computer changes are still unpublished downstream handoffs. They need matching publication, builds and packaged-classpath checks. Inspect the built jars as well as the source tree for stale or transitive copies of the same class.

Prepare a coordinated service upgrade

Upgrade Server, PD and Store together to matching release artifacts. This migration does not support mixed-version rolling upgrades. The sequence below applies once those matching artifacts are available.

Back up data/configuration and check affected indexes, update imports/SPI and recompile, then upgrade matching services and align the PD namespace. Verify packaged services and graph reads/writes. OLAP keys change from one row per vertex to one row per property and vertex; matching legacy rows remain readable, overwritten values cannot be recovered, and mixed-version rolling upgrades are unsupported.

1. Back up graph data with the existing backup and restore procedure and preserve deployment configuration.
2. Prepare matching Server, PD and Store artifacts, plus rebuilt plugins and any required downstream integrations.
3. Align the metadata namespace using the settings below; preserve existing backend graph names.
4. Rehearse in a validation environment. Start the packaged services, read historical data and exercise affected queries and writes.
5. Pause writes for the coordinated deployment upgrade. Resume only after all Server and Store writers use matching artifacts and checks pass.

The consolidation does not automatically rewrite graph data, rebuild indexes or recover historical entries. Review the compatibility cases below during the rehearsal.

Match the PD metadata namespace

Store’s pd.cluster defaults to hg. Set it in Store application.yml as follows.

1pd:
2  cluster: hg

The equivalent environment variable is PD_CLUSTER.

This namespace covers schema, graph configuration, cache watches and TTL-cleaner metadata. All HStore graphs in one Server process must use the same metadata namespace. With usePD=false, the first HStore graph opened binds the process-wide MetaManager to its pd.cluster. A later graph’s explicit conflicting pd.cluster is logged and ignored; it does not create an independent namespace. One Store process cannot share a schema driver across conflicting namespaces. Preserve backend graphspace/store/table names such as DEFAULT/hugegraph/g; the REST identity DEFAULT-hugegraph is not a metadata key.

Check data compatibility

The core SYSTEM-label writer keeps its existing bytes. This migration adds no TTL suffix to those keys and does not change prefix deletion. Previously unsupported index-only element reconstruction remains unsupported.

Element classification also keeps the producer context through BaseVertex.TypeContext.

Engine wrappers select ENGINE; standalone storage elements retain STORAGE so table routing follows the existing behavior.

Rebuild affected legacy long-text indexes

The previous Store-side IndexBuilder shortened long text values to 20 characters. Server queries used the full value and its hash. The shared builder now follows the Server contract. An old shortened row can still be decoded, but it does not automatically match a full-value query.

If your deployment used Store-side index rebuilding, identify affected indexes and rebuild them from graph data where necessary. The migration performs no automatic rebuild and cannot recover missing historical entries. Ordinary Server-created index keys retain their existing contract.

Verify HStore OLAP reads and deletes

New OLAP rows use [property ID][vertex ID] keys, allowing several OLAP properties on one vertex to coexist. Legacy rows used only the vertex ID; their values remain readable without a rewrite.

Upgrade all Server and Store writers before resuming writes. An old writer can update a legacy row while a new reader prefers an existing compound row. Mixed-version OLAP writes are outside the supported upgrade contract.

Verify packaged services and integrations

Run affected Java/SPI tests, then exercise RocksDB and HStore queries, authentication, Store schema/filter behavior and shared element state propagation. Include historical ID, schema, property and index samples, pagination, TTL and OLAP cases. Inspect resolved dependencies and shipped jars for forbidden module dependencies or duplicate HugeGraph classes, and start the actual packaged services without classpath-ordering workarounds. The contribution guide describes build and dependency-inventory prerequisites.

The implementation, website documentation and downstream artifacts need coordinated publication. Use matching artifacts and their runtime results to decide when to adopt the migration; compiling source or skipping tests is insufficient.