docs(26.7.2): cover release-note gaps (HA, security, sparse-vector, write-counter, Bolt)#418
Conversation
…king changes Cover the two 26.7.2 breaking changes and related HA contracts: - arcadedb.ha.raftPersistStorage now defaults to true (durable Raft storage). Correct the default in settings.adoc and the HA settings table, add ha.raftStorageDirectory to the HA table, and add a "Durable Raft Storage" section. Fix the now-stale "wiped on every restart / do not copy" guidance in upgrade.adoc (What to copy, HA cluster upgrade, Docker/Kubernetes). - Bolt temporal values (date/time/datetime/...) are now native PackStream structures instead of ISO-8601 strings. Add a breaking- change NOTE to the Bolt data type mapping and a bolt-datatypes anchor. - Add the committed-remotely response contract (TransactionCommittedRemotelyException -> HTTP 409, do not retry). - Note leader auto-recovery of a follower's replication channel after a pod-IP/DNS change. - Add 26.7.2 entries to the upgrade Breaking changes section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…tions and triggers Cover the 26.7.2 security advisories that change user-visible behavior: - Add the updateDatabaseSettings group permission (GHSA-8vr5-263f-x5r3) to groups.adoc, including the auto-migration of admin groups and the new default admin access list. - Document required privileges for DEFINE FUNCTION in sql-custom- functions.adoc: LANGUAGE js now requires updateSecurity, sql/cypher require updateSchema (GHSA-vwjc-v7x7-cm6g), plus the polyglot sandbox (IOAccess.NONE / PolyglotAccess.NONE). - Expand the JS trigger sandbox note in sql-triggers.adoc with the narrowed host-class allow-list (java.util/java.time/java.math only; java.lang.* removed) and the RCE advisory GHSA-x9f9-r4m8-9xc2. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…M_SPARSE_VECTOR The sparse vector index now exposes posting-weight quantization through the weightQuantization index METADATA key (INT8 default, FP16, FP32), at parity with the dense LSM_VECTOR quantization knob. Previously the choice was hard-wired to INT8. - sql-indexes.adoc: add weightQuantization to the LSM_SPARSE_VECTOR METADATA example and a values/trade-off table. - vector-search.adoc: remove weight quantization from the "tracked separately" future-work list and point to CREATE INDEX; fix a pre-existing typo flagged by the typos hook. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…P and gRPC The QueryStatistics write counters (nodes/relationships/properties/labels/ indexes/constraints created/removed, containsUpdates), previously only on Bolt, are now surfaced over HTTP and gRPC, with counts aggregated across UNION branches and CALL subqueries. - http.adoc: add a "Write statistics (stats)" section to the command endpoint documenting the camelCase stats object, its keys, and an example response. Emitted only for write queries. - grpc-api.adoc: document ExecuteCommandResponse and the QueryUpdateStats message (snake_case fields) with a cross-link to the HTTP shape. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Tick the box to add this pull request to the merge queue (same as
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for ArcadeDB v26.7.2, covering key changes such as configurable posting-weight quantization for sparse vector indexes, native PackStream temporal structures for Bolt clients, new database settings permissions, and stricter JavaScript sandboxing. It also documents HA improvements, including durable Raft storage by default and write statistics in HTTP/gRPC responses. The review feedback correctly points out that mounting wildcard paths like raft-storage-* is unsupported by container runtimes and Kubernetes, recommending that users configure arcadedb.ha.raftStorageDirectory to a static path instead.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
|
|
||
| Durable storage lets a restarted node rejoin by *replaying its own persisted log* rather than always requiring a full snapshot resync from the leader. | ||
|
|
||
| *Migration:* mount `raft-storage-*` (or the directory named by `arcadedb.ha.raftStorageDirectory`) on durable storage before upgrading. On Kubernetes, back it with a `PersistentVolumeClaim` — see <<kubernetes,Kubernetes>>. A throwaway or test cluster that intentionally wants ephemeral behavior can opt out with `arcadedb.ha.raftPersistStorage=false`. |
There was a problem hiding this comment.
Mounting a wildcard path like raft-storage-* is not supported by container runtimes (Docker) or Kubernetes volume mounts. Doing so will result in a literal directory named raft-storage-* being created, which will not match the actual peer directories. Instead, users should configure arcadedb.ha.raftStorageDirectory to a static path and mount that static path.
*Migration:* Configure +arcadedb.ha.raftStorageDirectory+ to a static path (e.g., /home/arcadedb/raft-storage) and mount that directory on durable storage before upgrading. (Note: Mounting a wildcard path like raft-storage-* is not supported by container runtimes or Kubernetes). On Kubernetes, back it with a +PersistentVolumeClaim+ — see <<kubernetes,Kubernetes>>. A throwaway or test cluster that intentionally wants ephemeral behavior can opt out with +arcadedb.ha.raftPersistStorage=false+.
There was a problem hiding this comment.
Correct — a dynamically-named raft-storage-<nodeName> directory cannot be mounted as a volume, which is precisely what arcadedb.ha.raftStorageDirectory exists for. Reworded the migration note to set raftStorageDirectory to a static path and mount that, keeping the plain-filesystem copy path as an alternative. Fixed in 8fec0fe.
| * Mount `/home/arcadedb/databases` on a persistent volume — this is the equivalent of "copy the `databases/` folder". | ||
| * Mount `/home/arcadedb/config` only if you have edited the files listed in <<upgrade-config-files>>; otherwise let the image ship its defaults. | ||
| * Do *not* mount `/home/arcadedb/raft-storage-*` on a persistent volume; the Raft log is ephemeral and is rebuilt from peers on every pod restart. | ||
| * Mount `/home/arcadedb/raft-storage-*` (or the path set by `arcadedb.ha.raftStorageDirectory`) on a persistent volume. Since v26.7.2 the Raft log is durable by default (`arcadedb.ha.raftPersistStorage=true`) so a restarted pod can replay its own log instead of resyncing from peers. On releases before v26.7.2, or with `raftPersistStorage=false`, the log is ephemeral and this mount is unnecessary. |
There was a problem hiding this comment.
Mounting a wildcard path like /home/arcadedb/raft-storage-* is not supported by container runtimes (Docker) or Kubernetes volume mounts. Doing so will result in a literal directory named raft-storage-* being created, which will not match the actual peer directories. Instead, users should configure arcadedb.ha.raftStorageDirectory to a static path and mount that static path.
* Mount +arcadedb.ha.raftStorageDirectory+ (configured to a static path, e.g., /home/arcadedb/raft-storage) on a persistent volume. (Note: Mounting a wildcard path like /home/arcadedb/raft-storage-* is not supported by container runtimes or Kubernetes). Since v26.7.2 the Raft log is durable by default (+arcadedb.ha.raftPersistStorage=true+) so a restarted pod can replay its own log instead of resyncing from peers. On releases before v26.7.2, or with +raftPersistStorage=false+, the log is ephemeral and this mount is unnecessary.
There was a problem hiding this comment.
Correct for the container case. Changed the Docker/Kubernetes bullet to set arcadedb.ha.raftStorageDirectory to a static path and mount that path, and noted that the raft-storage-* wildcard is created literally rather than expanded. Fixed in 8fec0fe.
… Raft mounts Address review: a dynamically-named raft-storage-<nodeName> directory cannot be mounted as a Docker/Kubernetes volume (a raft-storage-* wildcard is created literally, not expanded) — which is exactly why arcadedb.ha.raftStorageDirectory exists. Update the durable-storage migration note (ha.adoc) and the Docker/Kubernetes upgrade bullet (upgrade.adoc) to set raftStorageDirectory to a static path and mount that, while keeping the plain-filesystem "copy the directory" path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 participant
Summary
Documents the user-facing changes introduced in ArcadeDB 26.7.2 that were missing from the docs. Every new fact was verified against the ArcadeDB source at tag
26.7.2(enum names, JSON/proto field names, METADATA keys, allow-lists) rather than paraphrased from the release notes.Organized as four focused commits.
1. HA durable Raft storage & Bolt temporal — breaking changes (
45dfe42c)arcadedb.ha.raftPersistStoragenow defaults totrue: corrected the default insettings.adocand the HA settings table, addedraftStorageDirectoryto the HA table, and a new Durable Raft Storage section.upgrade.adoc(What-to-copy, HA cluster upgrade, Docker/Kubernetes).TransactionCommittedRemotelyException→ HTTP 409, do not retry) and the leader auto-recovery of a follower's replication channel after a pod-IP/DNS change.upgrade.adocbreaking-change entries.2. Security hardening (
6bd4a9be)updateDatabaseSettingsgroup permission (GHSA-8vr5-263f-x5r3), incl. the admin-group auto-migration.DEFINE FUNCTION ... LANGUAGE jsnow requiresupdateSecurity; sql/cypher requireupdateSchema(GHSA-vwjc-v7x7-cm6g); documented the polyglot sandbox (IOAccess.NONE/PolyglotAccess.NONE).java.util/java.time/java.math(java.lang.*removed — GHSA-x9f9-r4m8-9xc2).3. Sparse-vector posting-weight quantization — #5143 (
89dadf0f)weightQuantizationMETADATA key (INT8default,FP16,FP32) onLSM_SPARSE_VECTOR; removed it from the "future work" list invector-search.adoc.4. Cypher write-counter (
stats) over HTTP & gRPC — #5015 (d43e533a)/commandWrite statistics section (camelCasestatsobject, 11 counters +containsUpdates, emitted only for writes).ExecuteCommandResponse/QueryUpdateStatsmessage (snake_case), cross-linked to the HTTP shape.Note on scope
The release bullet "Point datatype and spatial index (#3401)" is not a doc gap: the engine added no new
TypeorINDEX_TYPE(the enum is unchanged), and #3401 was closed against the existing WKTGEOSPATIALindex +geo.*functions, already documented ingeospatial.adoc. No nativePointtype was invented. Internal engine-audit fixes, parallel-scan/async fixes and dependency bumps have no user-facing surface and are intentionally not documented.Verification
docs-validator.pypasses: filenames, anchors, and all cross-references valid.typos).🤖 Generated with Claude Code