{"id":30762684,"url":"https://github.com/cwt/neosqlite","last_synced_at":"2026-04-13T02:23:05.192Z","repository":{"id":179922997,"uuid":"168724637","full_name":"cwt/neosqlite","owner":"cwt","description":"Drop-in PyMongo replacement for SQLite: Documents, aggregation, indexing, and GridFS","archived":false,"fork":false,"pushed_at":"2026-04-03T04:09:12.000Z","size":5681,"stargazers_count":19,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-03T06:46:00.096Z","etag":null,"topics":["mongodb","neosqlite","nosql","pymongo","sqlite"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/neosqlite/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"plutec/nosqlite","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cwt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"github":["cwt"],"liberapay":"cwt","custom":["https://paypal.me/chaiwat"]}},"created_at":"2019-02-01T16:14:43.000Z","updated_at":"2026-04-03T05:39:32.000Z","dependencies_parsed_at":"2025-09-25T19:07:14.798Z","dependency_job_id":"1e3aa1ed-1723-4a82-b91a-6d3e90407f1f","html_url":"https://github.com/cwt/neosqlite","commit_stats":null,"previous_names":["bashell-com/nosqlite"],"tags_count":60,"template":false,"template_full_name":null,"purl":"pkg:github/cwt/neosqlite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Fneosqlite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Fneosqlite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Fneosqlite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Fneosqlite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cwt","download_url":"https://codeload.github.com/cwt/neosqlite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Fneosqlite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31463015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"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":["mongodb","neosqlite","nosql","pymongo","sqlite"],"created_at":"2025-09-04T15:09:41.636Z","updated_at":"2026-04-13T02:23:05.140Z","avatar_url":"https://github.com/cwt.png","language":"Python","readme":"# NeoSQLite - NoSQL for SQLite with PyMongo-like API\n\n[![PyPI Version](https://img.shields.io/pypi/v/neosqlite.svg)](https://pypi.org/project/neosqlite/)\n\n`NeoSQLite` (new + nosqlite) is a pure Python library that provides a schemaless, `PyMongo`-like wrapper for interacting with SQLite databases. The API is designed to be familiar to those who have worked with `PyMongo`, providing a simple and intuitive way to work with document-based data in a relational database.\n\n**Keywords**: NoSQL, NoSQLite, SQLite NoSQL, PyMongo alternative, SQLite document database, Python NoSQL, schemaless SQLite, MongoDB-like SQLite\n\n[![NeoSQLite: SQLite with a MongoDB Disguise](https://img.youtube.com/vi/iZXoEjBaFdU/0.jpg)](https://www.youtube.com/watch?v=iZXoEjBaFdU)\n\n## Features\n\n- **`PyMongo`-like API**: A familiar interface for developers experienced with MongoDB.\n- **NX-27017**: [MongoDB Wire Protocol Server](packages/nx_27017/README.md) — Use PyMongo with SQLite backend\n- **Schemaless Documents**: Store flexible JSON-like documents.\n- **Lazy Cursor**: `find()` returns a memory-efficient cursor for iterating over results.\n- **Raw Batch Support**: `find_raw_batches()` returns raw JSON data in batches for efficient processing.\n- **Advanced Indexing**: Single-key, compound-key, nested-key indexes, and FTS5 text search.\n- **ACID Transactions**: Full `ClientSession` API with PyMongo 4.x parity using SQLite SAVEPOINTs.\n- **Change Streams**: Native SQLite triggers for `watch()` — no replica set required.\n- **Advanced Aggregation**: `$setWindowFields`, `$graphLookup`, `$fill`, streaming `$facet`, and more.\n- **Tier-1 SQL Optimization**: Dozens of operators translated to native SQL for 10-100x speedup.\n- **Native `$jsonSchema`**: Query filtering and write-time validation via SQLite CHECK constraints.\n- **Window Functions**: Complete MongoDB 5.0+ suite (`$rank`, `$top`, `$bottom`, math operators).\n- **MongoDB-compatible ObjectId**: Full 12-byte specification with automatic generation.\n- **Full GridFS Support**: Modern `GridFSBucket` API plus legacy `GridFS` compatibility.\n- **Binary Data**: PyMongo-compatible `Binary` class with UUID support.\n- **AutoVacuum \u0026 compact**: Reclaim disk space with incremental or full VACUUM.\n- **dbStats Command**: MongoDB-compatible statistics with accurate index sizes.\n- **SQL Translation Caching**: 10-30% faster for repeated aggregation pipelines and `$expr` queries.\n- **Configurable Journal Mode**: WAL (default), DELETE, MEMORY, and more.\n- **Security Hardening**: Built-in SQL injection protection via centralized identifier quoting.\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full history.\n\n## Latest Release: v1.14.5\n\nNeoSQLite v1.14.5 is a **feature enhancement release** that adds native FTS5 BM25 text relevance scoring to aggregation pipelines and enables `$push`/`$addToSet` with nested object expressions in `$group` stages.\n\n**Key Features:** Native text search relevance scoring via `$meta: \"textScore\"`, and full support for collecting nested objects during `$group` operations.\n\n### Key Features \u0026 Fixes\n\n- **$meta: textScore**: Native FTS5 BM25 relevance scoring in aggregation pipelines.\n- **$push/$addToSet with Expressions**: Collect nested objects during `$group` with `{'$push': {'title': '$title', 'author': '$author'}}`.\n- **Kill Switch Support**: Both features respect force fallback for debugging.\n\nFor full details, see [documents/releases/v1.14.5.md](documents/releases/v1.14.5.md).\n\n## Installation\n\n```bash\npip install neosqlite\n```\n\n### Optional Extras\n\n```bash\n# Enhanced JSON/JSONB support (only needed if your SQLite lacks JSON functions)\npip install neosqlite[jsonb]\n\n# Memory-constrained processing for large result sets\npip install neosqlite[memory-constrained]\n\n# NX-27017 MongoDB Wire Protocol Server\npip install \"neosqlite[nx27017]\"          # Core\npip install \"neosqlite[nx27017-speed]\"    # With uvloop (Linux/macOS)\n```\n\n## Quickstart\n\n```python\nimport neosqlite\n\nwith neosqlite.Connection(':memory:') as conn:\n    users = conn.users\n\n    # Insert\n    users.insert_one({'name': 'Alice', 'age': 30})\n    users.insert_many([\n        {'name': 'Bob', 'age': 25},\n        {'name': 'Charlie', 'age': 35}\n    ])\n\n    # Find\n    alice = users.find_one({'name': 'Alice'})\n    for user in users.find():\n        print(user)\n\n    # Update\n    users.update_one({'name': 'Alice'}, {'$set': {'age': 31}})\n\n    # Delete \u0026 Count\n    result = users.delete_many({'age': {'$gt': 30}})\n    print(f\"Remaining: {users.count_documents({})}\")\n```\n\n## Drop-in Replacement for PyMongo\n\n### 1. Direct API (No MongoDB)\n\n```python\nimport neosqlite\nclient = neosqlite.Connection('mydatabase.db')\ncollection = client.mycollection\ncollection.insert_one({\"name\": \"test\"})\n```\n\n### 2. Wire Protocol (NX-27017) — Zero Code Changes\n\n```bash\n# Start server\nnx-27017 --db ./myapp.db\n```\n\n```python\n# Then use PyMongo normally — no code changes!\nfrom pymongo import MongoClient\nclient = MongoClient('mongodb://localhost:27017/')\ncollection = client.mydatabase.mycollection\ncollection.insert_one({\"name\": \"test\"})  # Works!\n```\n\n## PyMongo Compatibility\n\n| Metric | Result |\n|--------|--------|\n| **Total Tests** | 386 |\n| **Passed** | 368 |\n| **Skipped** | 18 (architectural differences) |\n| **Failed** | 0 |\n| **Compatibility** | **100%** |\n\nSkipped tests are due to MongoDB requiring a replica set (change streams, transactions) or NeoSQLite extensions (`$log2`, `$contains`). All comparable APIs pass.\n\nRun the comparison yourself: `./scripts/run-api-comparison.sh`\n\n## Key APIs\n\n### Indexes\n\n```python\n# Single-key, compound, nested\nusers.create_index('age')\nusers.create_index([('name', neosqlite.ASCENDING), ('age', neosqlite.DESCENDING)])\nusers.create_index('profile.followers')\n\n# FTS5 text search\nusers.create_search_index('bio')\n```\n\n### Query Operators\n\n`$eq`, `$gt`, `$gte`, `$lt`, `$lte`, `$ne`, `$in`, `$nin`, `$and`, `$or`, `$not`, `$nor`,\n`$exists`, `$type`, `$regex`, `$elemMatch`, `$size`, `$mod`,\n`$bitsAllSet`, `$bitsAllClear`, `$bitsAnySet`, `$bitsAnyClear`,\n`$text` (FTS5), `$jsonSchema`, and more.\n\n### Aggregation Stages\n\n`$match`, `$project`, `$group`, `$sort`, `$skip`, `$limit`, `$unwind`,\n`$lookup`, `$facet`, `$bucket`, `$bucketAuto`, `$sample`, `$merge`,\n`$setWindowFields`, `$graphLookup`, `$fill`, `$densify`, `$unionWith`,\n`$replaceRoot`, `$replaceWith`, `$unset`, `$count`, `$redact`, `$addFields`, `$switch`.\n\n### Transactions\n\n```python\nwith client.start_session() as session:\n    with session.start_transaction():\n        users.insert_one({\"name\": \"Alice\"}, session=session)\n        orders.insert_one({\"user\": \"Alice\"}, session=session)\n    # Commits on success, rolls back on exception\n```\n\n### Change Streams\n\n```python\n# Native SQLite triggers — no replica set needed\nstream = collection.watch()\nfor change in stream:\n    print(change)\n```\n\n### Journal Mode\n\n```python\nfrom neosqlite import Connection, JournalMode\n\ndb = Connection(\"app.db\", journal_mode=JournalMode.WAL)  # Default\n```\n\n| Mode | Use Case |\n|------|----------|\n| **WAL** | Best concurrency (default) |\n| **DELETE** | Single-file distribution |\n| **MEMORY** | Maximum speed, no crash recovery |\n\n## Documentation\n\n| Topic | Link |\n|-------|------|\n| Release Notes | [documents/releases/](documents/releases/) |\n| Changelog | [CHANGELOG.md](CHANGELOG.md) |\n| GridFS | [documents/GRIDFS.md](documents/GRIDFS.md) |\n| Text Search | [documents/TEXT_SEARCH.md](documents/TEXT_SEARCH.md) |\n| Aggregation Optimization | [documents/AGGREGATION_PIPELINE_OPTIMIZATION.md](documents/AGGREGATION_PIPELINE_OPTIMIZATION.md) |\n| NX-27017 Server | [packages/nx_27017/README.md](packages/nx_27017/README.md) |\n| API Comparison | [examples/api_comparison/README.md](examples/api_comparison/README.md) |\n\n## Contributing\n\nClone the repository:\n\n```bash\ngit clone https://github.com/cwt/neosqlite.git\ncd neosqlite\n```\n\nCreate and activate a virtual environment:\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\n```\n\nThen run the test script, which installs all required dependencies automatically:\n\n```bash\n./scripts/runtest.sh\n```\n\n### Shell Script Compatibility\n\nAll shell scripts in this project target **bash 3.2+** for compatibility with macOS, which still ships with bash 3.2.x. Please ensure any contributions to shell scripts remain compatible.\n\n## Contribution and License\n\nThis project was originally developed as [shaunduncan/nosqlite](https://github.com/shaunduncan/nosqlite) and was later forked as [plutec/nosqlite](https://github.com/plutec/nosqlite) before becoming NeoSQLite. It is now maintained by Chaiwat Suttipongsakul and is licensed under the MIT license.\n\nContributions are highly encouraged. If you find a bug, have an enhancement in mind, or want to suggest a new feature, please feel free to open an issue or submit a pull request.\n","funding_links":["https://github.com/sponsors/cwt","https://liberapay.com/cwt","https://paypal.me/chaiwat"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcwt%2Fneosqlite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcwt%2Fneosqlite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcwt%2Fneosqlite/lists"}