4.0.0

CogDB 4.0.0

CogDB 4.0 is a ground-up rebuild of the storage engine, focused on speed, crash safety, and predictable on-disk behavior.

Spindle storage format (On-disk format change - BREAKING)

The 3.x marshall-based format is replaced by Spindle, a compact binary, length-addressable record format:

• mmap-backed reads and an in-memory traversal cache — significantly faster gets and graph traversals
• Values are stored with typed binary tags; embeddings are packed as fixed-width float64 arrays
• Every record is length-prefixed, so payloads can contain any byte sequence (the 3.x separator-byte corruption class is gone by construction)

Strict value types (breaking)

4.0 defines the value domain explicitly: str, int (int64), float, bool, bytes, and numeric lists (persisted as float64 arrays — int elements widen to float, matching embedding semantics). Anything else (dict, None, tuples, mixed lists, ints beyond int64) now raises ValueError at write time instead of being silently stringified. What you read back is always exactly what was stored.

Migrating from 3.x

3.x databases must be migrated once:

from cog.migrate import migrate

stats = migrate("/path/to/cog-home")   # your COG_HOME / CUSTOM_COG_DB_PATH
print(stats)                            # errors list is empty on success

Migration is built to be safe to run on real data:

• All-or-nothing: a pre-flight pass verifies every record first; if anything can't be represented, all problems are reported and nothing is converted
• Faithful: deleted keys stay deleted, updated keys resolve to their newest value, graph edges remain traversable
• Reversible: originals are kept as .v3_backup files until you pass remove_backups=True