From 155b1ba9d0fe78c0eaeec55741e46b5817bbe351 Mon Sep 17 00:00:00 2001 From: Michael Chus Date: Sat, 31 Jan 2026 00:33:25 +0300 Subject: [PATCH] Update documentation files (README.md and claude.md) based on codebase analysis --- README.md | 28 +++++++++-- claude.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 170 insertions(+), 5 deletions(-) create mode 100644 claude.md diff --git a/README.md b/README.md index 2dd70bc..38ddf68 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,9 @@ Open http://localhost:8080 in your browser. - Edit existing rows. - Delete rows. - Generic, schema-agnostic behavior using `information_schema`. +- CSV import/export functionality. +- Database backup using mysqldump. +- Foreign key relationship support. --- @@ -75,6 +78,7 @@ project/ 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 ``` --- @@ -136,7 +140,7 @@ No database name is hardcoded: the app reads available schemas from `information ## Running the App (Development) -Use PHP’s built-in web server and point it to the `public` directory: +Use PHP's built-in web server and point it to the `public` directory: ```bash cd /path/to/mariadb-grid @@ -163,7 +167,7 @@ http://localhost:8080/ 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. + - The central Tabulator grid will load the table's data. - Column header filters allow you to filter per column. - Pagination is handled server-side. @@ -181,15 +185,24 @@ http://localhost:8080/ - Click **“Delete”**. - Confirm the deletion. -> Updates and deletes are performed using the table’s primary key. +> 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. +- 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. @@ -223,4 +236,9 @@ http://localhost:8080/ - 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`. \ No newline at end of file + - 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 \ No newline at end of file diff --git a/claude.md b/claude.md new file mode 100644 index 0000000..5d6ea2d --- /dev/null +++ b/claude.md @@ -0,0 +1,147 @@ +# 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) + +```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. + +### Manual Installation + +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 +``` + +3. Run the development server: +```bash +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. \ No newline at end of file