Enhance XLS upload functionality and update requirements. Added Flask, Flask-SQLAlchemy, and Alembic to requirements. Modified database schema in upload_xls.py for improved data handling and added SQLAlchemy configuration in config.py.

2025-06-09 15:34:18 +01:00
parent f478a52a2f
commit c00bb71d2a
14 changed files with 427 additions and 33 deletions
@@ -0,0 +1,56 @@
+# Database Migration & Data Upload Guide
+
+This project uses **Flask-Migrate** (powered by Alembic) for managing database schema changes and a custom Flask CLI command for uploading XLS data.
+
+## Migration Workflow
+
+Follow these steps to manage database schema and upload data:
+
+1.  **Set Flask App Environment Variable:**
+    Open your terminal in the project root (`digifi-Analytics/`) and set the `FLASK_APP` variable:
+
+    ```bash
+    # For Windows
+    set FLASK_APP=run.py
+
+    # For macOS/Linux
+    export FLASK_APP=run.py
+    ```
+
+2.  **Initialize Migration Repository (First-time setup only):**
+    This command sets up the `migrations/` directory structure. You've likely already run this, so you might get a "Directory already exists" message, which is fine.
+
+    ```bash
+    flask --app run.py db init
+    ```
+
+3.  **Generate a New Migration Script:**
+    After making changes to `salary_analytics/app/models.py` (e.g., adding a new table or column), use this command to create a migration file. This file will contain the `upgrade()` and `downgrade()` logic.
+
+    ```bash
+    flask --app run.py db migrate -m "Descriptive message for your changes"
+    ```
+
+4.  **Review the Generated Migration:**
+    Open the newly created `.py` file in `migrations/versions/` (e.g., `XXXXXXXXXXXX_your_message.py`) and review the `upgrade()` and `downgrade()` functions. Ensure they accurately reflect your intended schema changes.
+
+5.  **Apply Migrations to the Database:**
+    This command executes the pending migration scripts, updating your database schema. **Always apply migrations after generating them.**
+
+    ```bash
+    flask --app run.py db upgrade
+    ```
+
+## Uploading XLS Data
+
+Once your `analytics_raw_transactions` table is created via migration, you can upload your XLS files using the custom command:
+
+```bash
+flask --app run.py upload-xls <path_to_your_xls_file>
+```
+
+**Example:**
+
+```bash
+flask --app run.py upload-xls data/transactions.xls
+```