244 lines
7.0 KiB
Markdown
244 lines
7.0 KiB
Markdown
# TurboRFQ - MariaDB 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`.
|
|
|
|
---
|
|
|
|
## Installation (Docker)
|
|
|
|
**Recommended method:**
|
|
|
|
```bash
|
|
docker pull git.mchus.pro/mchus/turborfq:latest
|
|
|
|
docker run -d \
|
|
--name turborfq \
|
|
-p 8080:8080 \
|
|
-e DB_HOST=your-mariadb-host \
|
|
-e DB_PORT=3306 \
|
|
git.mchus.pro/mchus/turborfq:latest
|
|
```
|
|
|
|
Open http://localhost:8080 in your browser.
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `DB_HOST` | localhost | MariaDB server address |
|
|
| `DB_PORT` | 3306 | MariaDB server port |
|
|
| `DB_CHARSET` | utf8mb4 | Connection charset |
|
|
|
|
---
|
|
|
|
## 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`.
|
|
- CSV import/export functionality.
|
|
- Database backup using mysqldump.
|
|
- Foreign key relationship support.
|
|
|
|
---
|
|
|
|
## 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
|
|
BackupService.php # Database backup functionality using mysqldump
|
|
```
|
|
|
|
---
|
|
|
|
## 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 (Manual)
|
|
|
|
If you prefer to run without Docker:
|
|
|
|
1. Clone 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
|
|
|
|
Connection settings are configured via environment variables (see table above).
|
|
|
|
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.
|
|
|
|
### CSV Operations
|
|
|
|
- **Import CSV**: Use the import button to upload CSV files for bulk data insertion
|
|
- **Export CSV**: Use the export button to download table data as CSV files
|
|
|
|
### Backup Operations
|
|
|
|
- **Database Backup**: Use the backup functionality to create database dumps using mysqldump
|
|
|
|
---
|
|
|
|
## 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 container logs: `docker logs turborfq`
|
|
|
|
- **"Not authenticated" / 401 responses**
|
|
Ensure you logged in successfully and that your browser accepts cookies (session).
|
|
|
|
- **Cannot connect to MariaDB**
|
|
- Verify `DB_HOST` and `DB_PORT` environment variables.
|
|
- Confirm credentials using `mysql` client or another tool.
|
|
- Check firewall and bind-address on the MariaDB server.
|
|
- If running in Docker, use host IP or `host.docker.internal` instead of `localhost`.
|
|
|
|
- **CSV import errors**
|
|
- Check that CSV files are properly formatted
|
|
- Ensure data types match the target table schema
|
|
- Review error messages for specific issues with rows or fields |