Skip to content

Docs: say that a database written by a 26.11.x wheel must not be opened with an older wheel #415

Closed

Description

@tae898

I found that the docs say nothing about opening a 26.11.x database with an older wheel, and that doing so loses data today.

Since ArcadeData/arcadedb#10904 (released in 26.11.1), a float or double array, a vector embedding included, is written in a fixed-width form (binary types 36 and 37). The setting arcadedb.serializer.fixedWidthFloatArrays is on by default; I read its default and text in GlobalConfiguration.java at the tag 26.11.1. The 26.11.1 wheels carry that engine, so they write the new form unasked.

What an older wheel does, from ArcadeData/arcadedb#12234 (measured by the reporter on 26.10.1 and 26.9.1, with 26.11.1 and with an engine build of main): it opens the database without an error, reads every array in the new form as null, never returns those records from vector.neighbors(), and the next UPDATE of such a record, even of an unrelated property, rewrites it without its arrays. Opening the database again with 26.11.1 shows them gone for good. In that test a database with a UNIQUE_HASH index was refused by 26.10.1 for another reason (page layout 3), so a refusal cannot be counted on.

What upstream changed: ArcadeData/arcadedb#12239 (commit fd18fce4, merged 2026-11-18, not in 26.11.1) labels the dictionary file of the database as format version 2 while the setting is on. A new database is created with the label and an existing one gets it at its first read-write open, whether or not it holds an array. Builds from 26.8.1 to 26.11.x refuse to open a labelled database, 26.11.1 included. Setting the setting to false before the first open by the new build keeps the files openable by an older build; turning it off later does not remove the label (the text of the setting in that commit). I found no wheel that contains the change yet.

I propose a short section on the installation page, "Open a database with an older wheel", with the safe rule: do not open a database that a 26.11.x wheel has written with a 26.10.x or older wheel, and keep a backup before upgrading. It cites the three upstream numbers, says what an older wheel does today and what the later label does, and names the system property route that the durability page already documents (jvm_args or ARCADEDB_JVM_ARGS for arcadedb-jvm, ARCADEDB_NATIVE_ISOLATE_ARGS for arcadedb). There is no static changelog in the repository, because the release notes are built from pull request titles, so the pull request title carries the one line.

What I did not verify: I did not run a downgrade myself, so every statement about older builds comes from the upstream issue and diff and not from the wheels. I did not test that the system property reaches this setting in either package. I could not build the docs site here, so the Docs workflow is the first build of the new section.

After the first wheel that is built from an engine with fd18fce4, a test is worth adding: create a vector database and check that its dictionary file name carries .v2.. I can add that when such a wheel exists, and I can also check the wording of the section against that wheel.

Activity

  1. self-assigned this
    on Nov 20, 2026
  2. added
    github_actionsPull requests that update GitHub Actions code
    jvmThe arcadedb-jvm package (JPype build)
    pythonPull requests that update python code
    vectorVector indexes and find_nearest
    on Nov 20, 2026
  3. added this to the 26.12.1 milestone on Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationgithub_actionsPull requests that update GitHub Actions codein progressThe team is actively working on this issuejvmThe arcadedb-jvm package (JPype build)pythonPull requests that update python codevectorVector indexes and find_nearest

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions