feat: Add PostgreSQL support and configuration setup for PunimTag

This commit introduces PostgreSQL as the default database for the PunimTag application, along with a new `.env.example` file for configuration. A setup script for PostgreSQL has been added to automate the installation and database creation process. The README has been updated to reflect these changes, including instructions for setting up PostgreSQL and using the `.env` file for configuration. Additionally, the database session management has been enhanced to support PostgreSQL connection pooling. Documentation has been updated accordingly.

README.md

@@ -55,11 +55,38 @@ cd ..
 
 ### Database Setup
 
+**PostgreSQL (Default - Network Database):**
+The application is configured to use PostgreSQL by default. The database connection is configured via the `.env` file.
+
+**Install PostgreSQL (if not installed):**
+```bash
+# On Ubuntu/Debian:
+sudo apt update && sudo apt install -y postgresql postgresql-contrib
+sudo systemctl start postgresql
+sudo systemctl enable postgresql
+
+# Or use the automated setup script:
+./scripts/setup_postgresql.sh
+```
+
+**Create Database and User:**
+```bash
+sudo -u postgres psql -c "CREATE USER punimtag WITH PASSWORD 'punimtag_password';"
+sudo -u postgres psql -c "CREATE DATABASE punimtag OWNER punimtag;"
+sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE punimtag TO punimtag;"
+```
+
+**Configuration:**
+The `.env` file contains the database connection string:
+```bash
+DATABASE_URL=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag
+```
+
 **Automatic Initialization:**
 The database and all tables are automatically created on first startup. No manual migration is needed!
 
 The web application will:
-- Create the database file at `data/punimtag.db` (SQLite default) if it doesn't exist
+- Connect to PostgreSQL using the `.env` configuration
 - Create all required tables with the correct schema on startup
 - Match the desktop version schema exactly for compatibility
 
@@ -72,10 +99,10 @@ export PYTHONPATH=/home/ladmin/Code/punimtag
 python scripts/recreate_tables_web.py
 ```
 
-**PostgreSQL (Production):**
-Set the `DATABASE_URL` environment variable:
+**SQLite (Alternative - Local Database):**
+To use SQLite instead of PostgreSQL, comment out or remove the `DATABASE_URL` line in `.env`, or set it to:
 ```bash
-export DATABASE_URL=postgresql+psycopg2://user:password@host:port/database
+DATABASE_URL=sqlite:///data/punimtag.db
 ```
 
 **Database Schema:**
@@ -90,7 +117,8 @@ The web version uses the **exact same schema** as the desktop version for full c
 ### Running the Application
 
 **Prerequisites:**
-- Redis must be installed and running (for background jobs)
+- **PostgreSQL** must be installed and running (see Database Setup section above)
+- **Redis** must be installed and running (for background jobs)
   
   **Install Redis (if not installed):**
   ```bash
@@ -375,25 +403,29 @@ punimtag/
 
 ### Database
 
-**SQLite (Default for Development):**
+**PostgreSQL (Default - Network Database):**
+The application uses PostgreSQL by default, configured via the `.env` file:
 ```bash
-# Default location: data/punimtag.db
-# No configuration needed
+DATABASE_URL=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag
 ```
 
-**PostgreSQL (Production):**
+**SQLite (Alternative - Local Database):**
+To use SQLite instead, comment out or remove the `DATABASE_URL` line in `.env`, or set:
 ```bash
-export DATABASE_URL=postgresql+psycopg2://user:password@host:port/database
+DATABASE_URL=sqlite:///data/punimtag.db
 ```
 
 ### Environment Variables
 
+Configuration is managed via the `.env` file in the project root. A `.env.example` template is provided.
+
+**Required Configuration:**
 ```bash
-# Database (optional, defaults to SQLite)
-DATABASE_URL=sqlite:///data/punimtag.db
+# Database (PostgreSQL by default)
+DATABASE_URL=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag
 
 # JWT Secrets (change in production!)
-SECRET_KEY=your-secret-key-here
+SECRET_KEY=dev-secret-key-change-in-production
 
 # Single-user credentials (change in production!)
 ADMIN_USERNAME=admin
@@ -403,6 +435,8 @@ ADMIN_PASSWORD=admin
 PHOTO_STORAGE_DIR=data/uploads
 ```
 
+**Note:** The `.env` file is automatically loaded by the application using `python-dotenv`. Environment variables can also be set directly in your shell if preferred.
+
 ---
 
 
@@ -420,9 +454,9 @@ PHOTO_STORAGE_DIR=data/uploads
 
 **Backend:**
 - **Framework**: FastAPI (Python 3.12+)
-- **Database**: SQLite (dev), PostgreSQL (production)
+- **Database**: PostgreSQL (default, network), SQLite (optional, local)
 - **ORM**: SQLAlchemy 2.0
-- **Migrations**: Alembic
+- **Configuration**: Environment variables via `.env` file (python-dotenv)
 - **Jobs**: Redis + RQ
 - **Auth**: JWT (python-jose)