Merge pull request #482 from christianlouis/copilot/add-database-configuration-wizard

feat(database): integrate wizard into settings page, improve accessibility and test coverage
2026-03-06 11:28:44 +01:00
parent aad62958fb 7dae15fd29
commit 26b4d04d76
15 changed files with 2647 additions and 2 deletions
@@ -1238,6 +1238,125 @@ Send a test notification through all configured notification channels.
 The API implements rate limiting to ensure system stability. If you exceed the limits, you'll receive a `429 Too Many Requests` response.


+## Database Configuration Wizard
+
+Endpoints for building and testing database connection strings and migrating data between databases.  All write endpoints require admin authentication.
+
+### GET /api/database/backends
+
+List supported database backends with metadata.
+
+**Response (200):**
+```json
+[
+  {
+    "id": "sqlite",
+    "label": "SQLite (Development)",
+    "default_port": null,
+    "description": "File-based database. Best for development and single-user setups.",
+    "requires_host": false
+  },
+  {
+    "id": "postgresql",
+    "label": "PostgreSQL (Recommended for Production)",
+    "default_port": 5432,
+    "description": "Robust, full-featured database. Recommended for production.",
+    "requires_host": true
+  }
+]
+```
+
+### POST /api/database/build-url
+
+Build a SQLAlchemy connection string from individual components.
+
+**Request:**
+```json
+{
+  "backend": "postgresql",
+  "host": "my-db.rds.amazonaws.com",
+  "port": 5432,
+  "database": "docuelevate",
+  "username": "admin",
+  "password": "secret",
+  "ssl_mode": "require"
+}
+```
+
+**Response (200):**
+```json
+{
+  "url": "postgresql://admin:secret@my-db.rds.amazonaws.com:5432/docuelevate?sslmode=require"
+}
+```
+
+### POST /api/database/test-connection
+
+Test connectivity to a database.
+
+**Request:**
+```json
+{
+  "url": "postgresql://admin:secret@my-db.rds.amazonaws.com:5432/docuelevate?sslmode=require"
+}
+```
+
+**Response (200):**
+```json
+{
+  "success": true,
+  "message": "Connection successful",
+  "backend": "postgresql",
+  "server_version": "PostgreSQL 16.2 on x86_64-pc-linux-gnu"
+}
+```
+
+### POST /api/database/preview-migration
+
+Preview a data migration (table-by-table row counts) without copying data.
+
+**Request:**
+```json
+{
+  "url": "sqlite:///./app/database.db"
+}
+```
+
+**Response (200):**
+```json
+{
+  "success": true,
+  "tables": [
+    {"name": "documents", "row_count": 42},
+    {"name": "files", "row_count": 150}
+  ],
+  "total_rows": 192
+}
+```
+
+### POST /api/database/migrate
+
+Execute a full data migration from source to target database.
+
+**Request:**
+```json
+{
+  "source_url": "sqlite:///./app/database.db",
+  "target_url": "postgresql://admin:secret@host:5432/docuelevate"
+}
+```
+
+**Response (200):**
+```json
+{
+  "success": true,
+  "tables_copied": 8,
+  "rows_copied": 192,
+  "errors": []
+}
+```
+
+
 ## Further Assistance

 For additional help with the API, please contact our support team or refer to the [Development Guide](../CONTRIBUTING.md).
@@ -10,7 +10,7 @@ Configuration is primarily done through environment variables specified in a `.e

 | **Variable**           | **Description**                                          | **Example**                    |
 |------------------------|----------------------------------------------------------|--------------------------------|
-| `DATABASE_URL`         | Path/URL to the SQLite database (or other SQL backend). | `sqlite:///./app/database.db`  |
+| `DATABASE_URL`         | Path/URL to the SQLite database (or other SQL backend). Use the [Database Wizard](/database-wizard) for guided setup. See [Database Configuration](DatabaseConfiguration.md). | `sqlite:///./app/database.db`  |
 | `REDIS_URL`            | URL for Redis, used by Celery for broker & result store. | `redis://redis:6379/0`         |
 | `WORKDIR`              | Working directory for the application.                  | `/workdir`                     |
 | `GOTENBERG_URL`        | Gotenberg PDF processing URL.                           | `http://gotenberg:3000`        |
@@ -4,6 +4,8 @@ DocuElevate uses [SQLAlchemy](https://www.sqlalchemy.org/) as its ORM and [Alemb

 ## Table of Contents

+- [Database Configuration Wizard](#database-configuration-wizard)
+- [Database Migration Tool](#database-migration-tool)
 - [Supported Databases](#supported-databases)
 - [Configuration](#configuration)
 - [SQLite (Development)](#sqlite-development)
@@ -17,6 +19,74 @@ DocuElevate uses [SQLAlchemy](https://www.sqlalchemy.org/) as its ORM and [Alemb

 ---

+## Database Configuration Wizard
+
+DocuElevate includes a guided **Database Configuration Wizard** accessible at `/database-wizard`.  The wizard walks you through building a connection string step by step — no need to remember the exact URL format.
+
+### How to Access
+
+Navigate to **`/database-wizard`** in your browser, or find the link under **Admin → Settings**.  On the Settings page, click the **DB Wizard** button in the toolbar, or look for the **Open Database Wizard** link next to the `database_url` setting.
+
+### Wizard Steps
+
+1. **Choose Database Type** — select SQLite, PostgreSQL, or MySQL/MariaDB.
+2. **Connection Details** — enter host, port, database name, credentials, and SSL mode (auto-populated with sensible defaults).
+3. **Test & Apply** — test the connection before committing, then copy the generated `DATABASE_URL` into your `.env` file.
+
+The wizard generates the full SQLAlchemy connection string and lets you test connectivity directly from the UI.  After testing, copy the `DATABASE_URL=…` line into your `.env` file (or Docker Compose environment) and restart DocuElevate.
+
+### REST API
+
+The wizard is backed by a REST API under `/api/database/`:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/database/backends` | GET | List supported database backends |
+| `/api/database/build-url` | POST | Build a connection string from components |
+| `/api/database/parse-url` | POST | Parse a connection string into components |
+| `/api/database/validate-url` | POST | Validate URL format without connecting |
+| `/api/database/test-connection` | POST | Test connectivity to a database |
+
+> **Note:** All write endpoints require admin authentication.
+
+---
+
+## Database Migration Tool
+
+The **Migrate Data** tab (on the same `/database-wizard` page) lets you copy all your data from one database to another — for example, migrating from the built-in SQLite database to an external PostgreSQL or MySQL instance.
+
+### When to Use
+
+- Moving from a development SQLite database to a production PostgreSQL instance.
+- Migrating to a managed cloud database (AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL, Supabase, etc.).
+- Consolidating data from one database engine to another.
+
+### How It Works
+
+1. Enter (or auto-fill) the **Source Database URL** — this is your current database.
+2. Enter the **Target Database URL** — the new, empty database to copy data into.
+3. Click **Test Source** and **Test Target** to verify both connections.
+4. Click **Preview Migration** to see a table-by-table row count.
+5. Confirm and click **Start Migration** to copy all data.
+
+The migration tool:
+- Creates the full schema in the target database from the application models.
+- Copies all rows table by table in dependency order (parent tables first).
+- Stamps the Alembic migration version to `head` in the target.
+
+After migration, update your `DATABASE_URL` environment variable to point at the new database and restart DocuElevate.
+
+### REST API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/database/preview-migration` | POST | Preview tables and row counts |
+| `/api/database/migrate` | POST | Execute the full data migration |
+
+> **Warning:** Always run the migration against an **empty** target database.  The tool does not delete existing data in the target before copying.
+
+---
+
 ## Supported Databases

 | Database | Recommended Use | Notes |