{"id":34094147,"url":"https://github.com/7s9n/pylowdb","last_synced_at":"2026-06-09T12:01:23.365Z","repository":{"id":62354920,"uuid":"443016377","full_name":"7s9n/pylowdb","owner":"7s9n","description":"Tiny local JSON database for Python.","archived":false,"fork":false,"pushed_at":"2022-01-04T01:46:27.000Z","size":32,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-10T14:06:31.888Z","etag":null,"topics":["database","json","local","nosql","nosql-database","python","python3"],"latest_commit_sha":null,"homepage":"https://github.com/Ho011/pylowdb","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/7s9n.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}},"created_at":"2021-12-30T08:39:34.000Z","updated_at":"2026-01-05T02:35:07.000Z","dependencies_parsed_at":"2022-10-31T10:48:12.256Z","dependency_job_id":null,"html_url":"https://github.com/7s9n/pylowdb","commit_stats":null,"previous_names":["ho011/pylowdb"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/7s9n/pylowdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7s9n%2Fpylowdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7s9n%2Fpylowdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7s9n%2Fpylowdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7s9n%2Fpylowdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/7s9n","download_url":"https://codeload.github.com/7s9n/pylowdb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7s9n%2Fpylowdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34105565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"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","json","local","nosql","nosql-database","python","python3"],"created_at":"2025-12-14T15:01:02.890Z","updated_at":"2026-06-09T12:01:23.340Z","avatar_url":"https://github.com/7s9n.png","language":"Python","funding_links":["https://www.buymeacoffee.com/HusseinSarea"],"categories":[],"sub_categories":[],"readme":"# Pylowdb\n\n[![Downloads](https://pepy.tech/badge/pylowdb)](https://pepy.tech/project/pylowdb)\n[![Downloads](https://pepy.tech/badge/pylowdb/month)](https://pepy.tech/project/pylowdb)\n\n\u003e Simple to use local JSON database 🦉\n\n```python\n# This is pure python, not specific to pylowdb ;)\ndb.data['posts'] = ({ 'id': 1, 'title': 'pylowdb is awesome' })\n\n# Save to file\ndb.write()\n```\n\n```python\n# db.json\n{\n  \"posts\": [\n    { \"id\": 1, \"title\": \"pylowdb is awesome\" }\n  ]\n}\n```\n\n## Support me\n\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/HusseinSarea)\n\n## Features\n\n- __Lightweight__\n- __Minimalist__ and easy to learn API\n- Query and modify data using __plain Python__\n- Atomic write\n- Hackable:\n  - Change storage, file format (JSON, YAML, ...) or add encryption via [adapters](#adapters)\n\n## Install\n\n```python\npip install pylowdb\n```\n\n## Usage\n\n```python\nimport os\nfrom os import path\nfrom pylowdb import (\n    Low,\n    JSONFile,\n)\n\n# Use JSON file for storage\nfile = path.join(os.getcwd(), 'db.json')\nadapter = JSONFile(file)\ndb = Low(adapter)\n\n# Read data from JSON file, this will set db.data content\ndb.read()\n\n# If file.json doesn't exist, db.data will be None\n# Set default data\n# db.data = db.data or { 'posts': [] }\ndb.data = db.data or { 'posts': [] }\n\n# Create and query items using plain Python\n\ndb.data['posts'].append('hello world')\ndb.data['posts'][0]\n\n# You can also use this syntax if you prefer\nposts = db.data['posts']\nposts.append('hello world')\n\n# Write db.data content to db.json\ndb.write()\n```\n\n```JSON\n// db.json\n{\n  \"posts\": [ \"hello world\" ]\n}\n```\n\n### More examples\n\nFor more example, see [`examples/`](/examples) directory.\n\n## API\n\n### Classes\n\nPylowdb has classes (for synchronous adapters).\n\n#### `Low(adapter)`\n\n```python\nfrom pylowdb import (\n    Low,\n    JSONFile,\n)\ndb = Low(JSONFile('file.json'))\ndb.read()\ndb.write()\n```\n\n### Methods\n\n#### `db.read()`\n\nCalls `adapter.read()` and sets `db.data`.\n\n**Note:** `JSONFile` adapter will set `db.data` to `None` if file doesn't exist.\n\n```python\ndb.data  # is None\ndb.read()\ndb.data # is not None\n```\n\n#### `db.write()`\n\nCalls `adapter.write(db.data)`.\n\n```python\ndb.data = { 'posts': [] }\ndb.write() # file.json will be { posts: [] }\ndb.data = {}\ndb.write() # file.json will be {}\n```\n\n### Properties\n\n#### `db.data`\n\nHolds your db content. If you're using the adapters coming with pylowdb, it can be any type supported by [`json.dumbs`](https://docs.python.org/3/library/json.html).\n\nFor example:\n\n```python\ndb.data = 'string'\ndb.data = [1, 2, 3]\ndb.data = { 'key': 'value' }\n```\n\n## Adapters\n\n### Pylowdb adapters\n\n#### `JSONFile`\n\nAdapter for reading and writing JSON files.\n\n```python\nLow(JSONFile(filename))\n```\n\n#### `Memory`\n\nIn-memory adapter. Useful for speeding up unit tests.\n\n```python\nLow(Memory())\n```\n\n#### `YAMLFile`\n\nAdapter for reading and writing YAML files.\n\n```python\nLow(YAMLFile(filename))\n```\n\n#### `TextFile`\n\nAdapters for reading and writing text. Useful for creating custom adapters.\n\n### Third-party adapters\n\nIf you've published an adapter for pylowdb, feel free to create a PR to add it here.\n\n### Writing your own adapter\n\nYou may want to create an adapter to write `db.data` to YAML, XML, encrypt data, a remote storage, ...\n\nAn adapter is a simple class that just needs to expose two methods:\n\n```python\nclass CustomAdapter:\n    read(self):\n        # should return deserialized data\n        pass\n    write(self, data):\n        # should return nothing\n        pass\n```\n\nFor example, let's say you have some async storage and want to create an adapter for it:\n\n```python\napi = YourAPI()\n\nclass CustomAdapter:\n    # Optional: your adapter can take arguments\n\n    def __init__(self, *args, **kwargs):\n        pass\n\n    def read(self):\n        data = api.read()\n    return data\n\n    def write(self, data):\n        api.write(data)\n\nadapter = CustomAdapter()\ndb = Low(adapter)\n```\n\nSee [`pylowdb/adapters`](pylowdb/adapters.py) for more examples.\n\n#### Custom serialization\n\nTo create an adapter for another format than JSON, you can use\n`TextFile`.\n\nFor example:\n\n```python\nfrom pylowdb import (\n    Adapter,\n    Low,\n    TextFile,\n)\nimport yaml\n\nclass YAMLFile(Adapter):\n    def __init__(self, filename: str):\n        self.adapter = TextFile(filename)\n\n    def read(self):\n        data = self.adapter.read()\n        if data is None:  \n            return null\n        else:\n            return YAML.deserialize(data)\n\n    def write(self, obj):\n        return self.adapter.write(YAML.serialize(obj))\n\nadapter = YAMLFile('file.yaml')\ndb = Low(adapter)\n```\n\n## Limits\n\nIf you have large Python objects (`~10-100MB`) you may hit some performance issues. This is because whenever you call `db.write`, the whole `db.data` is serialized and written to storage.\n\nDepending on your use case, this can be fine or not. It can be mitigated by doing batch operations and calling `db.write` only when you need it.\n\nIf you plan to scale, it's highly recommended to use databases like PostgreSQL, MySql, Oracle ...\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7s9n%2Fpylowdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F7s9n%2Fpylowdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7s9n%2Fpylowdb/lists"}