Update documentation files (README.md and claude.md) based on codebase analysis

2026-01-31 00:33:25 +03:00
parent 73c63b5d86
commit 155b1ba9d0
2 changed files with 170 additions and 5 deletions
--- 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`.
+  - 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
--- a/claude.md
+++ 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.