turborfq/claude.md

TurboRFQ - MariaDB Web UI

TurboRFQ is 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.

Key Features

• Authentication: Native MariaDB user/password authentication (no separate app users)
• Schema Agnostic: Works with any schema by reading metadata from information_schema
• Excel-like Grid: Interactive data grid built with Tabulator
• Column Header Filters: Per-column search capabilities
• Server-side Pagination: Efficient handling of large datasets
• Full CRUD Operations: Insert, update, delete functionality
• CSV Import/Export: Bulk data operations
• Backup Functionality: Database backup using mysqldump
• Foreign Key Support: Proper handling of foreign key relationships

Architecture

Backend Components

1. Database Layer (Db.php):

   • PDO factory based on session credentials
   • Connection testing functionality
   • Session-based authentication

2. Metadata Service (MetaService.php):

   • Queries information_schema to build schema → tables tree
   • Loads column definitions and detects primary keys
   • Handles foreign key relationships
   • Provides editor type mapping for different data types

3. Data Service (DataService.php):

   • Generic SELECT operations with server-side pagination and filtering
   • INSERT operations (skipping auto_increment columns)
   • UPDATE/DELETE operations by primary key
   • CSV import with error handling and data validation
   • CSV export functionality
   • Mass delete operations
   • Backup functionality using mysqldump
   • Foreign key value suggestions

4. Backup Service (BackupService.php):

   • Database backup using mysqldump
   • Supports backup of individual databases or all databases
   • Temporary file management

Frontend Components

• index.html - Basic layout with sidebar, toolbar, and grid container
• app.js - Frontend logic using Tabulator for interactive data grid

API Endpoints

The application exposes a comprehensive RESTful API:

• Authentication (/api/login)
• Schema tree (/api/tree)
• Table metadata (/api/table/meta)
• Data operations (/api/table/data, /api/table/insert, /api/table/update, /api/table/delete)
• CSV import/export (/api/table/import-csv, /api/table/export-csv)
• Foreign key values (/api/fk-values)
• Batch operations (/api/table/delete-batch)
• Backup functionality (/api/backup/*)

Technology Stack

Backend:

• PHP 8.1+
• Slim 4 microframework
• PHP-DI (dependency injection)
• PDO (MariaDB/MySQL driver)

Frontend:

• Vanilla JS
• Tabulator (interactive data grid)

Installation

Docker (Recommended)

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.

Manual Installation

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

3. Run the development server:

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

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" to add a new row
• Update: Select a row and edit cells directly in the grid, then click "Save row"
• Delete: Select one or more rows and click "Delete", then confirm

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.

Security Considerations

The application uses session-based authentication with credentials stored in PHP sessions. It leverages MariaDB's own permission system for access control, ensuring that users can only see and edit what their credentials allow.

The application includes robust error handling and logging capabilities, particularly for data operations and CSV import/export functions.

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.