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:

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 for interactive data grid (filters, pagination, editing)

---

Project Structure

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):

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

Install Composer globally (simplified example):

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:

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

2. Install PHP dependencies:

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:

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