Initiall commit
This commit is contained in:
216
README.md
216
README.md
@@ -1,2 +1,216 @@
|
||||
# turborfq
|
||||
# MariaDB Excel-like 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 <your-repo-url> 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.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This project is intended as a starting point/template.
|
||||
Use and adapt it freely within your environment and licensing requirements of the included libraries (e.g., Tabulator, Slim, etc.).
|
||||
```
|
||||
Reference in New Issue
Block a user