NeoSQLite - NoSQL for SQLite with PyMongo-like API
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.
Keywords: NoSQL, NoSQLite, SQLite NoSQL, PyMongo alternative, SQLite document database, Python NoSQL, schemaless SQLite, MongoDB-like SQLite
Features
PyMongo-like API: A familiar interface for developers experienced with MongoDB.- NX-27017: MongoDB Wire Protocol Server — Use PyMongo with SQLite backend
- Schemaless Documents: Store flexible JSON-like documents.
- Lazy Cursor:
find()returns a memory-efficient cursor for iterating over results. - Raw Batch Support:
find_raw_batches()returns raw JSON data in batches for efficient processing. - Advanced Indexing: Single-key, compound-key, nested-key indexes, and FTS5 text search.
- ACID Transactions: Full
ClientSessionAPI with PyMongo 4.x parity using SQLite SAVEPOINTs. - Change Streams: Native SQLite triggers for
watch()— no replica set required. - Advanced Aggregation:
$setWindowFields,$graphLookup,$fill, streaming$facet, and more. - Tier-1 SQL Optimization: Dozens of operators translated to native SQL for 10-100x speedup.
- Native
$jsonSchema: Query filtering and write-time validation via SQLite CHECK constraints. - Window Functions: Complete MongoDB 5.0+ suite (
$rank,$top,$bottom, math operators). - MongoDB-compatible ObjectId: Full 12-byte specification with automatic generation.
- Full GridFS Support: Modern
GridFSBucketAPI plus legacyGridFScompatibility. - Binary Data: PyMongo-compatible
Binaryclass with UUID support. - AutoVacuum & compact: Reclaim disk space with incremental or full VACUUM.
- dbStats Command: MongoDB-compatible statistics with accurate index sizes.
- SQL Translation Caching: 10-30% faster for repeated aggregation pipelines and
$exprqueries. - Configurable Journal Mode: WAL (default), DELETE, MEMORY, and more.
- Security Hardening: Built-in SQL injection protection via centralized identifier quoting.
See CHANGELOG.md for the full history.
Latest Release: v1.14.15
NeoSQLite v1.14.15 is a security and data integrity patch release addressing SQL injection vectors via unquoted collection names and fixing several data-loss edge cases.
Key Fixes:
- SQL Injection Hardening — Applied
quote_table_name()to cursor SQL f-strings and GridFS legacy migration. - Data Integrity — Fixed ChangeStream
_last_idordering (moved after commit),__del__accidental commit (now rolls back), and GridIn empty/exact-chunk MD5. - Correctness — ChangeStream ensures
_idcolumn exists before triggers;with_options()clones get independent_collectionsdicts. - New:
query_onlyCommand — Get/set SQLite read-only mode viaconn.command("query_only").
For full details, see documents/releases/v1.14.15.md.
Installation
pip install neosqlite
Optional Extras
# Enhanced JSON/JSONB support (only needed if your SQLite lacks JSON functions)
pip install neosqlite[jsonb]
# Memory-constrained processing for large result sets
pip install neosqlite[memory-constrained]
# NX-27017 MongoDB Wire Protocol Server
pip install "neosqlite[nx27017]" # Core
pip install "neosqlite[nx27017-speed]" # With uvloop (Linux/macOS)
Quickstart
import neosqlite
with neosqlite.Connection(':memory:') as conn:
users = conn.users
# Insert
users.insert_one({'name': 'Alice', 'age': 30})
users.insert_many([
{'name': 'Bob', 'age': 25},
{'name': 'Charlie', 'age': 35}
])
# Find
alice = users.find_one({'name': 'Alice'})
for user in users.find():
print(user)
# Update
users.update_one({'name': 'Alice'}, {'$set': {'age': 31}})
# Delete & Count
result = users.delete_many({'age': {'$gt': 30}})
print(f"Remaining: {users.count_documents({})}")
Drop-in Replacement for PyMongo
1. Direct API (No MongoDB)
import neosqlite
client = neosqlite.Connection('mydatabase.db')
collection = client.mycollection
collection.insert_one({"name": "test"})
2. Wire Protocol (NX-27017) — Zero Code Changes
# Start server
nx-27017 --db ./myapp.db
# Then use PyMongo normally — no code changes!
from pymongo import MongoClient
client = MongoClient('mongodb://localhost:27017/')
collection = client.mydatabase.mycollection
collection.insert_one({"name": "test"}) # Works!
PyMongo Compatibility
| Metric | Result |
|---|---|
| Total Tests | 379 |
| Passed | 361 |
| Skipped | 18 (architectural differences) |
| Failed | 0 |
| Compatibility | 100% |
Skipped tests are due to MongoDB requiring a replica set (change streams, transactions) or NeoSQLite extensions ($log2, $contains). All comparable APIs pass.
Run the comparison yourself: ./scripts/run-api-comparison.sh
Key APIs
Indexes
# Single-key, compound, nested
users.create_index('age')
users.create_index([('name', neosqlite.ASCENDING), ('age', neosqlite.DESCENDING)])
users.create_index('profile.followers')
# FTS5 text search
users.create_search_index('bio')
Query Operators
$eq, $gt, $gte, $lt, $lte, $ne, $in, $nin, $and, $or, $not, $nor,
$exists, $type, $regex, $elemMatch, $size, $mod,
$bitsAllSet, $bitsAllClear, $bitsAnySet, $bitsAnyClear,
$text (FTS5), $jsonSchema, and more.
Aggregation Stages
$match, $project, $group, $sort, $skip, $limit, $unwind,
$lookup, $facet, $bucket, $bucketAuto, $sample, $merge,
$setWindowFields, $graphLookup, $fill, $densify, $unionWith,
$replaceRoot, $replaceWith, $unset, $count, $redact, $addFields, $switch.
Transactions
with client.start_session() as session:
with session.start_transaction():
users.insert_one({"name": "Alice"}, session=session)
orders.insert_one({"user": "Alice"}, session=session)
# Commits on success, rolls back on exception
Change Streams
# Native SQLite triggers — no replica set needed
stream = collection.watch()
for change in stream:
print(change)
Journal Mode
from neosqlite import Connection, JournalMode
db = Connection("app.db", journal_mode=JournalMode.WAL) # Default
| Mode | Use Case |
|---|---|
| WAL | Best concurrency (default) |
| DELETE | Single-file distribution |
| MEMORY | Maximum speed, no crash recovery |
Documentation
| Topic | Link |
|---|---|
| Release Notes | documents/releases/ |
| Changelog | CHANGELOG.md |
| GridFS | documents/GRIDFS.md |
| Text Search | documents/TEXT_SEARCH.md |
| Aggregation Optimization | documents/AGGREGATION_PIPELINE_OPTIMIZATION.md |
| NX-27017 Server | packages/nx_27017/README.md |
| API Comparison | examples/api_comparison/README.md |
Contributing
Clone the repository:
git clone https://github.com/cwt/neosqlite.git
cd neosqlite
Create and activate a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
Then run the test script, which installs all required dependencies automatically:
./scripts/runtest.sh
Shell Script Compatibility
All 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.
Contribution and License
This project was originally developed as shaunduncan/nosqlite and was later forked as plutec/nosqlite before becoming NeoSQLite. It is now maintained by Chaiwat Suttipongsakul and is licensed under the MIT license.
Contributions 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file neosqlite-1.14.15.tar.gz.
File metadata
- Download URL: neosqlite-1.14.15.tar.gz
- Upload date:
- Size: 262.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.4.1 CPython/3.14.6 Linux/7.0.13-200.fc44.x86_64
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
44cfa0d87ff4b8f5afb5a29ded0e467e99c315f25b0842934963c11309ace8a0
|
|
| MD5 |
a5288ac565d8f8b3deaeaef66cbc6bbf
|
|
| BLAKE2b-256 |
c16a7e40a60933df707da615b375e3a56719fcece0ffb1c46d29b6da6145419d
|
File details
Details for the file neosqlite-1.14.15-py3-none-any.whl.
File metadata
- Download URL: neosqlite-1.14.15-py3-none-any.whl
- Upload date:
- Size: 298.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.4.1 CPython/3.14.6 Linux/7.0.13-200.fc44.x86_64
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4a1168d11f2f9f9f4c1a7ca0a79c775f83594154b6c18a416ea1e2b81e5e62d7
|
|
| MD5 |
fa5cb0a50ce66dcd7ebda60d6a9efe3f
|
|
| BLAKE2b-256 |
d7baacef0f94cafb555f35ab8efb1d2781f1ebbe062c1e7e2313df40a3263505
|
