# neosqlite
`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.
## Features
- **`pymongo`-like API**: A familiar interface for developers experienced with MongoDB.
- **Schemaless Documents**: Store flexible JSON-like documents.
- **Lazy Cursor**: `find()` returns a memory-efficient cursor for iterating over results.
- **Advanced Indexing**: Supports single-key, compound-key, and nested-key indexes.
- **Modern API**: Aligned with modern `pymongo` practices (using methods like `insert_one`, `update_one`, `delete_many`, etc.).
- **Automatic JSON/JSONB Support**: Automatically detects and uses JSONB column type when available for better performance.
## Installation
```bash
pip install neosqlite
```
For enhanced JSON/JSONB support on systems where the built-in SQLite doesn't support these features, you can install with the `jsonb` extra:
```bash
pip install neosqlite[jsonb]
```
This will install `pysqlite3-binary` which provides a newer version of SQLite with JSON/JSONB support compiled in.
**Note**: `neosqlite` will work with any SQLite installation. The `jsonb` extra is only needed if:
1. Your system's built-in SQLite doesn't support JSON functions, **and**
2. You want to take advantage of JSONB column type for better performance with JSON operations
If your system's SQLite already supports JSONB column type, `neosqlite` will automatically use them without needing the extra dependency.
## Quickstart
Here is a quick example of how to use `neosqlite`:
```python
import neosqlite
# Connect to an in-memory database
with neosqlite.Connection(':memory:') as conn:
# Get a collection
users = conn.users
# Insert a single document
users.insert_one({'name': 'Alice', 'age': 30})
# Insert multiple documents
users.insert_many([
{'name': 'Bob', 'age': 25},
{'name': 'Charlie', 'age': 35}
])
# Find a single document
alice = users.find_one({'name': 'Alice'})
print(f"Found user: {alice}")
# Find multiple documents and iterate using the cursor
print("\nAll users:")
for user in users.find():
print(user)
# Update a document
users.update_one({'name': 'Alice'}, {'$set': {'age': 31}})
print(f"\nUpdated Alice's age: {users.find_one({'name': 'Alice'})}")
# Delete documents
result = users.delete_many({'age': {'$gt': 30}})
print(f"\nDeleted {result.deleted_count} users older than 30.")
# Count remaining documents
print(f"There are now {users.count_documents({})} users.")
```
## JSON/JSONB Support
`neosqlite` automatically detects JSON support in your SQLite installation:
- **With JSON/JSONB support**: Uses JSONB column type for better performance with JSON operations
- **Without JSON support**: Falls back to TEXT column type with JSON serialization
The library will work correctly in all environments - the `jsonb` extra is completely optional and only needed for enhanced performance on systems where the built-in SQLite doesn't support JSONB column type.
## Indexes
Indexes can significantly speed up query performance. `neosqlite` supports single-key, compound-key, and nested-key indexes.
```python
# Create a single-key index
users.create_index('age')
# Create a compound index
users.create_index([('name', neosqlite.ASCENDING), ('age', neosqlite.DESCENDING)])
# Create an index on a nested key
users.insert_one({'name': 'David', 'profile': {'followers': 100}})
users.create_index('profile.followers')
# Create multiple indexes at once
users.create_indexes([
'age',
[('name', neosqlite.ASCENDING), ('age', neosqlite.DESCENDING)],
'profile.followers'
])
```
Indexes are automatically used by `find()` operations where possible. You can also provide a `hint` to force the use of a specific index.
## Sorting
You can sort the results of a `find()` query by chaining the `sort()` method.
```python
# Sort users by age in descending order
for user in users.find().sort('age', neosqlite.DESCENDING):
print(user)
```
## Contribution and License
This project was originally developed by Shaun Duncan and is now maintained by Chaiwat Suttipongsakul. It 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.
Raw data
{
"_id": null,
"home_page": "https://sr.ht/~cwt/neosqlite",
"name": "neosqlite",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "nosql, sqlite, neosqlite",
"author": "Chaiwat Suttipongsakul",
"author_email": "cwt@bashell.com",
"download_url": "https://files.pythonhosted.org/packages/ae/f0/b05f235c7be1e2bb6c93e86f93e93d4974338f4e177ec5e515b06e36862d/neosqlite-0.2.0.tar.gz",
"platform": null,
"description": "# 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## Features\n\n- **`pymongo`-like API**: A familiar interface for developers experienced with MongoDB.\n- **Schemaless Documents**: Store flexible JSON-like documents.\n- **Lazy Cursor**: `find()` returns a memory-efficient cursor for iterating over results.\n- **Advanced Indexing**: Supports single-key, compound-key, and nested-key indexes.\n- **Modern API**: Aligned with modern `pymongo` practices (using methods like `insert_one`, `update_one`, `delete_many`, etc.).\n- **Automatic JSON/JSONB Support**: Automatically detects and uses JSONB column type when available for better performance.\n\n## Installation\n\n```bash\npip install neosqlite\n```\n\nFor enhanced JSON/JSONB support on systems where the built-in SQLite doesn't support these features, you can install with the `jsonb` extra:\n\n```bash\npip install neosqlite[jsonb]\n```\n\nThis will install `pysqlite3-binary` which provides a newer version of SQLite with JSON/JSONB support compiled in.\n\n**Note**: `neosqlite` will work with any SQLite installation. The `jsonb` extra is only needed if:\n1. Your system's built-in SQLite doesn't support JSON functions, **and**\n2. You want to take advantage of JSONB column type for better performance with JSON operations\n\nIf your system's SQLite already supports JSONB column type, `neosqlite` will automatically use them without needing the extra dependency.\n\n## Quickstart\n\nHere is a quick example of how to use `neosqlite`:\n\n```python\nimport neosqlite\n\n# Connect to an in-memory database\nwith neosqlite.Connection(':memory:') as conn:\n # Get a collection\n users = conn.users\n\n # Insert a single document\n users.insert_one({'name': 'Alice', 'age': 30})\n\n # Insert multiple documents\n users.insert_many([\n {'name': 'Bob', 'age': 25},\n {'name': 'Charlie', 'age': 35}\n ])\n\n # Find a single document\n alice = users.find_one({'name': 'Alice'})\n print(f\"Found user: {alice}\")\n\n # Find multiple documents and iterate using the cursor\n print(\"\\nAll users:\")\n for user in users.find():\n print(user)\n\n # Update a document\n users.update_one({'name': 'Alice'}, {'$set': {'age': 31}})\n print(f\"\\nUpdated Alice's age: {users.find_one({'name': 'Alice'})}\")\n\n # Delete documents\n result = users.delete_many({'age': {'$gt': 30}})\n print(f\"\\nDeleted {result.deleted_count} users older than 30.\")\n\n # Count remaining documents\n print(f\"There are now {users.count_documents({})} users.\")\n```\n\n## JSON/JSONB Support\n\n`neosqlite` automatically detects JSON support in your SQLite installation:\n\n- **With JSON/JSONB support**: Uses JSONB column type for better performance with JSON operations\n- **Without JSON support**: Falls back to TEXT column type with JSON serialization\n\nThe library will work correctly in all environments - the `jsonb` extra is completely optional and only needed for enhanced performance on systems where the built-in SQLite doesn't support JSONB column type.\n\n## Indexes\n\nIndexes can significantly speed up query performance. `neosqlite` supports single-key, compound-key, and nested-key indexes.\n\n```python\n# Create a single-key index\nusers.create_index('age')\n\n# Create a compound index\nusers.create_index([('name', neosqlite.ASCENDING), ('age', neosqlite.DESCENDING)])\n\n# Create an index on a nested key\nusers.insert_one({'name': 'David', 'profile': {'followers': 100}})\nusers.create_index('profile.followers')\n\n# Create multiple indexes at once\nusers.create_indexes([\n 'age',\n [('name', neosqlite.ASCENDING), ('age', neosqlite.DESCENDING)],\n 'profile.followers'\n])\n```\n\nIndexes are automatically used by `find()` operations where possible. You can also provide a `hint` to force the use of a specific index.\n\n## Sorting\n\nYou can sort the results of a `find()` query by chaining the `sort()` method.\n\n```python\n# Sort users by age in descending order\nfor user in users.find().sort('age', neosqlite.DESCENDING):\n print(user)\n```\n\n## Contribution and License\n\nThis project was originally developed by Shaun Duncan and is now maintained by Chaiwat Suttipongsakul. It 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",
"bugtrack_url": null,
"license": "MIT",
"summary": "A wrapper for sqlite3 to have schemaless, document-store features",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://sr.ht/~cwt/neosqlite",
"Repository": "https://hg.sr.ht/~cwt/neosqlite"
},
"split_keywords": [
"nosql",
" sqlite",
" neosqlite"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2b33ea30f8ce1d71377e511fc499e4d476532fe49f7dfb7e79184518fd5a1569",
"md5": "0b6dc0b0d201b06db73d8f801614893f",
"sha256": "0ed110175a81399a6e2b085e380b4092441c596503165936e07fe1acc92a8aae"
},
"downloads": -1,
"filename": "neosqlite-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b6dc0b0d201b06db73d8f801614893f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 15024,
"upload_time": "2025-08-11T04:19:51",
"upload_time_iso_8601": "2025-08-11T04:19:51.811607Z",
"url": "https://files.pythonhosted.org/packages/2b/33/ea30f8ce1d71377e511fc499e4d476532fe49f7dfb7e79184518fd5a1569/neosqlite-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aef0b05f235c7be1e2bb6c93e86f93e93d4974338f4e177ec5e515b06e36862d",
"md5": "a5ee4194574670020d6fd622f1ec9229",
"sha256": "c87e881b60e4e17c4351ad1268b80295e7df821bbe0bb195b8ed95fac994ba20"
},
"downloads": -1,
"filename": "neosqlite-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "a5ee4194574670020d6fd622f1ec9229",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 15825,
"upload_time": "2025-08-11T04:19:53",
"upload_time_iso_8601": "2025-08-11T04:19:53.351915Z",
"url": "https://files.pythonhosted.org/packages/ae/f0/b05f235c7be1e2bb6c93e86f93e93d4974338f4e177ec5e515b06e36862d/neosqlite-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 04:19:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "neosqlite"
}
JSON