{"slug": "show-hn-relational-to-kv-ai-maps-relational-models-to-toplingdb-rocksdb", "title": "Show HN: Relational-to-KV – AI maps relational models to ToplingDB/RocksDB", "summary": "A new open-source project, Relational-to-KV, provides an AI coding skill and cross-agent plugin that maps relational models directly onto ToplingDB/RocksDB key-value stores, avoiding the RDBMS abstraction tax. The project, delivered for Cursor, Claude Code, and Codex, codifies the manual KV-mapping expertise used by blockchains like Sui, Aptos, and NEAR, enabling AI agents to generate consistent, migration-aware storage code without ad-hoc key layouts.", "body_md": "This project transforms relational models into explicit KV models that run directly on [ToplingDB](https://github.com/topling/toplingdb) / RocksDB, avoiding the RDBMS (relational database) abstraction tax.\n\nIt is delivered as an AI coding skill and cross-agent plugin, not an ORM, SQL compatibility layer, or runtime library. The skill gives Cursor, Claude Code, and Codex the same rules and templates so an agent can generate storage code without inventing key layouts ad hoc.\n\nIn real products, the hard part is not `Put`\n\n/`Get`\n\n. It is what happens after entities, relationships, and indexes pile up: how keys are split, ordered, range-deleted, migrated, and kept operable for years. Ad-hoc design, or AI left to freestyle, often ships a layout that runs today and needs a rewrite in six months.\n\nManually mapping data models made up of entities, relationships, and indexes to KV, with no SQL layer in between, has long been common practice in production systems. Popular public blockchains such as [Sui](https://github.com/MystenLabs/sui), the [Move](https://move-language.github.io/move/)-based [Aptos](https://github.com/aptos-labs/aptos-core), and the sharded [NEAR](https://near.github.io/nearcore/architecture/storage/database.html) derive their exceptional performance from this very approach. In fact, a look at their code shows that their data models are standard relational models, yet they all independently translate those relational models into KV by hand and store them in RocksDB.\n\nIn the past, this approach to mapping relational models directly onto KV stores was expensive to develop: key spaces, encoding, consistency, and pruning all had to be designed by hand, putting it within reach only of projects that could afford dedicated storage teams. Today, this project codifies that expertise as an AI coding skill, enabling agents to follow consistent rules and deliver designs and implementations that once required storage specialists.\n\n- Inventory the entities, identifiers, relationships, indexes, ownership, retention, and consistency constraints in the relational model.\n- Enumerate the required point lookups, prefix scans, ranges, writes, and deletes. Access patterns—not the existing SQL tables alone—determine the KV model.\n- Derive the primary, relationship, reverse, and secondary-index key spaces; fix each key's field order and scan boundaries.\n- Assign logical key-space identities, then choose keyPrefix or an intentional CF namespace without mixing logical identity with physical placement.\n- Define a bytewise-ordered business-key encoding and generate matching bounded encode/decode code for every key shape.\n- Map logical key spaces to RocksDB column families and engine options, adding SidePlugin configuration for ToplingDB targets. Then specify atomic update groups, pruning, range deletion, and migration rules.\n- Review the access patterns and key-space contract before accepting generated code or engine configuration.\n\nGenerated storage designs use the default `BytewiseComparator`\n\n, so every key preserves its intended order under `memcmp`\n\n. Scalar keys remain the default; composite keys are introduced only when an access pattern needs multiple ordered fields. Floating keys use the FoundationDB tuple-layer transform and preserve IEEE 754 `totalOrder`\n\n, so `-0.0`\n\nand `+0.0`\n\nremain distinct unless the application normalizes them before encoding.\n\nUse this project when the domain is naturally described with entities and relationships, the production data should live directly on ToplingDB / RocksDB, and point, prefix, and range access must remain predictable. It is especially useful when performance matters and AI-generated storage code must remain reviewable and migration-aware.\n\nIt is not a drop-in replacement for arbitrary SQL queries, an automatic data migrator, or a reason to force every relational workload onto embedded KV.\n\nInstall the plugin or personal skill for your coding agent. Then provide the domain model, required access patterns, consistency rules, deletion/retention requirements, and current ToplingDB / RocksDB constraints. For example:\n\n```\nUse the $relational-to-kv skill to design this model for ToplingDB.\nStart from the listed read/write/scan/delete access patterns,\nthen produce the Key Space Catalog, key code, CF layout,\nconsistency/pruning plan, and migration notes.\n```\n\nReview the access-pattern decisions and Catalog first; only then accept the generated encoding and engine configuration.\n\nFor RocksDB targets, use the same workflow and deliver RocksDB column-family and Options configuration instead of SidePlugin configuration.\n\n**As a plugin (recommended)** — official local path `~/.cursor/plugins/local`\n\n([docs](https://cursor.com/docs/plugins.md#test-plugins-locally)):\n\n```\ngit clone https://github.com/rockeet/relational-to-kv.git\nln -sfn \"$PWD/relational-to-kv\" ~/.cursor/plugins/local/relational-to-kv\n```\n\nThen restart Cursor or run **Developer: Reload Window**. Manage under **Customize**.\n\n**As a personal skill** (flat skill folder):\n\n```\nln -sfn \"$PWD/relational-to-kv/skills/relational-to-kv\" ~/.cursor/skills/relational-to-kv\n```\n\nPoint Claude Code at the plugin root (`--plugin-dir`\n\nor plugin manager). Manifest is `.claude-plugin/plugin.json`\n\n; skills stay under root `skills/`\n\n([docs](https://code.claude.com/docs/en/plugins)).\n\n```\ngit clone https://github.com/rockeet/relational-to-kv.git\nclaude --plugin-dir \"$PWD/relational-to-kv\"\n```\n\nOr install via Claude Code’s plugin manager from this repository. Invoke as `/relational-to-kv:relational-to-kv`\n\n(plugin namespace + skill folder name).\n\nOptional personal skill symlink:\n\n```\nln -sfn \"$PWD/relational-to-kv/skills/relational-to-kv\" ~/.claude/skills/relational-to-kv\n```\n\nManifest is `.codex-plugin/plugin.json`\n\n; only that file belongs under `.codex-plugin/`\n\n. Skills live under root `skills/`\n\n([docs](https://developers.openai.com/codex/plugins/build)).\n\n```\ngit clone https://github.com/rockeet/relational-to-kv.git\n# Install / enable via Codex Plugins UI, or symlink into your local plugin source\n```\n\nOptional personal skill symlink:\n\n```\nln -sfn \"$PWD/relational-to-kv/skills/relational-to-kv\" ~/.codex/skills/relational-to-kv\n```\n\n| Deliverable | Contents |\n|---|---|\n| Key Space Catalog | One reviewed inventory of entities, relationships, indexes, namespaces, and key-space IDs where applicable |\n| Key schema and C++ code | Ordered business-key fields, memcmp-safe encoding, bounded EncodeKey/DecodeKey, and user-key assembly |\n| CF and engine configuration | Explicit mapping from logical key identity to physical CFs; CF / Options for RocksDB, plus SidePlugin configuration for ToplingDB |\n| Consistency and pruning plan | Atomic update groups, reverse indexes, range-delete boundaries, retention, and migration notes |\n\nThe human remains responsible for business semantics and access-pattern choices. The agent makes those decisions explicit and implements the resulting contract consistently.\n\n| File | Role |\n|---|---|\n`skills/relational-to-kv/SKILL.md` |\nEntry / router (English; loaded by agents) |\n`encoding.md` |\nFramework / Scalar / Composite encoding |\n`patterns.md` |\nP1–P8, AP1–AP12, namespace trade-offs |\n`templates.md` |\nDeliverable templates |\n`examples.md` |\nGolden-path examples |\n`reference.md` |\nToplingDB / SidePlugin / memcmp_coding paths |\n\nChinese human-readable copies: `*.zh.md`\n\n(content preserved; cross-linked to English).\n\n```\nrelational-to-kv/\n├── plugin.json                      # Agent Plugins (Cursor loads this)\n├── .cursor-plugin/plugin.json       # Cursor Plugin manifest\n├── .claude-plugin/plugin.json       # Claude Code manifest (only file in that dir)\n├── .codex-plugin/plugin.json        # Codex manifest (only file in that dir)\n├── skills/\n│   └── relational-to-kv/\n│       ├── SKILL.md                 # English entry (agent)\n│       ├── *.md                     # English child docs\n│       └── *.zh.md                  # Chinese copies for human readers\n├── tests/                            # Repository-level unit and contract tests\n│   ├── cpp/                          # Encoding helpers + C++ unit tests\n│   ├── test_repository.py            # Manifests, links, docs/API contract\n│   └── run_tests.sh                  # Local test entry point\n├── README.md\n├── README.zh.md\n└── LICENSE\n```\n\nPlatform references:\n\n- Cursor / Agent Plugins:\n[Plugins](https://cursor.com/docs/plugins.md),[Agent Plugins authoring](https://agent-plugins.org/plugin-authors) - Claude Code:\n[Plugins](https://code.claude.com/docs/en/plugins),[Plugins reference](https://code.claude.com/docs/en/plugins-reference) - Codex:\n[Build plugins](https://developers.openai.com/codex/plugins/build),[Package your plugin](https://developers.openai.com/plugins/build/plugins)\n\nTests live at repository root, outside the skill folder, so test-only material is never loaded into an agent's skill context.\n\n```\n./tests/run_tests.sh\n```\n\nThe runner recompiles the required Topling-zip sources instead of linking stale objects. It checks bounded raw-buffer memory-block round trips, the DataIO `as_memcmp`\n\nstream contract, and byte equivalence between them, runs ASan/UBSan builds, then checks manifests, Markdown links, bilingual structure, and documented APIs.\n\nThe test runner does not assume a machine-specific `~/osc/toplingdb`\n\ncheckout.\n\n-\nTo use an existing full ToplingDB working tree, pass its root explicitly. The runner reads\n\n`${TOPLINGDB_ROOT}/sideplugin/topling-zip`\n\nand never fetches or modifies that checkout:\n\n```\nTOPLINGDB_ROOT=/path/to/toplingdb ./tests/run_tests.sh\n```\n\n-\nIf\n\n`TOPLINGDB_ROOT`\n\nis unset, the first run shallow-clones[topling/topling-zip](https://github.com/topling/topling-zip)with its required`boost-include`\n\nsubmodule into`${XDG_CACHE_HOME:-~/.cache}/relational-to-kv/topling-zip`\n\n. Later runs reuse that cache and compile the checked-out source again. Set`TOPLINGDB_CACHE_ROOT=/path/to/cache`\n\nto relocate it.\n\nThe runner validates that either checkout contains the required signed, real, and string `as_memcmp`\n\nAPIs plus the `std::string*`\n\nappend encoder and bounded output decoder before compiling, so an incompatible explicit checkout or stale cache fails with an actionable message instead of obscure compiler errors. `git`\n\n, GCC or Clang with C++17 support, and network access on the first automatic-clone run are required. Set `CXX`\n\nto select GCC or Clang; set `SKIP_SANITIZERS=1`\n\nonly when sanitizers are unavailable.\n\nAdditional systems that keep business state on embedded KV (shapes differ; useful for comparison):\n\n| Kind | Examples | Notes |\n|---|---|---|\n| Chain, RocksDB for part of the stack |\n|\n\n[Substrate / Polkadot](https://github.com/paritytech/polkadot-sdk)[Bitcoin Core](https://github.com/bitcoin/bitcoin);[Ethereum clients (Geth, …)](https://github.com/ethereum/go-ethereum)[Kafka Streams](https://kafka.apache.org/documentation/streams/);[Apache Flink](https://nightlies.apache.org/flink/flink-docs-stable/docs/ops/state/state_backends/)[Uber Cherami](https://github.com/uber-archive/cherami-server), etc.See also: [Aptos](https://github.com/aptos-labs/aptos-core)'s schema layer traces back to [Diem SchemaDB](https://diem.github.io/diem/schemadb/index.html).\n\nSQL systems such as MySQL with [MyRocks](https://myrocks.io/)/[MyTopling](https://github.com/topling/mytopling), [TiDB](https://github.com/pingcap/tidb) over [TiKV](https://github.com/tikv/tikv), and [CockroachDB](https://github.com/cockroachdb/cockroach) embody a different form of the same idea: the product itself is a relational database backed by a KV storage engine. This project brings that architecture directly to application data models, mapping their relational structure onto ToplingDB / RocksDB and thereby eliminating the RDBMS (relational database) abstraction tax.", "url": "https://wpnews.pro/news/show-hn-relational-to-kv-ai-maps-relational-models-to-toplingdb-rocksdb", "canonical_source": "https://github.com/rockeet/relational-to-kv", "published_at": "2026-08-13 07:58:16+00:00", "updated_at": "2026-08-13 08:10:37.908261+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["ToplingDB", "RocksDB", "Cursor", "Claude Code", "Codex", "Sui", "Aptos", "NEAR"], "alternates": {"html": "https://wpnews.pro/news/show-hn-relational-to-kv-ai-maps-relational-models-to-toplingdb-rocksdb", "markdown": "https://wpnews.pro/news/show-hn-relational-to-kv-ai-maps-relational-models-to-toplingdb-rocksdb.md", "text": "https://wpnews.pro/news/show-hn-relational-to-kv-ai-maps-relational-models-to-toplingdb-rocksdb.txt", "jsonld": "https://wpnews.pro/news/show-hn-relational-to-kv-ai-maps-relational-models-to-toplingdb-rocksdb.jsonld"}}