Skip to content

Align architecture/database.md with current java-tron storage layer and Toolkit behavior#604

Open
abn2357 wants to merge 4 commits into
tronprotocol:masterfrom
abn2357:fix_database
Open

Align architecture/database.md with current java-tron storage layer and Toolkit behavior#604
abn2357 wants to merge 4 commits into
tronprotocol:masterfrom
abn2357:fix_database

Conversation

@abn2357
Copy link
Copy Markdown
Contributor

@abn2357 abn2357 commented May 20, 2026

Summary

Audited docs/architecture/database.md against the current java-tron
storage layer and the Toolkit.jar db subcommands. Fixes a few
inaccuracies and fills in the gaps a reader naturally hits when
looking at the example storage { ... } block.

Notable corrections:

  • db convert is x86_64-only: DbConvert.java checks
    Arch.isArm64() at the top of call() and exits early with an
    "unsupported architecture" message, so it does nothing on arm64.
    Surfaced this as a note at the start of the migration section.
  • Positional, not named, arguments: section 2 previously
    documented src_db_path / dst_db_path as if they were CLI flags,
    but DbConvert.java declares them as picocli @Parameters with
    index = "0" / index = "1". Renamed the section to "Positional
    Arguments", switched to <src> / <dst> placeholders, and added
    the explicit db convert <src> <dst> command shape.
  • Dropped stale legacy link: the trailing
    Rocksdb_vs_Leveldb.md link pointed at the legacy
    tronprotocol/documentation repo, which is no longer maintained.

Filled-in gaps under the storage { ... } example block:

  • db.sync: explained that it controls whether the underlying
    engine waits for each write to be physically flushed to disk
    before returning. Default false. Verified that all four call
    sites — LevelDbDataSourceImpl, db2/common/LevelDB,
    db2/common/RocksDB, TronDatabase — set
    WriteOptions.sync(storage.isDbSync()), so the flag applies to
    both engines (the RocksDB path included).
  • transHistory.switch: explained that when "off",
    TransactionHistoryStore.put and TransactionRetStore.put
    silently drop new writes (BooleanUtils.toBoolean(switch) gate),
    which makes gettransactioninfobyid return empty for any
    transaction processed while the switch was off. Reads of
    pre-existing data are not gated. Default "on".
  • dbSettings is RocksDB-only: added a leading sentence to
    "RocksDB Optimization Parameters" noting that the block is only
    consumed by RocksDbSettings.initCustomSettings (and from there
    by RocksDbDataSourceImpl). The LevelDB code path has its own
    per-db tuning via storage.properties[*] with different key
    names (blockSize, writeBufferSize, cacheSize, maxOpenFiles,
    compressionType) and never reads dbSettings.

Formatting:

  • Normalized the inline-note prefix to **Note**: — the trailing
    10-hours note used the bare > Note: form (which also wrapped
    to the next line); now matches the bolded single-line style used
    by the arm64 note added in this PR.

Test plan

  • Verified Arch.isArm64() gating in DbConvert.java
  • Verified the two @Parameters indices and default values in
    DbConvert.java
  • Verified db.sync consumers across LevelDbDataSourceImpl,
    db2/common/LevelDB, db2/common/RocksDB, TronDatabase
  • Verified transHistory.switch gates put() in
    TransactionHistoryStore and TransactionRetStore, and that
    Wallet.getTransactionInfoById reads from both
  • Verified dbSettings only flows into RocksDbSettings and
    RocksDbDataSourceImpl; LevelDB path uses
    StorageUtils.getOptionsByDbName / Storage.newDefaultDbOptions
    with separate key names
  • Visual review of the rendered page

abn2357 added 4 commits May 20, 2026 11:22
- Note that `db convert` is x86_64-only; on arm64 the subcommand
  prints an "unsupported architecture" message and exits without
  converting anything.
- Rewrite section 2 to describe the two arguments as positional,
  not named flags: in DbConvert.java they are picocli `@Parameters`
  with `index = "0"` and `index = "1"`, so `--src_db_path=...` /
  `--dst_db_path=...` would not be recognized. Use `<src>` / `<dst>`
  placeholders and show the positional command shape explicitly.
- Drop the trailing link to tronprotocol/documentation's
  Rocksdb_vs_Leveldb.md — the target lives in the legacy docs repo
  and is no longer maintained.
The doc previously claimed db convert exits on arm64 "since arm64
builds do not ship the LevelDB native library". The actual gating
in DbConvert.java is just an Arch.isArm64() policy check with no
comment explaining the reason, and platform/build.gradle declares
leveldbjni-all unconditionally, so the rationale is speculative.
Keep the observed behavior and drop the cause clause.
Same convention used elsewhere in the docs: drop the bare `> Note:`
form (which also wrapped to the next line in this block) and use
the bolded single-line `> **Note:** ...` form, matching the arm64
note added earlier in this file.
…bSettings

The previous storage block listed three keys with no explanation.
Readers had no way to know which writes db.sync gates, what flipping
transHistory.switch costs them, or whether dbSettings does anything
under LevelDB. Sourced from:

- LevelDbDataSourceImpl, db2/common/LevelDB, db2/common/RocksDB,
  TronDatabase all set WriteOptions.sync(storage.isDbSync()), so
  db.sync applies to both engines (RocksDB path included).
- TransactionHistoryStore.put / TransactionRetStore.put gate writes
  on storage.transactionHistorySwitch; reads are not gated. The
  cutoff is block-apply time, not chain-confirmation, so the doc
  says "processed while the switch was off".
- dbSettings is only consumed by RocksDbSettings, which only feeds
  RocksDB Options; the LevelDB path uses storage.properties[*] with
  different key names and never reads dbSettings.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant