Skip to content

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

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

Align architecture/database.md with current java-tron storage layer and Toolkit behavior#330
abn2357 wants to merge 3 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. Content-aligned with
the English counterpart
tronprotocol/documentation-en#604.

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 "位置参数",
    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 优化参数" 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 **注意**: — the trailing
    10-hours note used the bare >备注: form (no space, wrong
    label, wraps to 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 3 commits May 20, 2026 11:26
- 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.
Same convention used elsewhere in the docs: drop the bare `>备注:`
form (no space, wrong label, wraps to next line) and use the bolded
single-line `> **注意**:...` 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