firebase-rtdb-tools 0.2.1__tar.gz

firebase_rtdb_tools-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Berkay Turanci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

firebase_rtdb_tools-0.2.1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: firebase-rtdb-tools
+Version: 0.2.1
+Summary: Firebase Realtime Database (RTDB) lossless restore toolkit for large backups
+Author-email: Berkay Turanci <berkayturanci@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/berkayturanci/firebase-rtdb-restore
+Project-URL: Repository, https://github.com/berkayturanci/firebase-rtdb-restore
+Project-URL: Issues, https://github.com/berkayturanci/firebase-rtdb-restore/issues
+Project-URL: Changelog, https://github.com/berkayturanci/firebase-rtdb-restore/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://berkayturanci.github.io/firebase-rtdb-restore/
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: firebase-admin>=5.0.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Dynamic: license-file
+
+# Firebase RTDB Lossless Restore Toolkit
+
+A simple, memory-efficient toolkit to restore large Firebase Realtime Database (RTDB) backups safely and without data loss.
+
+[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/berkayturanci/firebase-rtdb-restore)](https://github.com/berkayturanci/firebase-rtdb-restore/releases)
+[![PyPI version](https://img.shields.io/pypi/v/firebase-rtdb-tools?logo=pypi)](https://pypi.org/project/firebase-rtdb-tools/)
+[![Run Tests](https://github.com/berkayturanci/firebase-rtdb-restore/actions/workflows/tests.yml/badge.svg)](https://github.com/berkayturanci/firebase-rtdb-restore/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## The Problem
+
+Restoring a large Firebase database backup (e.g., 1 GB+) using default tools is difficult for three reasons:
+
+1. **The Overwrite Trap**: Importing a JSON file in the Firebase Console completely erases all existing data at that path first. You cannot upload a large backup in pieces because each new piece wipes out the previous ones.
+2. **Request Size Limits**: Firebase limits the size of a single write request. Large backup files will timeout or fail with payload size errors.
+3. **Out-Of-Memory Crashes**: Loading a giant JSON backup file into memory will crash standard scripts.
+
+---
+
+## The Solution
+
+This toolkit solves these problems using four simple steps:
+
+* **Stream Splitting**: Splits a giant JSON file into smaller chunks without loading the whole file into memory. It reads the file in tiny 128 KB blocks.
+* **Lossless Verification**: Automatically checks that no data was lost during splitting by comparing SHA-256 fingerprints of every single entry.
+* **Batch Uploading**: Groups entries into safe ≤ 4 MB batches and uploads them using additive `PATCH` updates, merging data without erasing anything else.
+* **Oversized Entry Recovery**: Recursively splits individual massive entries (like a single user with huge data) child-key by child-key so they fit under request limits.
+
+---
+
+## Installation
+
+### Via PyPI
+
+```bash
+pip install firebase-rtdb-tools
+```
+
+This installs four simple command-line tools:
+* `firebase-rtdb-split`
+* `firebase-rtdb-validate`
+* `firebase-rtdb-upload`
+* `firebase-rtdb-upload-single`
+
+If PyPI does not show the package yet, install from source until the next release workflow publishes successfully.
+
+### From Source
+
+```bash
+git clone https://github.com/berkayturanci/firebase-rtdb-restore.git
+cd firebase-rtdb-restore
+pip install -r requirements.txt
+```
+
+For local development, install the editable package with development tools:
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## How to Get Your Firebase Service Account Key
+
+To upload data to your Firebase database:
+
+1. Go to your **Firebase Console** -> **Project Settings** -> **Service accounts**.
+2. Click **Generate new private key** and download the JSON file.
+3. Pass the path to this JSON file using the `-s` / `--service-account` option, or set the environment variable:
+   ```bash
+   export FIREBASE_SERVICE_ACCOUNT_KEY="/path/to/serviceAccountKey.json"
+   ```
+
+---
+
+## Simple Restore Workflow
+
+### Step 1: Split the giant backup file
+Split the backup JSON into smaller files (default is 1,000 entries per file):
+```bash
+make split BACKUP=backup.json CHUNKS=./chunks NODE=users
+```
+*(Or use `firebase-rtdb-split backup.json -o ./chunks -n users -c 1000`)*
+
+### Step 2: Verify the split
+Check that the split was 100% exact and no data was lost:
+```bash
+make validate BACKUP=backup.json CHUNKS=./chunks NODE=users
+```
+*(Or use `firebase-rtdb-validate backup.json ./chunks -n users`)*
+
+**Do not proceed if this step fails.**
+
+### Step 3: Upload chunks to Firebase
+Upload all chunks to your database. This merges data additively and will not overwrite other sibling nodes:
+```bash
+# Option A: Append/Resume (merges chunks into /users without wiping anything else)
+make upload CHUNKS=./chunks SA=serviceAccountKey.json DBPATH=/users
+
+# Option B: Clean restore of the TARGET path (wipes /users first, leaves siblings intact)
+make upload-wipe CHUNKS=./chunks SA=serviceAccountKey.json DBPATH=/users
+
+# Option C: Full reset (wipes the ENTIRE database root first — destroys all data)
+make upload-wipe-root CHUNKS=./chunks SA=serviceAccountKey.json DBPATH=/users
+```
+*(Or use `firebase-rtdb-upload ./chunks -s serviceAccountKey.json -p /users --wipe`)*
+
+**Upload options:**
+* `--wipe` wipes only the target path (`-p`); `--wipe-root` wipes the entire database root.
+* `--dry-run` previews exactly what would be wiped/uploaded without writing anything.
+* `-w/--workers N` uploads N chunks in parallel (default 1).
+* Uploads are **resumable**: completed chunks are recorded in a `.upload-progress` file inside the chunks directory and skipped automatically when you re-run after a failure. Transient write errors are retried with exponential backoff.
+
+### Step 4: Handle giant entries (if any)
+If the upload script reports that a specific entry failed because it is too large to fit in a single request:
+```bash
+make upload-single UID=some_uid CHUNKS=./chunks/chunk_0000.json SA=serviceAccountKey.json DBPATH=/users
+```
+*(Or use `firebase-rtdb-upload-single some_uid ./chunks/chunk_0000.json -s serviceAccountKey.json -p /users`)*
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

firebase_rtdb_tools-0.2.1/README.md

@@ -0,0 +1,127 @@
+# Firebase RTDB Lossless Restore Toolkit
+
+A simple, memory-efficient toolkit to restore large Firebase Realtime Database (RTDB) backups safely and without data loss.
+
+[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/berkayturanci/firebase-rtdb-restore)](https://github.com/berkayturanci/firebase-rtdb-restore/releases)
+[![PyPI version](https://img.shields.io/pypi/v/firebase-rtdb-tools?logo=pypi)](https://pypi.org/project/firebase-rtdb-tools/)
+[![Run Tests](https://github.com/berkayturanci/firebase-rtdb-restore/actions/workflows/tests.yml/badge.svg)](https://github.com/berkayturanci/firebase-rtdb-restore/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## The Problem
+
+Restoring a large Firebase database backup (e.g., 1 GB+) using default tools is difficult for three reasons:
+
+1. **The Overwrite Trap**: Importing a JSON file in the Firebase Console completely erases all existing data at that path first. You cannot upload a large backup in pieces because each new piece wipes out the previous ones.
+2. **Request Size Limits**: Firebase limits the size of a single write request. Large backup files will timeout or fail with payload size errors.
+3. **Out-Of-Memory Crashes**: Loading a giant JSON backup file into memory will crash standard scripts.
+
+---
+
+## The Solution
+
+This toolkit solves these problems using four simple steps:
+
+* **Stream Splitting**: Splits a giant JSON file into smaller chunks without loading the whole file into memory. It reads the file in tiny 128 KB blocks.
+* **Lossless Verification**: Automatically checks that no data was lost during splitting by comparing SHA-256 fingerprints of every single entry.
+* **Batch Uploading**: Groups entries into safe ≤ 4 MB batches and uploads them using additive `PATCH` updates, merging data without erasing anything else.
+* **Oversized Entry Recovery**: Recursively splits individual massive entries (like a single user with huge data) child-key by child-key so they fit under request limits.
+
+---
+
+## Installation
+
+### Via PyPI
+
+```bash
+pip install firebase-rtdb-tools
+```
+
+This installs four simple command-line tools:
+* `firebase-rtdb-split`
+* `firebase-rtdb-validate`
+* `firebase-rtdb-upload`
+* `firebase-rtdb-upload-single`
+
+If PyPI does not show the package yet, install from source until the next release workflow publishes successfully.
+
+### From Source
+
+```bash
+git clone https://github.com/berkayturanci/firebase-rtdb-restore.git
+cd firebase-rtdb-restore
+pip install -r requirements.txt
+```
+
+For local development, install the editable package with development tools:
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## How to Get Your Firebase Service Account Key
+
+To upload data to your Firebase database:
+
+1. Go to your **Firebase Console** -> **Project Settings** -> **Service accounts**.
+2. Click **Generate new private key** and download the JSON file.
+3. Pass the path to this JSON file using the `-s` / `--service-account` option, or set the environment variable:
+   ```bash
+   export FIREBASE_SERVICE_ACCOUNT_KEY="/path/to/serviceAccountKey.json"
+   ```
+
+---
+
+## Simple Restore Workflow
+
+### Step 1: Split the giant backup file
+Split the backup JSON into smaller files (default is 1,000 entries per file):
+```bash
+make split BACKUP=backup.json CHUNKS=./chunks NODE=users
+```
+*(Or use `firebase-rtdb-split backup.json -o ./chunks -n users -c 1000`)*
+
+### Step 2: Verify the split
+Check that the split was 100% exact and no data was lost:
+```bash
+make validate BACKUP=backup.json CHUNKS=./chunks NODE=users
+```
+*(Or use `firebase-rtdb-validate backup.json ./chunks -n users`)*
+
+**Do not proceed if this step fails.**
+
+### Step 3: Upload chunks to Firebase
+Upload all chunks to your database. This merges data additively and will not overwrite other sibling nodes:
+```bash
+# Option A: Append/Resume (merges chunks into /users without wiping anything else)
+make upload CHUNKS=./chunks SA=serviceAccountKey.json DBPATH=/users
+
+# Option B: Clean restore of the TARGET path (wipes /users first, leaves siblings intact)
+make upload-wipe CHUNKS=./chunks SA=serviceAccountKey.json DBPATH=/users
+
+# Option C: Full reset (wipes the ENTIRE database root first — destroys all data)
+make upload-wipe-root CHUNKS=./chunks SA=serviceAccountKey.json DBPATH=/users
+```
+*(Or use `firebase-rtdb-upload ./chunks -s serviceAccountKey.json -p /users --wipe`)*
+
+**Upload options:**
+* `--wipe` wipes only the target path (`-p`); `--wipe-root` wipes the entire database root.
+* `--dry-run` previews exactly what would be wiped/uploaded without writing anything.
+* `-w/--workers N` uploads N chunks in parallel (default 1).
+* Uploads are **resumable**: completed chunks are recorded in a `.upload-progress` file inside the chunks directory and skipped automatically when you re-run after a failure. Transient write errors are retried with exponential backoff.
+
+### Step 4: Handle giant entries (if any)
+If the upload script reports that a specific entry failed because it is too large to fit in a single request:
+```bash
+make upload-single UID=some_uid CHUNKS=./chunks/chunk_0000.json SA=serviceAccountKey.json DBPATH=/users
+```
+*(Or use `firebase-rtdb-upload-single some_uid ./chunks/chunk_0000.json -s serviceAccountKey.json -p /users`)*
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

firebase_rtdb_tools-0.2.1/firebase_rtdb_restore/__init__.py

@@ -0,0 +1,5 @@
+"""
+Firebase RTDB Lossless Restore Toolkit.
+"""
+
+__version__ = "0.2.0"

firebase_rtdb_tools-0.2.1/firebase_rtdb_restore/__main__.py

@@ -0,0 +1,24 @@
+"""Allow ``python -m firebase_rtdb_restore`` to list the available commands."""
+
+import sys
+
+COMMANDS = {
+    "split": "firebase_rtdb_restore.split_backup",
+    "validate": "firebase_rtdb_restore.validate_chunks",
+    "upload": "firebase_rtdb_restore.upload_chunks",
+    "upload-single": "firebase_rtdb_restore.upload_single_user",
+}
+
+
+def main():
+    print("Firebase RTDB Lossless Restore Toolkit\n")
+    print("Run one of the module entry points directly, e.g.:")
+    for name, module in COMMANDS.items():
+        print(f"  python -m {module}    # {name}")
+    print("\nOr use the installed console scripts: firebase-rtdb-split, "
+          "firebase-rtdb-validate, firebase-rtdb-upload, firebase-rtdb-upload-single.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

firebase_rtdb_tools-0.2.1/firebase_rtdb_restore/_common.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""
+Shared helpers for the Firebase RTDB restore toolkit.
+
+Keeps the streaming JSON parser, node location, service-account resolution,
+idempotent app initialisation, retrying writes and TTY-aware progress in one
+place so the four CLI entry points stay thin and behave consistently.
+"""
+
+import contextlib
+import json
+import os
+import sys
+import time
+
+READ_CHUNK = 128 * 1024  # 128 KB read window
+
+# Sentinel distinguishing "value not parsed yet" from a legitimate JSON ``null``
+# value, so an entry whose value is literally ``null`` is not silently dropped.
+_INCOMPLETE = object()
+
+
+def is_tty():
+    return sys.stdout.isatty()
+
+
+def tty_progress(msg):
+    """Emit a carriage-return progress line, but only on an interactive TTY.
+
+    On non-interactive streams (CI logs, pipes, test runners) this is a no-op so
+    the transient ``\\r`` updates do not flood the output. Final/summary lines
+    should use ``print`` directly.
+    """
+    if is_tty():
+        print(f"\r{msg}", end="", flush=True)
+
+
+def locate_node(f, node_key):
+    """Stream-search the open text file ``f`` for the top-level ``"<node_key>": {``.
+
+    Reads the file in blocks until the node is found, so the target node may
+    appear anywhere in the backup rather than only within a fixed-size header
+    window. Returns the leftover buffer positioned just after the opening
+    ``{`` of the node object, or ``None`` if the node is never found.
+    """
+    node_pattern = f'"{node_key}"'
+    # Retain enough of a tail across reads that a pattern straddling a read
+    # boundary still matches on the next iteration.
+    overlap = len(node_pattern) + 1
+    buf = ""
+    while True:
+        idx = buf.find(node_pattern)
+        if idx != -1:
+            after = buf[idx + len(node_pattern):]
+            colon = after.find(":")
+            if colon != -1:
+                brace = after.find("{", colon)
+                if brace != -1:
+                    return after[brace + 1:]
+            # Key found but ':' / '{' not fully buffered yet — keep from the key
+            # onward and read more.
+            more = f.read(READ_CHUNK)
+            if not more:
+                return None
+            buf = buf[idx:] + more
+            continue
+        more = f.read(READ_CHUNK)
+        if not more:
+            return None
+        buf = buf[-overlap:] + more
+
+
+def iter_entries(f, buf, file_size=None, label=""):
+    """Yield ``(key, value)`` pairs from the node object being streamed.
+
+    ``buf`` must be positioned just after the node's opening ``{`` (see
+    :func:`locate_node`). Works on both pretty-printed and minified JSON and
+    never loads the whole file into memory. When ``file_size`` and ``label`` are
+    given, a TTY-only progress line is emitted as the file is consumed.
+    """
+    decoder = json.JSONDecoder()
+    total = 0
+
+    def report():
+        if file_size and label:
+            pct = min(f.tell() * 100 // file_size, 100)
+            tty_progress(f"  {label}: {total} entries | {pct}% read ")
+
+    while True:
+        if len(buf) < READ_CHUNK:
+            more = f.read(READ_CHUNK)
+            if more:
+                buf += more
+                report()
+
+        s = buf.lstrip(" \t\n\r")
+        if not s or s[0] == "}":
+            break
+        if s[0] == ",":
+            buf = s[1:]
+            continue
+        if s[0] != '"':
+            # Unexpected character outside of a key — skip one char and retry.
+            buf = s[1:]
+            continue
+
+        # ── parse key ───────────────────────────────────────────────────────
+        try:
+            key, key_end = decoder.raw_decode(s)
+        except json.JSONDecodeError:
+            more = f.read(READ_CHUNK)
+            if not more:
+                break
+            buf = s + more
+            continue
+
+        if not isinstance(key, str):
+            buf = s[key_end:]
+            continue
+
+        rest = s[key_end:].lstrip()
+        if not rest or rest[0] != ":":
+            buf = rest
+            continue
+
+        val_str = rest[1:].lstrip()
+
+        # ── parse value (read more if incomplete) ───────────────────────────
+        val = _INCOMPLETE
+        while True:
+            try:
+                val, val_end = decoder.raw_decode(val_str)
+                break
+            except json.JSONDecodeError:
+                more = f.read(READ_CHUNK)
+                if not more:
+                    break  # EOF with incomplete value
+                val_str += more
+
+        if val is _INCOMPLETE:
+            break  # incomplete entry at EOF — stop
+
+        total += 1
+        buf = val_str[val_end:]
+        yield key, val
+
+    report()
+
+
+def resolve_service_account(arg):
+    """Resolve the service-account path from CLI arg, env var, or local default.
+
+    Order of precedence: explicit ``arg`` → ``FIREBASE_SERVICE_ACCOUNT_KEY`` env
+    var → ``./serviceAccountKey.json``. Returns the expanded path or ``None``.
+    """
+    if arg:
+        return os.path.expanduser(arg)
+    env = os.environ.get("FIREBASE_SERVICE_ACCOUNT_KEY")
+    if env:
+        return os.path.expanduser(env)
+    if os.path.exists("./serviceAccountKey.json"):
+        return "./serviceAccountKey.json"
+    return None
+
+
+def service_account_error():
+    print("ERROR: Service account file must be provided via -s/--service-account,")
+    print("or set via the FIREBASE_SERVICE_ACCOUNT_KEY environment variable,")
+    print("or exist as './serviceAccountKey.json' in the current working directory.")
+
+
+def init_app(sa_path, database_url=None):
+    """Initialise the default Firebase app idempotently.
+
+    Returns ``(service_account_dict, database_url)``. Safe to call more than once
+    in the same process: a pre-existing default app is reused instead of raising.
+    """
+    import firebase_admin
+    from firebase_admin import credentials
+
+    with open(sa_path) as f:
+        sa = json.load(f)
+
+    db_url = database_url or f"https://{sa['project_id']}.firebaseio.com"
+
+    # A pre-existing default app raises ValueError — reuse it instead of failing.
+    with contextlib.suppress(ValueError):
+        firebase_admin.initialize_app(credentials.Certificate(sa_path), {"databaseURL": db_url})
+
+    return sa, db_url
+
+
+def with_retry(fn, *, attempts=4, base_delay=1.0, label=""):
+    """Call ``fn`` with exponential backoff, retrying on any exception.
+
+    ``attempts`` is the total number of tries (1 initial + ``attempts - 1``
+    retries). Re-raises the last exception if every attempt fails.
+    """
+    last = None
+    for i in range(1, attempts + 1):
+        try:
+            return fn()
+        except Exception as e:  # noqa: BLE001 — surface any transient failure to retry
+            last = e
+            if i == attempts:
+                break
+            delay = base_delay * (2 ** (i - 1))
+            print(f"\n  retry {i}/{attempts - 1} for {label or 'write'} after error: {e} (waiting {delay:.1f}s)")
+            time.sleep(delay)
+    raise last
+
+
+def recursive_write(ref, value, path, max_bytes, depth=0):
+    """Write ``value`` to ``ref``, splitting dicts child-by-child if too large.
+
+    Any single write is retried with backoff. A non-dict value larger than
+    ``max_bytes`` cannot be split, so it is written as one request with a warning.
+    """
+    sz = len(json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode())
+    indent = "  " * (depth + 1)
+    tty_progress(f"{indent}{path}  ({sz // 1024} KB) ...")
+
+    if sz <= max_bytes or not isinstance(value, dict):
+        if sz > max_bytes:
+            print(
+                f"\n  WARNING: {path} is {sz // 1024} KB and is not a dict — "
+                f"cannot split further, writing as a single request."
+            )
+        with_retry(lambda: ref.set(value), label=path)
+        return
+
+    # Too large — write each child key separately (recursing as needed).
+    for k, v in value.items():
+        recursive_write(ref.child(k), v, f"{path}/{k}", max_bytes, depth + 1)

firebase_rtdb_tools-0.2.1/firebase_rtdb_restore/split_backup.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+Stream-split a Firebase RTDB backup into N-entry chunk files.
+
+Works on both pretty-printed AND minified (single-line) JSON.
+Reads in 128 KB blocks — never loads the full file into memory.
+"""
+
+import argparse
+import json
+import os
+
+from firebase_rtdb_restore._common import iter_entries, locate_node
+
+
+def split_backup(input_path, output_dir, chunk_size, node_key):
+    if not os.path.exists(input_path):
+        print(f"ERROR: Input file not found: {input_path}")
+        return 0, 0
+    file_size = os.path.getsize(input_path)
+    os.makedirs(output_dir, exist_ok=True)
+
+    chunk_num = 0
+    total = 0
+    chunk = {}
+
+    with open(input_path, encoding="utf-8") as f:
+        buf = locate_node(f, node_key)
+        if buf is None:
+            print(f'ERROR: "{node_key}" key not found. Is this a Firebase RTDB backup?')
+            return 0, 0
+
+        for key, val in iter_entries(f, buf, file_size=file_size, label="parsing"):
+            chunk[key] = val
+            total += 1
+            if len(chunk) >= chunk_size:
+                _write_chunk(output_dir, chunk_num, chunk)
+                chunk_num += 1
+                chunk = {}
+
+    # Final partial chunk
+    if chunk:
+        _write_chunk(output_dir, chunk_num, chunk)
+        chunk_num += 1
+
+    print(f"\n\nDone: {total} entries → {chunk_num} chunk files in:\n  {output_dir}/")
+    _print_upload_instructions(output_dir, node_key)
+    return chunk_num, total
+
+
+def _write_chunk(output_dir, chunk_num, chunk):
+    path = os.path.join(output_dir, f"chunk_{chunk_num:04d}.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(chunk, f)
+    print(f"\r  chunk_{chunk_num:04d}.json  ({len(chunk)} entries){' ' * 30}")
+
+
+def _print_upload_instructions(output_dir, node_key):
+    print(f"\nUpload each chunk (merges into /{node_key} — does NOT overwrite others):")
+    print(f"  for f in {output_dir}/chunk_*.json; do")
+    print( "    echo \"Uploading $f ...\"")
+    print(f"    firebase database:update /{node_key} \"$f\"")
+    print( "  done")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Stream-split a Firebase RTDB backup into N-entry chunk files.")
+    parser.add_argument("backup_file", help="Path to the RTDB backup JSON file.")
+    parser.add_argument("-o", "--output-dir", help="Directory to save chunk files. Defaults to '<backup_file_dir>/rtdb-chunks'.")
+    parser.add_argument("-c", "--chunk-size", type=int, default=1000, help="Number of entries per chunk file (default: 1000).")
+    parser.add_argument("-n", "--node", default="users", help="The top-level JSON key to split (default: 'users').")
+
+    args = parser.parse_args()
+
+    if args.chunk_size < 1:
+        parser.error("--chunk-size must be a positive integer")
+
+    input_path = os.path.expanduser(args.backup_file)
+    output_dir = os.path.expanduser(args.output_dir) if args.output_dir \
+        else os.path.join(os.path.dirname(input_path), "rtdb-chunks")
+
+    print(f"Input:      {input_path}")
+    print(f"Output dir: {output_dir}")
+    print(f"Chunk size: {args.chunk_size} entries")
+    print(f"Split node: {args.node}\n")
+
+    split_backup(input_path, output_dir, args.chunk_size, args.node)
+
+
+if __name__ == "__main__":
+    main()