docs(database): add wizard and migration tool documentation

Update DatabaseConfiguration.md with sections for the new Database
Configuration Wizard and Database Migration Tool. Also update API.md
with the new /api/database/ endpoint documentation.

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>

docs/API.md

@@ -1094,6 +1094,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).

docs/DatabaseConfiguration.md

@@ -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**.
+
+### 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 |