{"id":31274028,"url":"https://github.com/jonaylor89/png-db","last_synced_at":"2026-02-17T03:43:22.375Z","repository":{"id":316131522,"uuid":"1062091657","full_name":"jonaylor89/png-db","owner":"jonaylor89","description":"store JSON data in PNG images","archived":false,"fork":false,"pushed_at":"2025-09-23T03:59:25.000Z","size":1315,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-03T07:01:51.872Z","etag":null,"topics":["database","png","rust","sql","steganography","wasm"],"latest_commit_sha":null,"homepage":"https://pngdb.jonaylor.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonaylor89.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T19:48:13.000Z","updated_at":"2025-09-23T03:59:28.000Z","dependencies_parsed_at":"2025-09-22T22:17:05.385Z","dependency_job_id":"4a7c3832-f677-415d-82e1-fecb25638d13","html_url":"https://github.com/jonaylor89/png-db","commit_stats":null,"previous_names":["jonaylor89/png-db"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jonaylor89/png-db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fpng-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fpng-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fpng-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fpng-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonaylor89","download_url":"https://codeload.github.com/jonaylor89/png-db/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fpng-db/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29530380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T00:57:22.232Z","status":"online","status_checked_at":"2026-02-17T02:00:08.105Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","png","rust","sql","steganography","wasm"],"created_at":"2025-09-23T22:26:49.429Z","updated_at":"2026-02-17T03:43:22.368Z","avatar_url":"https://github.com/jonaylor89.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PNG-DB\n\nA simple database that stores JSON data rows as compressed text within the zTXt chunks of PNG image files. Each JSON row is associated with a pixel coordinate and can be queried using a simple SQL-like syntax.\n\n\n**Try it online**: [https://pngdb.jonaylor.com](https://pngdb.jonaylor.com)\n\n![Demo Screenshot](images/screenshot.png)\n\n## Quick Start\n\n```bash\njust        # List all available commands\njust serve  # Start web demo\njust demo   # Try CLI with sample data\n```\n\n## Features\n\n- **PNG Storage**: Stores JSON data in PNG zTXt chunks while maintaining a valid image file\n- **Schema Definition**: Define field types for your JSON data structure\n- **Coordinate-based Storage**: Associate each JSON row with pixel coordinates (x, y)\n- **SQL-like Queries**: Query data using WHERE clauses with coordinate and JSON field filtering\n- **Compression**: Uses zlib compression for efficient storage of JSON data\n- **CLI Interface**: Easy-to-use command-line interface for database operations\n\n## Installation\n\n### NPM Package (WASM)\n\n```bash\nnpm install @jonaylor89/png-db\n```\n\n```javascript\nimport init, { PngDb } from '@jonaylor89/png-db';\n\nawait init();\n\n// Create a new database\nconst db = PngDb.create(500, 500, { name: 'string', age: 'number' });\n\n// Insert data\ndb.insert(10, 20, { name: 'Alice', age: 30 });\ndb.insert(50, 60, { name: 'Bob', age: 25 });\n\n// Query data\nconst results = db.query('WHERE age \u003e 28');\nconsole.log(results);\n\n// Save to file (in Node.js) or get bytes for browser download\nconst pngBytes = db.to_bytes();\n```\n\n### CLI Version\n\n**Using Just (recommended):**\n```bash\njust build  # Build CLI version\njust demo   # Create and test sample database\n```\n\nOr install from crates.io (coming soon):\n```bash\ncargo install png-db\n```\n\n## Usage\n\n### Creating a Database\n\nCreate a new PNG database with a schema:\n\n```bash\n./target/release/png-db create --file mydb.png --width 500 --height 500 --schema \"name:string,age:number,active:boolean\"\n```\n\n### Inserting Data\n\nInsert JSON data at specific coordinates:\n\n```bash\n./target/release/png-db insert --file mydb.png --x 10 --y 20 --data '{\"name\": \"Alice\", \"age\": 30, \"active\": true}'\n./target/release/png-db insert --file mydb.png --x 50 --y 100 --data '{\"name\": \"Bob\", \"age\": 25, \"active\": false}'\n./target/release/png-db insert --file mydb.png --x 200 --y 150 --data '{\"name\": \"Charlie\", \"age\": 35, \"active\": true}'\n```\n\n### Querying Data\n\nQuery data using WHERE clauses:\n\n```bash\n# Find all active users\n./target/release/png-db query --file mydb.png --where-clause \"WHERE active = true\"\n\n# Find users in a specific coordinate range\n./target/release/png-db query --file mydb.png --where-clause \"WHERE x \u003e 25 AND y \u003c 200\"\n\n# Combine coordinate and data filters\n./target/release/png-db query --file mydb.png --where-clause \"WHERE x \u003e 10 AND age \u003e= 30\"\n\n# Find users by name\n./target/release/png-db query --file mydb.png --where-clause 'WHERE name = \"Alice\"'\n```\n\n### Listing All Data\n\nList all rows in the database:\n\n```bash\n./target/release/png-db list --file mydb.png\n```\n\n## Query Syntax\n\nThe query engine supports simple WHERE clauses with the following features:\n\n### Supported Operators\n- `=` - Equal\n- `!=` - Not equal  \n- `\u003e` - Greater than\n- `\u003c` - Less than\n- `\u003e=` - Greater than or equal\n- `\u003c=` - Less than or equal\n\n### Supported Fields\n- `x`, `y` - Pixel coordinates (numbers)\n- Any field defined in your JSON schema\n\n### Value Types\n- **Strings**: Use double quotes, e.g., `name = \"Alice\"`\n- **Numbers**: Integer or float, e.g., `age = 30` or `height = 5.9`\n- **Booleans**: `true` or `false`\n\n### Combining Conditions\nUse `AND` to combine multiple conditions:\n```\nWHERE x \u003e 100 AND y \u003c 200 AND active = true AND age \u003e= 25\n```\n\n## Examples\n\n### Complete Workflow\n\n```bash\n# 1. Create a user database\n./target/release/png-db create --file users.png --width 1000 --height 1000 --schema \"name:string,email:string,age:number,department:string,active:boolean\"\n\n# 2. Add some users\n./target/release/png-db insert --file users.png --x 100 --y 200 --data '{\"name\": \"Alice Johnson\", \"email\": \"alice@company.com\", \"age\": 28, \"department\": \"Engineering\", \"active\": true}'\n\n./target/release/png-db insert --file users.png --x 250 --y 300 --data '{\"name\": \"Bob Smith\", \"email\": \"bob@company.com\", \"age\": 34, \"department\": \"Marketing\", \"active\": true}'\n\n./target/release/png-db insert --file users.png --x 400 --y 150 --data '{\"name\": \"Carol Brown\", \"email\": \"carol@company.com\", \"age\": 29, \"department\": \"Engineering\", \"active\": false}'\n\n# 3. Query the data\n./target/release/png-db query --file users.png --where-clause 'WHERE department = \"Engineering\"'\n\n./target/release/png-db query --file users.png --where-clause \"WHERE active = true AND age \u003e 30\"\n\n./target/release/png-db query --file users.png --where-clause \"WHERE x \u003e 200 AND y \u003c 250\"\n\n# 4. List all data\n./target/release/png-db list --file users.png\n```\n\n## Technical Details\n\n### Storage Format\n\n- **PNG Image**: Creates a valid PNG image (black pixels by default)\n- **Schema**: Stored in a zTXt chunk with keyword \"schema\"\n- **Data Rows**: Each row stored in a zTXt chunk with keyword \"row_x_y\" (where x,y are coordinates)\n- **Compression**: All text data is compressed using zlib before storage\n\n### File Structure\n\n```\nPNG File\n├── IHDR chunk (image header)\n├── zTXt chunk (keyword: \"schema\") - Database schema\n├── zTXt chunk (keyword: \"row_10_20\") - JSON data at (10,20)\n├── zTXt chunk (keyword: \"row_50_100\") - JSON data at (50,100)\n├── ...\n├── IDAT chunks (image data - black pixels)\n└── IEND chunk (end marker)\n```\n\n## Limitations\n\n- **Query Complexity**: Only supports simple WHERE clauses with AND conditions\n- **Data Types**: Limited to JSON-compatible types (string, number, boolean, null)\n- **Performance**: Not optimized for large datasets - intended for small to medium data storage\n- **Concurrency**: No built-in support for concurrent access\n- **Indexing**: No indexing - queries perform linear scans\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonaylor89%2Fpng-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonaylor89%2Fpng-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonaylor89%2Fpng-db/lists"}