Metadata-Version: 2.4
Name: SQELDB
Version: 0.1.0
Summary: A simple ELDB engine for Python
Author: Baraa
Author-email: cenomi3041@gavrom.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-python
Dynamic: summary

# ELDB â€” Embedded Lightweight DB Engine

> Simple file-backed fixed-width record database for small projects and experimentation.

ELDB is a minimal, easy-to-use embedded database implemented in Python. It stores tables as binary files with a small text header and fixed-width records. This project is intended for learning, prototyping, and small single-user applications â€” not for production use.

**Features**
- **Tiny footprint**: each table is a single `.eldb` file under a database folder
- **Fixed-size fields**: supports `int` and fixed-length `str` columns
- **Simple API**: create/load tables, insert/select/update/delete rows, add/delete columns
- **Primary key index**: builds an in-memory index for a declared primary key on load

**Quick Links**
- Source: [ELDB_engine.py](ELDB_engine.py)

## Installation

No external dependencies â€” just Python 3.6+.

Clone or copy the repository files to your project folder. The engine writes table files to a folder (default `mydb`).

## Basic Usage

Example session using the `ELDB` class from `ELDB_engine.py`:

```python
from ELDB_engine import ELDB

# Create engine (defaults to folder 'mydb')
db = ELDB(db_folder='ELDB_Data')

# Define table schema: column -> {type, size, nullable}
columns = {
    'id': {'type': 'int', 'size': 4, 'nullable': False},
    'name': {'type': 'str', 'size': 50, 'nullable': False},
    'age': {'type': 'int', 'size': 4, 'nullable': True}
}

# Create table with a primary key
db.create_table('users', columns, primary_key='id', if_not_exists=True)

# Insert a row (note: columns with no value must be nullable or provide default)
db.insert('users', {'id': 1, 'name': 'Alice', 'age': 30})
db.insert('users', {'id': 2, 'name': 'Bob'})

# Select rows (where uses dict: column -> (operator, value))
rows = db.select('users', where={'age': ('>=', 18)}, order_by=('age', False), limit=10)
print(rows)

# Update rows
db.update('users', updates={'age': 31}, where={'id': ('=', 1)})

# Delete rows
db.delete('users', where={'id': ('=', 2)})

# Add a new column
db.add_column('users', 'email', column_type='str', size=100, nullable=True, default='')

# Delete table
# db.delete_table('users')
```

## API Reference

- `ELDB(db_folder='mydb')`
  - Create engine instance. `db_folder` is the folder where `.eldb` files live.

- `create_table(name, columns, primary_key=None, if_not_exists=False)`
  - `columns` is a dict mapping column name to options: `{'type': 'int'|'str', 'size': <int>, 'nullable': True|False}`.
  - `primary_key` (optional) column name to build an in-memory index on load.

- `load_table(table_name)`
  - Loads an existing `.eldb` table and builds the primary key index if present.

- `insert(table_name, row)`
  - `row` is a dict of column -> value. Type checks are performed.

- `select(table_name=None, where=None, order_by=None, limit=None, columns=None)`
  - `table_name`: choose specific table or `None` to select across all tables.
  - `where`: dict of column -> (operator, value), operators: `=, !=, >, <, >=, <=`.
  - `order_by`: tuple `(column, reverse)` where `reverse` is `True` for descending.
  - `limit`: maximum number of rows to return.
  - `columns`: list of column names to return.

- `update(table_name, updates, where=None)`
  - `updates` is a dict of column -> new value.

- `delete(table_name, where=None)`
  - Remove rows matching `where` â€” omit `where` to remove all rows.

- `add_column(table_name, column_name, column_type='str', size=50, nullable=True, default=None)`
  - Adds a column to the schema and writes the default value to existing rows.

- `delete_column(table_name, column_name)`
  - Removes a column from the schema and from existing rows.

- `clear_table(table_name)`
  - Remove all rows from a table (keeps file and schema).

- `delete_table(table_name)` and `drop_all_tables()`
  - Remove files from disk.

## Table File Format

Each table is stored as a `.eldb` file under the database folder. The file begins with a single text header line (a Python dictionary representation) that contains the `columns` schema, `primary_key`, and `row_count`. Following the header, records are stored as fixed-size binary blobs. String columns are fixed-length and padded with NUL bytes; integers are 4-byte little-endian signed integers using Python's `struct` format `i`.

Note: The header is written using `str()` and read with `eval()` in the current implementation. This is simple but unsafe for untrusted inputs; do not open files from unknown sources.

## Limitations & Notes

- Binary fixed-width format: you must choose adequate `size` for `str` columns.
- No concurrency control: this engine is not safe for concurrent writers.
- Header uses `eval()` and thus can execute arbitrary code if the file is tampered with â€” treat files as untrusted.
- Index is in-memory and rebuilt on load; large tables will use more memory.

## Suggested Improvements

- Replace `eval()` with a safe serializer (JSON) for the header.
- Add transaction/locking and append-mode writes for better concurrency.
- Support variable-length fields or a simple heap for strings to save space.
- Add basic tests and a small CLI for table inspection.

## Development

Project files live in the repository root. The main engine source is [ELDB_engine.py](ELDB_engine.py).

To experiment interactively, run `python` in the project folder and import the `ELDB` class.

## Contributing

Feel free to open issues or create pull requests with improvements, tests, or bug fixes.

## License

This project is provided as-is for learning and prototyping. No explicit license file is included.
