{"id":27141351,"url":"https://github.com/spinualexandru/mara-db","last_synced_at":"2025-10-29T22:38:52.980Z","repository":{"id":286612165,"uuid":"961940507","full_name":"spinualexandru/mara-db","owner":"spinualexandru","description":"Simple file based JSON database with NOSQL-like methods","archived":false,"fork":false,"pushed_at":"2025-04-07T18:43:24.000Z","size":31,"stargazers_count":5,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T14:19:30.154Z","etag":null,"topics":["database","db","json","love","love2d","lua","nosql"],"latest_commit_sha":null,"homepage":"https://github.com/spinualexandru/mara-db","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spinualexandru.png","metadata":{"files":{"readme":"README.md","changelog":null,"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},"funding":null},"created_at":"2025-04-07T12:06:34.000Z","updated_at":"2025-04-09T23:15:46.000Z","dependencies_parsed_at":"2025-04-10T00:58:01.160Z","dependency_job_id":"02f9f3cc-f934-40e7-bcfe-e46ff0310524","html_url":"https://github.com/spinualexandru/mara-db","commit_stats":null,"previous_names":["spinualexandru/mara-db"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/spinualexandru/mara-db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinualexandru%2Fmara-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinualexandru%2Fmara-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinualexandru%2Fmara-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinualexandru%2Fmara-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spinualexandru","download_url":"https://codeload.github.com/spinualexandru/mara-db/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinualexandru%2Fmara-db/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281713030,"owners_count":26548728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-29T02:00:06.901Z","response_time":59,"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","db","json","love","love2d","lua","nosql"],"created_at":"2025-04-08T06:48:34.184Z","updated_at":"2025-10-29T22:38:52.965Z","avatar_url":"https://github.com/spinualexandru.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![MaraDB Tests](https://github.com/spinualexandru/mara-db/actions/workflows/tests.yml/badge.svg)](https://github.com/spinualexandru/mara-db/actions/workflows/tests.yml)\n\n# MaraDB\n\nMaraDB is a lightweight document database for Lua with JSON persistence. It provides an easy-to-use interface for\nstoring, retrieving, and manipulating structured data.\n\n## Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Basic Usage](#basic-usage)\n    - [Opening a Database](#opening-a-database)\n    - [Working with Collections](#working-with-collections)\n- [CRUD Operations](#crud-operations)\n    - [Insert](#insert)\n    - [Query](#query)\n    - [Update](#update)\n    - [Upsert](#upsert-update-or-insert)\n    - [Delete](#delete)\n- [Indexing](#indexing)\n- [Working with Nested Data](#working-with-nested-data)\n- [Complete Example](#complete-example)\n- [Love2D Examples](examples/love2d)\n    - [Basic Usage in Love2D](examples/love2d/basic.lua)\n    - [Game Inventory System](examples/love2d/game_inventory.lua)\n    - [Player Save System](examples/love2d/save_system.lua)\n    - [High Score System](examples/love2d/high_score.lua)\n    - [Dialog and Quest System](examples/love2d/quest_dialog.lua)\n- [License](#license)\n\n## Features\n\n- Document-oriented storage\n- Collection-based organization\n- JSON persistence\n- Indexing and unique constraints\n- Support for nested objects and arrays\n- Full CRUD operations (Create, Read, Update, Delete)\n\n## Installation\n\nSimply include the `maradb.lua` file in your project:\n\n```lua\nlocal maradb = require('maradb')\n```\n\n## Basic Usage\n\n### Opening a Database\n\n```lua\n-- Open a database (creates it if it doesn't exist)\nlocal db = maradb.open(\"my_database\")\n\n-- Save changes and close when done\ndb:close()\n```\n\n### Working with Collections\n\n```lua\n-- Get or create a collection\nlocal users = db:collection(\"users\")\n\n-- Insert a document\nusers:insert({ name = \"Alice\", email = \"alice@example.com\", age = 30 })\n\n-- Close the database when done\ndb:close()\n```\n\n## CRUD Operations\n\n### Insert\n\n```lua\n-- Insert a document\nusers:insert({ name = \"Bob\", email = \"bob@example.com\", age = 25 })\n\n-- Insert a simple string value\ntags:insert(\"important\")\n```\n\n### Query\n\n```lua\n-- Find all matching documents\nlocal active_users = users:where({ status = \"active\" })\n\n-- Get a single matching document\nlocal user = users:get({ email = \"alice@example.com\" })\n\n-- Find with multiple conditions\nlocal admins = users:where({ status = \"active\", role = \"admin\" })\n```\n\n### Update\n\n```lua\n-- Update all matching documents\nusers:update({ status = \"active\" }, { last_seen = \"today\" })\n\n-- Find and update in one operation (returns updated documents)\nlocal updated_users = users:where({ status = \"active\" }, { level = 2 })\n```\n\n### Upsert (Update or Insert)\n\n```lua\n-- Update if exists, insert if not\nusers:upsert({ email = \"charlie@example.com\" }, { name = \"Charlie\", level = 1 })\n```\n\n### Delete\n\n```lua\n-- Remove all matching documents\nusers:remove({ status = \"inactive\" })\n\n-- Clear all documents in collection\nusers:purge()\n```\n\n## Indexing\n\n```lua\n-- Create an index (default: unique = true)\nusers:createIndex(\"email\")\n\n-- Create a non-unique index\nusers:createIndex(\"status\", { unique = false })\n```\n\n## Working with Nested Data\n\n```lua\n-- Insert document with nested structure\nposts:insert({\n    title = \"Hello World\",\n    author = {\n        name = \"Alice\",\n        email = \"alice@example.com\"\n    },\n    tags = { \"lua\", \"database\", \"tutorial\" },\n    comments = {\n        { user = \"Bob\", text = \"Great post!\" },\n        { user = \"Charlie\", text = \"Thanks for sharing!\" }\n    }\n})\n\n-- Query nested document\nlocal post = posts:get({ \"author.name\" = \"Alice\" })\n```\n\n## Complete Example\n\n```lua\nlocal maradb = require('maradb')\n\n-- Open database\nlocal db = maradb.open(\"blog\")\n\n-- Create collections\nlocal users = db:collection(\"users\")\nlocal posts = db:collection(\"posts\")\n\n-- Create indexes\nusers:createIndex(\"email\")\nposts:createIndex(\"slug\")\n\n-- Insert users\nusers:insert({ name = \"Alice\", email = \"alice@example.com\", role = \"admin\" })\nusers:insert({ name = \"Bob\", email = \"bob@example.com\", role = \"editor\" })\n\n-- Insert posts\nposts:insert({\n    title = \"Getting Started with MaraDB\",\n    slug = \"getting-started\",\n    content = \"This is a tutorial on using MaraDB...\",\n    author = \"alice@example.com\",\n    tags = { \"tutorial\", \"database\" }\n})\n\n-- Query data\nlocal admin_users = users:where({ role = \"admin\" })\nprint(\"Admin users:\", #admin_users)\n\n-- Update data\nusers:update({ name = \"Bob\" }, { status = \"active\" })\n\n-- Upsert data\nusers:upsert({ email = \"charlie@example.com\" }, {\n    name = \"Charlie\",\n    role = \"contributor\",\n    status = \"new\"\n})\n\n-- Save changes\ndb:close()\n```\n\n## License\n\nMIT License with Attribution Clause. See the [LICENSE](LICENSE) file for details.\n\nWhen used in commercial products, attribution is required: \"This product/service uses software created by\nAlexandru-Mihai Spinu.\"","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspinualexandru%2Fmara-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspinualexandru%2Fmara-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspinualexandru%2Fmara-db/lists"}