turborfq/README.md

# Turbo RFQ - MariaDB simple Web UI

A lightweight PHP web application that provides an Excel-like interface for browsing and editing MariaDB tables.  
Users authenticate with **their own MariaDB credentials**, and the app works with *any* schema by reading metadata from `information_schema`.

> Note: This README assumes a Linux environment with PHP 8.1+ and MariaDB available.

---

## Features

- Login with native MariaDB user/password (no separate app users).
- Side menu with database → table tree.
- Central Excel-like grid built dynamically from table metadata.
- Column header filters (per-column search).
- Server-side pagination.
- Basic CRUD operations:
  - Insert new rows.
  - Edit existing rows.
  - Delete rows.
- Generic, schema-agnostic behavior using `information_schema`.

---

## Tech Stack

- **Backend**
  - PHP 8.1+
  - Slim 4 (microframework for routing and middleware)
  - PHP-DI (dependency injection)
  - PDO (MariaDB/MySQL driver)

- **Frontend**
  - Vanilla JS
  - [Tabulator](https://tabulator.info/) for interactive data grid (filters, pagination, editing)

---

## Project Structure

```text
project/
  composer.json        # Project metadata and PHP dependencies
  vendor/              # Installed Composer packages (generated)
  public/
    index.php          # Front controller, routes, serves index.html
    index.html         # Basic layout (sidebar + toolbar + grid)
    app.js             # Frontend logic (Tabulator + API calls)
  src/
    Db.php             # PDO factory based on session credentials
    MetaService.php    # Schema/metadata from information_schema
    DataService.php    # Generic SELECT/INSERT/UPDATE/DELETE
```

---

## Prerequisites

- PHP 8.1+ with:
  - `pdo_mysql` extension enabled
  - `mbstring`, `xml` (typical for Composer and frameworks)
- Composer (global installation recommended)
- Access to a MariaDB server

Example (Debian/Ubuntu):

```bash
sudo apt update
sudo apt install php php-cli php-mbstring php-xml php-mysql unzip git
```

Install Composer globally (simplified example):

```bash
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir=/usr/local/bin --filename=composer
php -r "unlink('composer-setup.php');"
```

---

## Installation

1. Clone or copy the project:

```bash
cd /path/to
git clone https://git.mchus.pro/mchus/turborfq.git mariadb-grid
cd mariadb-grid
```

2. Install PHP dependencies:

```bash
composer install
```

This reads `composer.json` and installs Slim, PHP-DI and all required packages into `vendor/`.

---

## Configuration

By default, `Db.php` uses:

- Host: `localhost`
- Port: `3306`
- Charset: `utf8mb4`

If your MariaDB server is different, update the DSN in `src/Db.php`:

```php
$dsn = 'mysql:host=localhost;port=3306;charset=utf8mb4';
```

No database name is hardcoded: the app reads available schemas from `information_schema` and shows only those the connected user can see.

---

## Running the App (Development)

Use PHP’s built-in web server and point it to the `public` directory:

```bash
cd /path/to/mariadb-grid
php -S localhost:8080 -t public
```

Open in your browser:

```
http://localhost:8080/
```

> The built-in server is intended for development/testing only. For production use, configure a real web server (Nginx/Apache) with `public/` as document root and `index.php` as front controller.

---

## Usage

1. Open the app in a browser.
2. In the top login panel:
   - Enter MariaDB username.
   - Enter MariaDB password.
   - Click **“Login”**.
3. If the connection succeeds:
   - The left sidebar will show databases and tables as a tree.
4. Click any table:
   - The central Tabulator grid will load the table’s data.
   - Column header filters allow you to filter per column.
   - Pagination is handled server-side.

### CRUD operations

- **Insert**
  - Click **“Insert”**.
  - A new row is created (you can extend logic to open an editor or use default values).
- **Update**
  - Select a row (click to highlight it).
  - Edit cells directly in the grid.
  - Click **“Save row”** (or whatever label you use) to send the updated row to the backend.
- **Delete**
  - Select one or more rows.
  - Click **“Delete”**.
  - Confirm the deletion.

> Updates and deletes are performed using the table’s primary key.  
> If there is no primary key, it is safer to treat the table as read-only.

---

## How It Works (High Level)

- On login, the app tests a connection to MariaDB using the supplied credentials and stores them in the session.
- For all subsequent API requests, PDO is created with these credentials, so MariaDB’s own permissions control what the user can see and edit.
- `MetaService` queries `information_schema` to:
  - Build the schema → tables tree.
  - Load column definitions and detect the primary key.
- `DataService` builds generic, parameterized SQL statements for:
  - Paginated `SELECT` (with simple `LIKE` filters per column).
  - `INSERT` (skipping `auto_increment` columns).
  - `UPDATE` / `DELETE` by primary key.
- The frontend (Tabulator) requests data and metadata via JSON and renders an editable grid.

---

## Customization Ideas

- Map column `DATA_TYPE` to more specific editors (date picker, number editor, dropdowns).
- Add sorting synchronization (Tabulator sorters → backend `ORDER BY`).
- Add bulk insert/update operations using transactions.
- Add read-only mode for tables without primary keys.
- Add simple configuration file for allowed schemas, default page size, etc.

---

## Troubleshooting

- **Blank page or PHP errors**  
  Make sure `display_errors` is enabled in development, or check web server error logs.

- **“Not authenticated” / 401 responses**  
  Ensure you logged in successfully and that your browser accepts cookies (session).

- **Cannot connect to MariaDB**  
  - Verify host/port in `Db.php`.
  - Confirm credentials using `mysql` client or another tool.
  - Check firewall and bind-address on the MariaDB server.


```