Skip to content

Latest commit

 

History

History
176 lines (114 loc) · 4.67 KB

README.md

File metadata and controls

176 lines (114 loc) · 4.67 KB

MyDB - A Simple File-Based Database for LOVE2D

Introduction

MyDB is a lightweight, file-based database designed for small to medium-sized datasets. It leverages JSON files for storage and is tailored for projects needing an easy-to-manage database solution.

This project is primarily a hobby endeavor and may not receive frequent updates. Use it as-is for non-critical applications.

Features

  • JSON-based storage: Each table is stored as a separate JSON file, making it easy to read and manage.
  • Database and table management: Create, update, and manage databases and their tables effortlessly.
  • Support for structured tables: Use structured tables with predefined keys for consistency.
  • Lightweight: No additional dependencies beyond LOVE2D and a JSON library.
  • Dynamic merging: Combines existing data with new entries seamlessly.
  • Simple utilities: Includes helper functions for database validation and recovery.

Functions Overview

Database Functions

createDB(dbname)

Creates a new database directory with metadata stored in an info.json file.

Parameters:

  • dbname: The name of the database.

Throws an error if the database already exists.

dbExists(dbname)

Checks if a database exists.

Parameters:

  • dbname: The name of the database.

Returns:
true if the database exists, otherwise false.

getDbInfo(dbname)

Retrieves the metadata (info.json) of a specified database.

Parameters:

  • dbname: The name of the database.

Returns:
The metadata as a table, or nil if the database does not exist.

Table Functions

createTable(dbname, tablename, data)

Creates a new table in a database and populates it with initial data.

Parameters:

  • dbname: The database name.
  • tablename: The table name.
  • data: The initial data as a Lua table.

Throws an error if the table already exists or the database is missing.

tableExists(dbname, tablename)

Checks if a table exists in a database.

Parameters:

  • dbname: The database name.
  • tablename: The table name.

Returns:
true if the table exists, otherwise false.

getTableData(dbname, tablename)

Retrieves the data from a specified table.

Parameters:

  • dbname: The database name.
  • tablename: The table name.

Returns:
The table's data as a Lua table.

modifyTable(dbname, tablename, data)

Modifies an existing table's data by merging new data with the existing content.

Parameters:

  • dbname: The database name.
  • tablename: The table name.
  • data: The new data to merge (as a Lua table).

Throws an error if the table does not exist or the database is missing.

Structured Table Functions

createStructTable(dbname, tablename, struct)

Creates a structured table with predefined keys. Each entry must match the structure.

Parameters:

  • dbname: The database name.
  • tablename: The table name.
  • struct: A table defining the structure of each entry.

Throws an error if the table or database does not exist.

addStructData(dbname, tablename, vals)

Adds data to a structured table. Data must adhere to the table's predefined structure.

Parameters:

  • dbname: The database name.
  • tablename: The table name.
  • vals: The data to add, adhering to the structure.

Throws an error if keys are missing or the structure does not match.

getStructData(dbname, tablename, sno)

Retrieves data from a structured table. Optionally, fetch a specific record by its serial number (sno).

Parameters:

  • dbname: The database name.
  • tablename: The table name.
  • sno: (Optional) The record index to fetch.

Returns:

  • The entire table's data if no sno is provided.
  • A single record if sno is specified.

Filesystem Utilities

removeDbFile(dbname, file)

Deletes a file from the database directory. This function does not update the database's metadata.

Parameters:

  • dbname: The database name.
  • file: The name of the file to remove.

fixTableInfo(dbname)

Synchronizes the database's metadata (info.json) with the actual tables in the directory.

Parameters:

  • dbname: The database name.

Notes

  • Structured Tables: These tables enforce data consistency by requiring all entries to match a predefined structure.
  • Data Storage: All data is stored as JSON files within the database directory.
  • Error Handling: Errors are raised for operations on missing databases or tables.

Disclaimer

This is a hobby project and will not be updated frequently, if at all. Please use it at your own risk and for non-critical applications.