CLI: App-Scoped `dump` & `load` commands for single-application data export

[vfusco]

Context / Problem

Developers often need to move only the data for a single dApp—identified by its application name or Ethereum address—between Rollups-Node instances. Key use-cases:

1. Debugging production or user development issues locally.
2. Bootstrapping a reader node from an existing node.
3. Service migration of one app to new infrastructure.
4. Backup / restore at per app granularity.

Current work-arounds (full pg_dump + filtering) are slow, error-prone, and risk leaking unrelated data.

---

Suggested Solution

1. Hard-coded dependency graph

   • Embed the known FK chain (applications → epochs → inputs → outputs | reports → …) in code to give a deterministic dump/load order.

2. dump command

cartesi-rollups-cli app dump echo-dapp > echo-dapp.sql.gz
cartesi-rollups-cli app dump 0xAbC… > app-0xAbC.sql.gz
cartesi-rollups-cli app dump echo-dapp –binary > echo-dapp.bin.gz

• Default output: CSV + gzip (portable, human-readable).
• --binary flag switches to Postgres binary COPY (≈3× faster, version-locked).
• Generated SQL disables constraints, replays the data, then re-enables constraints.

3. load command

cartesi-rollups-cli app load echo-dapp.sql.gz

• Runs inside a single transaction.
• If a dApp with the same name or address already exists, abort with a clear error.
• Otherwise, remap any colliding internal PKs, update FKs, commit, and run ANALYZE.

4. Validation & DX

• Pre-flight checks ensure the app exists (for dump) and the dump file is well-formed (for load).
• Helpful errors: “application already exists”, “malformed dump file”, etc.
• --help shows new flags and examples.

---

Deliverables

• CLI binaries
• app dump <name|address> [--binary] > <file>.sql.gz
• app load <file>.sql.gz
• Tests
• Unit tests for dump/load helpers.
• Integration tests covering:

1. Happy-path dump & load.
2. Automatic PK remap.
3. Binary format round-trip (--binary).

---

Acceptance Criteria

#	Scenario	Expected outcome
1	Dump echo-dapp (~1 GB) on staging	File produced ≤ 5 min; contains only rows for that app
2	Restore with psql -f echo-dapp.sql.gz	Import completes with zero integrity violations
3	Load into DB where no app with same name/address exists	Import succeeds; internal IDs remapped as needed
4	Load into DB where app name/address already exists	Transaction aborts with clear “application already exists” error
5	cartesi-rollups-cli app dump --help	Shows --binary, and usage examples
6	cartesi-rollups-cli app load --help	Shows usage examples