Aiuto e documentazione

Introduzione a QueryForge
Cos'è QueryForge?

QueryForge è un ambiente sicuro e controllato progettato per l'apprendimento e la pratica del linguaggio SQL. Permette agli utenti di eseguire query SQL in un ambiente isolato, senza il rischio di danneggiare dati reali o compromettere la sicurezza del sistema.

A chi è rivolto?

Studenti che desiderano imparare e praticare SQL;
Sviluppatori che vogliono testare le loro query prima di eseguirle in produzione;
Insegnanti che necessitano di uno strumento didattico per i loro corsi di database;
Professionisti che desiderano perfezionare le loro competenze SQL.

Caratteristiche principali

• Interfaccia intuitiva per l'esecuzione di query SQL;
• Ambiente sicuro con protezioni contro operazioni pericolose;
• Visualizzazione immediata dei risultati delle query;
• Pannello struttura database integrato;
Tutor AI integrato per utenti Pro;
• Sistema di backup e ripristino per utenti Pro;
• Feedback dettagliato sugli errori e sui risultati.

Guida rapida all'utilizzo
Accesso al sistema

1. Accedi alla piattaforma utilizzando le tue credenziali;
2. Verrai reindirizzato all'interfaccia principale del playground.

Interfaccia utente

L'interfaccia del QueryForge è organizzata in schede responsive:

🖥️ Editor SQL

Area di scrittura: editor con evidenziazione della sintassi
Controlli dimensione font: personalizza la dimensione del testo
Query Comuni: sezione collassabile con template predefiniti
Pulsanti azione:
  - Esegui (Ctrl+Invio): esegue la query corrente
  - Pulisci: cancella il contenuto dell'editor
  - Aggiorna DB: ricarica la struttura del database
  - Tutor IA (Pro): chiedi aiuto all'assistente intelligente

🕐 Cronologia

• Visualizza le query eseguite precedentemente
• Possibilità di ricaricare o rieseguire query dalla cronologia
• Filtri e ricerca nelle query salvate

🔗 Relazioni DB (Pro)

• Visualizzazione grafica delle relazioni tra tabelle
• Mappe interattive della struttura del database
• Analisi delle dipendenze tra entità

💾 Backup (Pro)

• Creazione di backup del database
• Ripristino da backup precedenti
• Gestione delle versioni del database

Pannello Struttura Database

Visualizzazione live: mostra tabelle, colonne e tipi di dati
Indicatori chiavi: evidenzia le chiavi primarie (🔑)
Quick Actions: click sulle tabelle per generare query SELECT
Pulsante Refresh: aggiorna la struttura dopo modifiche
Responsive: collassabile su dispositivi mobili

Operazioni di base
Visualizzare la struttura del database

Metodo consigliato: Utilizza il pannello laterale "Database" che mostra automaticamente:

• Tutte le tabelle disponibili
• Colonne con tipi di dati
• Indicatori per chiavi primarie
• Click sulle tabelle per generare query SELECT

Connessione al database
USE nome_database;

Questo comando imposta il database attivo per le query successive.

Comandi di sistema avanzati

Per motivi di sicurezza, alcuni comandi SQL tradizionali sono gestiti tramite l'interfaccia:

SHOW TABLES → Usa il pulsante "Aggiorna DB" o il pannello laterale
DESCRIBE tabella → Visualizzabile nel pannello "Database"
SHOW COLUMNS → Informazioni visibili nel pannello laterale

Esecuzione di una query

1. Scrivi la tua query nell'editor;
2. Usa Ctrl + Invio oppure clicca "Esegui";
3. I risultati appariranno nell'area sottostante con possibilità di esportazione.

Limitazioni di sicurezza

Per garantire un ambiente sicuro, QueryForge implementa diverse restrizioni:

Comandi di sistema sostituiti da interfaccia

I seguenti comandi sono gestiti tramite l'interfaccia per maggiore sicurezza:

SHOW TABLES: sostituito dal pannello "Database" e pulsante "Aggiorna DB"
SHOW DATABASES: informazioni disponibili nel pannello laterale
DESCRIBE table_name: dettagli visibili nel pannello "Database"
SHOW COLUMNS FROM table_name: colonne mostrate nel pannello laterale

Funzioni bloccate

Le seguenti funzioni MySQL sono bloccate per motivi di sicurezza:

LOAD_FILE(): previene la lettura di file dal sistema;
SLEEP(), BENCHMARK(): evita attacchi di tipo Denial of Service;
• Altre funzioni potenzialmente pericolose per l'accesso al file system.

Comandi ad alto privilegio

I seguenti comandi amministrativi sono disabilitati:

SHOW GRANTS: previene la visualizzazione dei privilegi;
GRANT, REVOKE: previene modifiche ai privilegi;
• Comandi amministrativi come CREATE USER, DROP USER

Protezioni contro SQL Injection

• Sistema di rilevamento e blocco per pattern di iniezione SQL comuni;
• Analisi in tempo reale delle query per individuare tentativi di bypass;
Avvisi di sicurezza: notifiche visive quando vengono rilevate operazioni potenzialmente pericolose.

Altre limitazioni di sicurezza

Clausola WHERE consigliata: per prevenire operazioni accidentali su intere tabelle;
Limite nelle clausole LIKE: restrizioni sull'uso di wildcard troppo ampie;
Accesso database limitato: solo il database assegnato all'utente è accessibile;
Rate limiting: limite di query per prevenire abusi;
Sanitizzazione messaggi di errore: gli errori non rivelano dettagli sensibili sulla struttura del database

Esempi pratici
Esplorare la struttura del database

Usa il pannello "Database" a sinistra per visualizzare:

  • • Tutte le tabelle disponibili;
  • • Colonne con tipi di dati;
  • • Chiavi primarie (🔑).

Il pannello laterale ti mostra automaticamente la struttura completa.

Query di selezione base
SELECT * FROM clienti WHERE città = 'Milano';

Seleziona tutti i clienti di Milano.

Join tra tabelle
SELECT o.ordine_id, c.nome, c.cognome FROM ordini o JOIN clienti c ON o.cliente_id = c.cliente_id WHERE o.data_ordine >= '2023-01-01';

Seleziona gli ordini del 2023 con i nomi dei clienti.

Aggregazione dati
SELECT categoria, COUNT(*) as numero_prodotti, AVG(prezzo) as prezzo_medio FROM prodotti GROUP BY categoria HAVING COUNT(*) > 5;

Calcola il numero di prodotti e il prezzo medio per categoria, mostrando solo categorie con più di 5 prodotti.

Subquery
SELECT nome, cognome FROM clienti WHERE cliente_id IN ( SELECT DISTINCT cliente_id FROM ordini WHERE totale > 1000 );

Seleziona i clienti che hanno effettuato ordini superiori a 1000.

Inserimento dati
INSERT INTO prodotti (nome, categoria, prezzo, disponibilità) VALUES ('Prodotto Nuovo', 'Elettronica', 299.99, 100);

Inserisce un nuovo prodotto nella tabella prodotti.

Aggiornamento dati
UPDATE clienti SET email = '[email protected]' WHERE cliente_id = 42;

Aggiorna l'email di un cliente specifico.

Eliminazione dati
DELETE FROM ordini WHERE stato = 'Annullato' AND data_ordine < '2022-01-01' ;

Elimina gli ordini annullati precedenti al 2022.

Utilizzare il Tutor IA (Funzionalità Pro)
  • • Clicca sul pulsante "Tutor IA" nell'editor SQL;
  • • Inserisci la tua domanda o richiesta di aiuto;
  • • Ricevi risposte dettagliate e suggerimenti personalizzati.

Ad esempio, puoi chiedere: "Come posso ottimizzare questa query?" o "Qual è la struttura della tabella ordini?"

Il Tutor IA può analizzare la struttura del tuo database e fornire consigli personalizzati. Assicurati di avere un piano Pro attivo per accedere a questa funzionalità.

Risoluzione problemi
Errori comuni
Errore: "SHOW TABLES non funziona"

Problema: Hai tentato di usare il comando SHOW TABLES direttamente.

Soluzione: Usa il pannello "Database" a sinistra o clicca il pulsante "Aggiorna DB" per visualizzare le tabelle disponibili.

Errore: "DESCRIBE non permesso"

Problema: Hai tentato di usare DESCRIBE per visualizzare la struttura di una tabella.

Soluzione: Tutte le informazioni sulle colonne (nome, tipo, chiavi) sono visibili nel pannello "Database" laterale.

Errore: Query senza clausola WHERE non permessa

Problema: Hai tentato di eseguire un UPDATE o DELETE senza specificare una clausola WHERE.

Soluzione: Per sicurezza, aggiungi sempre una clausola WHERE specifica quando modifichi o elimini dati.

Errore: Funzione non consentita

Problema: Hai utilizzato una funzione MySQL vietata per motivi di sicurezza.

Soluzione: Usa alternative sicure o contatta l'amministratore se hai bisogno di funzionalità specifiche.

Errore: Limite di query raggiunto

Problema: Hai superato il limite di query per il tuo piano.

Soluzione: Attendi il reset del limite o considera l'upgrade a un piano Pro per limiti più elevati.

Il pannello Database non si aggiorna

Problema: Dopo aver modificato la struttura, il pannello laterale non mostra i cambiamenti.

Soluzione: Clicca l'icona di refresh (🔄) nel pannello Database o usa il pulsante "Aggiorna DB" nell'editor.

Funzionalità Pro non disponibili
Pulsanti Pro disabilitati

Problema: I pulsanti "Tutor IA", "Relazioni DB" e "Backup" sono grigi.

Soluzione: Queste sono funzionalità Premium. Visita la sezione "Abbonamenti" per sbloccarle.

Best practices

1. Usa il pannello Database come riferimento:
• Mantieni sempre aperto il pannello laterale per consultare la struttura;
• Clicca sulle tabelle per generare automaticamente query SELECT di base.

2. Esegui sempre query mirate:
• Specifica sempre le colonne necessarie invece di usare SELECT *;
• Usa clausole WHERE ben definite.

3. Verifica prima le query complesse:
• Per operazioni che modificano molti dati, esegui prima un SELECT con le stesse condizioni;
• Controlla il numero di righe che verranno modificate.

4. Utilizza le scorciatoie da tastiera:
Ctrl + Invio: esecuzione rapida delle query;
• Ridimensiona il font dell'editor per una migliore leggibilità.

5. Sfrutta il Tutor IA (Pro):
• Chiedi spiegazioni per errori complessi;
• Ottieni suggerimenti per migliorare le tue query;

Come ottenere assistenza

Se riscontri problemi non descritti in questa documentazione:

1. Verifica che la tua query rispetti le limitazioni di sicurezza;
2. Usa il pannello Database invece dei comandi SHOW/DESCRIBE;
3. Se hai un piano Pro, usa il Tutor IA per assistenza personalizzata;
4. Contatta il supporto per problemi tecnici specifici.