Cum funcționează site-ul?

Pe scurt

SQL Playground este un site pe care înveți Oracle SQL direct în browser: citești o lecție scurtă, rulezi interogări reale pe baza de date a unui liceu și rezolvi exerciții verificate automat.

Ideea principală: nu există server de baze de date. Motorul SQL (SQLite, compilat în WebAssembly) rulează chiar în browserul vizitatorului, iar baza de date este creată în memoria calculatorului la fiecare deschidere a paginii. Fiecare vizitator are propria copie, așa că poate șterge sau modifica orice fără să strice nimic altcuiva.

• 9 lecții de Oracle SQL
• 5 tabele cu date despre un liceu
• 0 servere de baze de date

Tehnologii folosite

• HTML structura paginilor
• CSS culori, fonturi, așezare
• JavaScript logica site-ului (module ES)
• sql.js SQLite compilat în WebAssembly
• GitHub păstrează codul și istoricul
• Cloudflare Pages publică site-ul

Nu am folosit framework-uri, npm sau un pas de „build”: fișierele scrise de mine sunt exact fișierele pe care le primește browserul. Singura bibliotecă externă este sql.js, copiată în folderul vendor/, deci site-ul merge și fără internet după ce a fost încărcat.

Structura fișierelor

Tot ce se publică se află în folderul site/. Fiecare fișier are o singură responsabilitate:

Drumul unei interogări

1. Când se deschide pagina

1. index.html Încarcă vendor/sql-wasm.js și js/main.js Primul fișier aduce funcția initSqlJs, al doilea pornește logica paginii.
2. js/main.js start() Cere crearea bazei de date, apoi o testează cu SELECT 1 FROM DUAL și aprinde punctul verde.
3. js/db.js createDatabase() Încarcă motorul (sql-wasm.wasm) și descarcă textul din data/seed.sql cu fetch (cu cache: 'no-cache', ca o modificare a datelor să apară după F5).
4. js/db.js buildDatabase() Creează o bază de date goală în memorie, pornește regulile Oracle (PRAGMA), adaugă tabelul DUAL (addOracleDual()), funcțiile Oracle (addOracleFunctions()) și rulează tot seed.sql.
5. js/main.js showSchema() Cere lista tabelelor cu getSchema() și completează panoul „Structura bazei de date”.
6. js/main.js + js/lessons-ui.js startLessons(tryInEditor) Înapoi în start(): butoanele „Rulează” și „Resetează” sunt pornite (până acum erau dezactivate), apoi startLessons() afișează lecțiile din lessons.js și redeschide ultima lecție deschisă (ținută minte în localStorage).

2. Când apeși „Rulează”

1. index.html Editorul (<textarea id="sql-editor">) Scrii SQL și apeși butonul „Rulează” sau Ctrl+Enter (tastele sunt prinse de handleEditorKeys()).
2. js/main.js runEditorQuery() Citește textul din editor și apelează runQuery(sql) într-un bloc try/catch, ca pagina să nu se strice la o greșeală.
3. js/db.js runQuery(sql) Trece SQL-ul prin prepareOracleSql(sql), ține minte câte rânduri fuseseră modificate până atunci (pentru countChangedRows()) și îl rulează cu db.exec().
4. js/db.js prepareOracleSql(sql) Adaptează SQL-ul Oracle: SYSDATE devine SYSDATE() și COMMIT este scos, iar ROLLBACK și LIMIT opresc comanda cu o eroare în română. Textele dintre apostrofuri sau ghilimele și comentariile nu sunt atinse.
5. vendor/sql-wasm.wasm sql.js / SQLite (WebAssembly) Motorul execută SQL-ul pe baza de date din memorie. Când întâlnește NVL, TO_CHAR etc., apelează funcțiile JavaScript din db.js.
6. rezultatul [{ columns, values }] O listă cu câte un obiect pentru fiecare SELECT, de exemplu: [{ columns: ['nume', 'prenume', 'oras'], values: [['Popa', 'Andrei', 'Brașov'], ...] }]
7. js/main.js Alege ce se afișează
   • Are rânduri: renderResults()
   • Fără rânduri: showResultWithoutRows() scrie „Interogarea nu a returnat niciun rând” sau, pentru INSERT/UPDATE/DELETE, „N rânduri afectate” (countChangedRows() adună rândurile tuturor comenzilor din text)
   • Eroare: renderMessage(..., 'error') scrie „Eroare SQL: ...” în roșu; translateError() traduce întâi mesajul SQLite în română (de exemplu no such table: elev devine „Tabelul elev nu există...”)
8. js/render.js renderResults(container, results) Construiește tabelul cu createResultTable(), createHeaderRow(), createBodyRows() și createCell(). Valorile NULL apar gri. Se desenează cel mult 500 de rânduri (MAX_ROWS), ca pagina să nu se blocheze; pentru mai multe apare „Se afișează primele 500 din N rânduri.”
9. pagina Tabelul cu rezultate + „N rânduri” Apoi showSchema() reîmprospătează panoul cu tabele (poate ai creat sau șters un tabel).

Butoanele „Încearcă în editor” din lecții folosesc același drum: tryInEditor(sql) din main.js scrie exemplul în editor, apelează runEditorQuery() și derulează pagina până la editor.

Securitate: rezultatele sunt puse în pagină doar cu document.createElement și textContent, niciodată ca text HTML. Astfel, chiar dacă cineva scrie cod HTML într-o interogare, el apare ca text și nu se execută. La fel și lecțiile: appendTextWithCode() din lessons-ui.js transformă textul dintre semnele ` în elemente <code>, tot cu textContent.

Butonul „Resetează baza de date”: resetAll() din main.js apelează resetDatabase() din db.js, care închide baza veche și construiește una nouă tot cu buildDatabase().

Baza de date

Baza de date descrie un liceu. Este scrisă în data/seed.sql în stil Oracle: tipuri VARCHAR2, NUMBER, DATE și constrângeri cu nume (de exemplu pk_elevi, fk_note_elev).

PK cheie primară FK cheie străină (arată spre alt tabel)

Legăturile dintre tabele

Rânduri „speciale”, puse intenționat

• Elevii 8, 23 și 37 nu au nicio notă: apar doar cu LEFT JOIN, nu cu JOIN simplu.
• 6 elevi și profesorul 15 au email NULL: pentru exerciții cu IS NULL și NVL.
• Profesorii 1, 2 și 3 sunt șefi de catedră, deci au id_sef NULL: pentru self-join.
• Clasa 12B nu are diriginte, iar materia 12 nu are profesor și nici note: pentru LEFT JOIN și IS NULL.

Cum face site-ul să semene cu Oracle

Oracle adevărat nu poate rula într-un browser, așa că motorul este SQLite. Diferențele cele mai importante sunt acoperite în db.js, în funcția buildDatabase():

• Tabelul DUAL: addOracleDual() creează tabelul dual cu un singur rând ('X'), ca SELECT 2 + 3 FROM DUAL să funcționeze.
• Funcții Oracle scrise în JavaScript: addOracleFunctions() le adaugă în SQLite cu create_function. Funcțiile cu un argument opțional (de exemplu TO_CHAR(valoare [, format])) trec prin addFunctionWithOptionalArgument().
• SYSDATE, COMMIT, ROLLBACK, LIMIT: prepareOracleSql() rescrie SQL-ul înainte de rulare: SYSDATE devine SYSDATE(), COMMIT este scos (aici fiecare modificare se salvează imediat), iar ROLLBACK (nu are ce anula) și LIMIT (nu există în Oracle) dau o eroare în română.
• PRAGMA case_sensitive_like = ON: LIKE 'a%' nu mai găsește „Ana”, exact ca în Oracle (SQLite ignoră implicit literele mari).
• PRAGMA foreign_keys = ON: cheile străine sunt verificate (SQLite nu le verifică implicit), deci nu poți pune o notă unui elev care nu există.
• UPPER și LOWER sunt înlocuite, pentru că varianta din SQLite nu schimbă literele ă, î, â, ș, ț.
• SUBSTR este înlocuit, ca să lucreze ca în Oracle: poziția 0 înseamnă 1 (SUBSTR('Ana', 0, 1) dă 'A'), iar o poziție negativă numără de la sfârșit (SUBSTR('Popescu', -3) dă 'scu').
• Erori în română: translateError() din render.js traduce cele mai des întâlnite erori SQLite cu o listă de tipare (ERROR_TRANSLATIONS): tabel, coloană sau funcție care nu există, sintaxă greșită, comandă incompletă, constrângere încălcată, tabel care există deja, număr greșit de argumente. Un mesaj care nu este în listă apare neschimbat.

Funcțiile adăugate

• NVL
• NVL2
• SYSDATE
• TO_DATE
• TO_CHAR
• INITCAP
• MOD
• TRUNC
• LPAD
• RPAD
• MONTHS_BETWEEN
• ADD_MONTHS
• UPPER
• LOWER
• SUBSTR

Funcțiile pe care SQLite le are deja și care se comportă ca în Oracle nu au fost adăugate, dar pot fi folosite: LENGTH, ROUND, INSTR, REPLACE, TRIM, CONCAT, ABS și funcțiile de grup COUNT, SUM, AVG, MIN, MAX.

Exemplu: funcția NVL din db.js

/**
 * NVL(value, replacement): returns replacement when value is NULL, otherwise value.
 */
function nvl(value, replacement) {
  return value === null ? replacement : value; // NULL arrives in JavaScript as null
}

Când SQLite întâlnește NVL(email, 'fără email'), apelează această funcție JavaScript pentru fiecare rând. Valoarea NULL din SQL ajunge în JavaScript ca null: dacă value este null, funcția întoarce înlocuitorul, altfel întoarce valoarea neschimbată. Legătura dintre numele SQL și funcția JavaScript se face într-o singură linie: database.create_function('NVL', nvl).

Cum sunt verificate exercițiile

Fiecare exercițiu din js/lessons.js are un enunț (statement), soluția corectă (solution), un indiciu (hint), orderMatters (contează ordinea rândurilor?) și, la exercițiile cu INSERT/UPDATE/DELETE/CREATE, o interogare de control (checkQuery). Site-ul nu compară textul SQL, ci rezultatele: o problemă poate fi rezolvată corect în mai multe feluri.

1. js/lessons-ui.js Butonul „Verifică” (sau Ctrl+Enter) checkAnswer() trimite exercițiul și SQL-ul elevului la checkExercise(exercise, userSql).
2. js/checker.js runOnScratchDatabase(userSql, checkQuery) Creează o copie nouă a bazei de date cu createScratchDatabase(), rulează pe ea SQL-ul elevului (trecut prin prepareOracleSql()), apoi închide copia. Baza de date din editor nu este atinsă.
3. js/checker.js runOnScratchDatabase(exercise.solution, checkQuery) La fel pentru soluția corectă, pe o altă copie curată.
4. js/checker.js findDifference(userResult, expectedResult, exercise) Compară cele două rezultate, pe rând: numărul de coloane, numărul de rânduri, valorile (fără să conteze ordinea rândurilor) și, doar dacă orderMatters este true, ordinea rândurilor.
5. js/lessons-ui.js Mesajul: verde sau roșu La exercițiile cu SELECT, sub mesaj apare și tabelul cu rândurile elevului. La cele cu INSERT/UPDATE/DELETE/CREATE, tabelul citit de interogarea ascunsă nu este afișat, iar mesajul explică în cuvinte ce diferă. Un exercițiu rezolvat primește „rezolvat” și este salvat în browser (localStorage, sub numele sqlPlayground.solved), deci progresul rămâne și după ce închizi pagina.

Regulile comparației

• Se compară doar valorile, nu și numele coloanelor, deci aliasurile pot fi oricare.
• Ordinea rândurilor contează doar dacă enunțul cere ORDER BY (orderMatters: true).
• Numerele sunt rotunjite la 6 zecimale (normalizeValue()), deci 7 și 7.0 sunt egale.
• Ca ordinea rândurilor să nu conteze, fiecare rând devine un text (rowKey()), apoi cele două liste de texte sunt sortate și comparate.
• Dacă SQL-ul are mai multe comenzi, se compară rezultatul ultimei comenzi care a întors rânduri (lastResultSet()).
• Exerciții cu INSERT, UPDATE, DELETE: după SQL-ul elevului, o interogare ascunsă (checkQuery) citește tabelul (de exemplu SELECT * FROM elevi ORDER BY id_elev;). La fel se face după soluție, iar cele două rezultate sunt comparate.
• Exerciții cu CREATE TABLE: interogarea ascunsă încearcă să adauge rânduri greșite cu INSERT OR IGNORE (un id repetat, un NULL într-o coloană NOT NULL, o valoare care nu respectă CHECK, o valoare repetată la UNIQUE), apoi citește tabelul. OR IGNORE sare peste un rând care încalcă o constrângere, deci dacă tabelul are constrângerile cerute, rândurile greșite nu apar; dacă lipsește una, ele apar și rezultatul diferă de al soluției. Cheia străină se verifică separat, cu pragma_foreign_key_list (lista cheilor străine ale tabelului), pentru că o cheie străină încălcată dă eroare chiar și cu OR IGNORE. Numele constrângerilor nu sunt verificate.

Exemple de mesaje

Diferențe față de Oracle

SQLite seamănă mult cu Oracle, dar nu este identic. Lecțiile și exercițiile evită aceste cazuri; lista de mai jos este aici ca să fie clar ce nu se comportă la fel.

Nu sunt suportate (dau eroare)

• ROWNUM
• FETCH FIRST n ROWS
• (+) join vechi
• MINUS
• secvențe
• DATE '...'
• EXTRACT
• DECODE
• TO_CHAR cu format de număr
• > ALL (...)
• = ANY (...)
• DELETE note WHERE ... fără FROM

Unde modific?

Fiecare linie de cod are un comentariu, iar toate culorile și mărimile sunt variabile în :root, la începutul fișierului css/style.css.

1. Pornești site-ul cu python3 serve.py (serverul proiectului, care dezactivează cache-ul browserului) și deschizi http://localhost:8000.
2. Deschizi fișierul din coloana „Fișier”, apeși Ctrl+F și cauți textul din coloana „Caută”.
3. Schimbi valoarea, salvezi fișierul (Ctrl+S) și apeși F5 în browser: modificarea apare imediat.

Dublu-clic pe index.html (adresă file://) nu merge: browserul nu lasă sql.js să își încarce fișierul .wasm și baza de date nu pornește. Site-ul trebuie deschis prin server.

--color-accent schimbă tot mov-ul: celelalte nuanțe (strălucirea --color-accent-glow, fundalul mov deschis --color-accent-soft, marginile --color-border, cuvintele de cod, titlul mare și butonul „Rulează”) sunt calculate din el (cu color-mix() sau direct cu var(--color-accent)), deci se schimbă singure. Dacă vrei ca una dintre ele să aibă altă culoare, scrii o culoare în locul formulei de pe linia ei. Singura excepție este iconița din tab (favicon.svg), care nu poate citi variabilele din CSS. --font-size-base schimbă doar textul normal; titlurile, butoanele și editorul au mărimile lor.

Cum am testat

Pe lângă verificarea în browser (pe calculator și pe telefon), proiectul are teste automate în folderul tests/. Ele nu sunt publicate (se publică doar site/) și rulează în Node.js, pe aceleași fișiere JavaScript ca site-ul.

• node tests/test-db.mjs: 207 verificări pentru db.js și translateError() (numărul de rânduri, constrângerile, fiecare funcție Oracle comparată cu valoarea dată de Oracle, COMMIT/ROLLBACK/LIMIT, comentariile, rândurile modificate, resetarea, traducerea erorilor).
• node tests/test-lessons.mjs: 171 de verificări pentru lecții și checker.js (fiecare exemplu rulează, fiecare soluție este acceptată, cel puțin un răspuns greșit la fiecare exercițiu este respins, iar la exercițiile cu CREATE TABLE sunt respinse tabelele fără o constrângere cerută sau cu un CHECK greșit).

Publicare

1. calculatorul meu git commit + git push Salvez modificările și le trimit pe GitHub.
2. GitHub Depozitul (repository) proiectului Păstrează codul și istoricul tuturor modificărilor.
3. Cloudflare Pages Publicare automată La fiecare push, publică folderul site/ așa cum este (fără „build”), în câteva secunde.

Pentru că toate fișierele sunt statice (HTML, CSS, JavaScript, SQL) și baza de date rulează în browser, site-ul nu are nevoie de un server propriu, de PHP sau de o bază de date găzduită.