App Request → Rust Binary Spawn → AES Decryption → JSON STDOUT → Process Exit (RAM Cleared)
How to use PON-Engine / Reader complete guide
Data Query Model
How PON-DB interacts with your Application
PON-DB does not use a persistent "Server-Client" connection. Instead, it follows an Atomic Request Pattern. This ensures that your application only consumes resources during the exact millisecond the data is being retrieved.
1. The Request
Your application (Python, Node.js, PHP, etc.) executes the pon-db-reader binary as a subprocess. You pass the database path, the query string, and the hardware-locked master key.
2. The O(1) Jump
The Rust engine performs a stateless offset jump. It doesn't scan the file from the beginning; it calculates the exact byte position, jumps there, and reads only the required encrypted block.
Key Integration Concepts
- Standard Streams: Data is delivered via
STDOUT. Errors are sent toSTDERR. This makes PON-DB compatible with 100% of modern programming languages. - Stateless Nature: There is no "session" to maintain. Every query is independent, making your architecture natively ready for Horizontal Scaling and Serverless environments.
- Secure by Design: Since the binary terminates after each query, there is no persistent process in memory that could be targeted by heap-dump attacks.
"Efficiency is not about doing more; it's about leaving no trace when you are done."
PON-DB Engine is the full version (ingestion + querying).
PON-Reader is the ultra-light read-only version — significantly smaller and optimized for production read-heavy workloads, edge devices, IoT, or any environment where you only need fast queries. Download PON-Reader v1.2 here. only ≈170Kb
1. Ingestion – Create the .pon file (one-time operation with PON-DB Engine)
The PON-DB Engine can index the top-level fields of JSON files, one field per processing, thus guaranteeing an O(1) search.
./pon-db-engine dataset.json --index=fieldThis command reads your JSON array, builds the O(1) solid-state index using the specified field as primary key, encrypts every row with AES-256-GCM, compresses the data, and generates:
dataset.json.pon– the encrypted and indexed filemasterkey_*.bin– the master key file
2. Querying
Option A – Using PON-Reader (recommended for production – lighter & faster )
./pon-db-reader data.pon "field=value" --key=key.binOption B – Using PON-DB Engine in query mode
./pon-db-engine data.pon query "field=value" --key=key.binExample with real dataset (NYC Yellow Taxi)
# Ingestion
./pon-db-engine 2023_Yellow_Taxi_Trip_Data.json --index=tpep_pickup_datetime
# Query with PON-Reader
./pon-db-reader 2023_Yellow_Taxi_Trip_Data.json.pon "tpep_pickup_datetime=01/01/2023 12:51:08 AM" --key=masterkey_*.binTypical output includes the matching JSON rows + performance metrics (~0.05 ms latency ENGINE LATENCY
(Total execution <25ms, 1.8MB STATIC RAM FOOTPRINT , < 0.1% CPU OVERHEAD ).
Key Benefits of this approach
- Single static binary (~1 MB for Engine, even smaller for PON-Reader)
- Zero dependencies, zero server, zero tuning
- Data always remains encrypted at rest and during queries
- Works everywhere: servers, laptops, edge devices, IoT, air-gapped systems
- True O(1) performance even with 100M+ encrypted rows