supabase-scheduler/CLAUDE.md

Supabase Scheduler - Documentazione Progetto

Panoramica

Supabase Scheduler è una web app per gestire ed eseguire automaticamente query verso database Supabase multipli. Permette di configurare più istanze Supabase, ciascuna con la propria query e frequenza di esecuzione, e le esegue in background 24/7.

---

Accesso

URL Live

• Applicazione: https://lab.mlhub.it/supabase-scheduler/
• Repository Git: https://git.mlhub.it/Michele/supabase-scheduler

Credenziali Login (fisse, non modificabili)

• Username: testlab
• Password: magarifunzione4

Le credenziali sono hardcoded nel file server.js (righe 12-13).

---

Cosa Fa

Funzionalità Principali

1. Gestione Multi-Database

   • Aggiungere configurazioni per diversi progetti Supabase
   • Ogni database ha: nome, URL, anon key, query, frequenza
   • CRUD completo (Create, Read, Update, Delete)

2. Scheduler Automatico

   • Esegue query automaticamente secondo la frequenza impostata
   • Gira 24/7 sul server (anche senza utenti connessi)
   • Controllo ogni minuto per verificare quali query eseguire

3. Log Esecuzioni

   • Registra ogni esecuzione con timestamp, status, durata
   • Memorizza errori per debugging
   • Ultimi 50 log per database visibili da UI

4. Esecuzione Manuale

   • Pulsante "Esegui Ora" per testare query on-demand

Formato Query Supabase

Il campo "Query" accetta endpoint REST Supabase:

# Esempi validi:
users?select=*                          # Tutti gli utenti
products?select=id,name&active=eq.true  # Prodotti filtrati
orders?select=*&limit=10                # Ultimi 10 ordini
rpc/my_function                         # Chiama RPC function
rpc/cleanup_old_data                    # Function di manutenzione

La query viene eseguita come GET request verso: {SUPABASE_URL}/rest/v1/{QUERY}

---

Stack Tecnologico

Componente	Tecnologia
Backend	Node.js + Express
Database	SQLite (better-sqlite3)
Scheduler	node-cron
Frontend	HTML/CSS/JS vanilla
Container	Docker (node:18-alpine)

---

Struttura File

supabase-scheduler/
├── server.js           # Backend Express + scheduler + API
├── package.json        # Dipendenze Node.js
├── docker-compose.yml  # Configurazione container
├── deploy.sh           # Script auto-deploy (solo su VPS)
├── public/
│   └── index.html      # Frontend SPA completo
├── data/
│   ├── .gitkeep        # Mantiene directory in Git
│   └── scheduler.db    # Database SQLite (gitignored, creato a runtime)
├── .env.example        # Template variabili ambiente
├── .gitignore
├── .gitattributes
├── README.md           # Documentazione utente
└── CLAUDE.md           # Questo file - documentazione tecnica

---

Database SQLite

Tabella databases

Configurazioni dei database Supabase.

Campo	Tipo	Descrizione
id	INTEGER	Primary key
name	TEXT	Nome identificativo
supabase_url	TEXT	URL progetto (https://xxx.supabase.co)
anon_key	TEXT	Chiave anon/public
query	TEXT	Endpoint REST da chiamare
frequency_minutes	INTEGER	Intervallo esecuzione (default 5)
is_active	INTEGER	0/1 toggle attivazione
last_run	TEXT	Timestamp ultima esecuzione
last_status	TEXT	'success' o 'error'
last_error	TEXT	Messaggio errore (se presente)
created_at	TEXT	Timestamp creazione
updated_at	TEXT	Timestamp ultima modifica

Tabella execution_logs

Log di tutte le esecuzioni.

Campo	Tipo	Descrizione
id	INTEGER	Primary key
database_id	INTEGER	FK a databases.id
executed_at	TEXT	Timestamp esecuzione
status	TEXT	'success' o 'error'
response	TEXT	Risposta JSON (troncata a 5000 char)
error	TEXT	Messaggio errore
duration_ms	INTEGER	Durata in millisecondi

---

API Endpoints

Autenticazione

• POST /api/login - Login con username/password
• POST /api/logout - Logout (distrugge sessione)
• GET /api/auth/status - Verifica stato autenticazione

Database CRUD (richiede auth)

• GET /api/databases - Lista tutti i database
• GET /api/databases/:id - Dettaglio singolo database
• POST /api/databases - Crea nuovo database
• PUT /api/databases/:id - Modifica database
• DELETE /api/databases/:id - Elimina database

Esecuzione e Log (richiede auth)

• POST /api/databases/:id/execute - Esegui query manualmente
• GET /api/databases/:id/logs - Ultimi 50 log esecuzione

Utility

• GET /api/health - Health check
• GET /api/scheduler/status - Stato scheduler

---

Configurazione VPS

Directory

/opt/lab-supabase-scheduler/

Container Docker

• Nome: lab-supabase-scheduler-app
• Immagine: node:18-alpine
• Porta interna: 3000
• Rete: proxy_net
• Limiti: 300M RAM, 0.25 CPU

Nginx Routing

File: /opt/lab-router/projects/supabase-scheduler.conf

location /supabase-scheduler/ {
    proxy_pass http://lab-supabase-scheduler-app:3000/;
    ...
}

---

Workflow Aggiornamenti

Modifiche al codice

# 1. Modifica file localmente
# 2. Commit e push
cd "D:\Michele\Progetti\Claude\VPS echosystem\lab\supabase-scheduler"
git add .
git commit -m "Descrizione modifica"
git push origin main

# 3. Deploy su VPS
ssh mic@72.62.49.98 "cd /opt/lab-supabase-scheduler && ./deploy.sh"

Comandi utili VPS

# Log container
ssh mic@72.62.49.98 "docker logs -f lab-supabase-scheduler-app"

# Restart container
ssh mic@72.62.49.98 "cd /opt/lab-supabase-scheduler && docker compose restart"

# Accesso shell container
ssh mic@72.62.49.98 "docker exec -it lab-supabase-scheduler-app sh"

---

Note Tecniche

Session Warning

All'avvio appare warning:

Warning: connect.session() MemoryStore is not designed for production

Per un'app lab è accettabile. In production usare Redis o database session store.

Scheduler Logic

• Il cron gira ogni minuto (* * * * *)
• Per ogni database attivo, verifica se è passato frequency_minutes dall'ultima esecuzione
• Se sì, esegue la query e aggiorna last_run, last_status, last_error

Sicurezza

• Le anon_key Supabase sono salvate in chiaro nel database SQLite
• Per uso production, considerare encryption at rest
• La sessione usa cookie HTTP-only ma non secure (lab environment)

---

Cronologia Progetto

• Creato: 2026-01-24
• Autore: Claude Opus 4.5 + Michele
• Scopo: Gestione automatica query periodiche verso database Supabase multipli
• Richiesta originale: App con login fisso, dashboard per configurare database Supabase, scheduler che esegue query automaticamente 24/7