final initial database fixes - IT WORKS

README.md

@@ -135,3 +135,97 @@ Add these credentials to your .env file at the project root:
 plaintext
 GITHUB_CLIENT_ID="your-github-client-id"
 GITHUB_CLIENT_SECRET="your-github-client-secret"
+
+## connect to postgres on projectium.com
+
+psql -h localhost -U flyer_crawler_user -d "flyer-crawler-prod" -W
+
+
+## postgis
+
+flyer-crawler-prod=> SELECT version();
+                                                                 version
+------------------------------------------------------------------------------------------------------------------------------------------
+ PostgreSQL 14.19 (Ubuntu 14.19-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.2) 11.4.0, 64-bit
+(1 row)
+
+flyer-crawler-prod=> SELECT PostGIS_Full_Version();
+                                                                        postgis_full_version
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ POSTGIS="3.2.0 c3e3cc0" [EXTENSION] PGSQL="140" GEOS="3.10.2-CAPI-1.16.0" PROJ="8.2.1" LIBXML="2.9.12" LIBJSON="0.15" LIBPROTOBUF="1.3.3" WAGYU="0.5.0 (Internal)"
+(1 row)
+
+
+## production postgres setup
+
+Part 1: Production Database Setup
+This database will be the live, persistent storage for your application.
+
+Step 1: Install PostgreSQL (if not already installed)
+First, ensure PostgreSQL is installed on your server.
+
+bash
+sudo apt update
+sudo apt install postgresql postgresql-contrib
+Step 2: Create the Production Database and User
+It's best practice to create a dedicated, non-superuser role for your application to connect with.
+
+Switch to the postgres system user to get superuser access to the database.
+
+bash
+sudo -u postgres psql
+Inside the psql shell, run the following SQL commands. Remember to replace 'a_very_strong_password' with a secure password that you will manage with a secrets tool or in your .env file.
+
+sql
+-- Create a new role (user) for your application
+CREATE ROLE flyer_crawler_user WITH LOGIN PASSWORD 'a_very_strong_password';
+
+-- Create the production database and assign ownership to the new user
+CREATE DATABASE "flyer-crawler-prod" WITH OWNER = flyer_crawler_user;
+
+-- Exit the psql shell
+
+Step 3: Apply the Master Schema
+Now, you'll populate your new database with all the tables, functions, and initial data. Your master_schema_rollup.sql file is perfect for this.
+
+Navigate to your project's root directory on the server.
+
+Run the following command to execute the master schema script against your new production database. You will be prompted for the password you created in the previous step.
+
+bash
+psql -U flyer_crawler_user -d "flyer-crawler-prod" -f sql/master_schema_rollup.sql
+This single command creates all tables, extensions (pg_trgm, postgis), functions, and triggers, and seeds essential data like categories and master items.
+
+Step 4: Seed the Admin Account
+Your application has a separate script to create the initial admin user.
+
+Ensure your .env file on the server is configured with the correct production database credentials (DB_USER, DB_PASSWORD, DB_DATABASE="flyer-crawler-prod", etc.).
+
+Run the admin seeding script using tsx.
+
+bash
+npx tsx src/db/seed_admin_account.ts
+Your production database is now ready! Your application can connect to it using the flyer_crawler_user role and the credentials in your .env file.
+
+Part 2: Test Database Setup (for CI/CD)
+Your Gitea workflow (deploy.yml) already automates the creation and teardown of the test database during the pipeline run. The steps below are for understanding what the workflow does and for manual setup if you ever need to run tests outside the CI pipeline.
+
+The process your CI pipeline follows is:
+
+Setup (sql/test_setup.sql):
+
+As the postgres superuser, it runs sql/test_setup.sql.
+This creates a temporary role named test_runner.
+It creates a separate database named "flyer-crawler-test" owned by test_runner.
+Schema Application (src/tests/setup/global-setup.ts):
+
+The test runner (vitest) executes the global-setup.ts file.
+This script connects to the "flyer-crawler-test" database using the temporary credentials.
+It then runs the same sql/master_schema_rollup.sql file, ensuring your test database has the exact same structure as production.
+Test Execution:
+
+Your tests run against this clean, isolated "flyer-crawler-test" database.
+Teardown (sql/test_teardown.sql):
+
+After tests complete (whether they pass or fail), the if: always() step in your workflow ensures that sql/test_teardown.sql is executed.
+This script terminates any lingering connections to the test database, drops the "flyer-crawler-test" database completely, and drops the test_runner role.