Guide

I dati dei demo e PostgreSQL

Un progetto demo è fatto di due metà. Le pagine sono metadati e arrivano con il Designer. I dati che ci stanno sotto no: vivono in un database PostgreSQL, e finché non ce li metti tu le pagine si aprono e non mostrano niente.

Questa guida copre la seconda metà, dall'inizio, senza dare per scontato che tu abbia mai usato PostgreSQL.

Ti serve solo se fai girare GTmeta sulla tua macchina: la Suite o il kit sviluppatori. Se stai guardando i demo in linea, i dati ce li mettiamo noi e non devi fare niente.

Se arrivi da Oracle

Tre differenze, e sono esattamente quelle su cui si inciampa il primo giorno.

Oracle	PostgreSQL
L'istanza è il database	Il cluster (il servizio sulla porta 5432) contiene più database
Lo schema coincide con l'utente	Gli schemi stanno dentro un database, e i ruoli sono un'altra cosa
Listener e `tnsnames.ora`	Host, porta e nome del database, più un file di regole, `pg_hba.conf`

Due conseguenze pratiche:

una connessione vede un solo database. Non si fa una query che ne tocca due, come faresti fra due schemi Oracle. Per questo qui sotto mettiamo tutti i demo nello stesso database, in schemi diversi;
i tablespace esistono anche qui, ma non si creano quasi mai. Tutto va nel predefinito. Per dati di queste dimensioni non è un argomento.

1. Installare PostgreSQL

Scarica l'installer da https://www.postgresql.org/download/ — versione 18 o successiva. È obbligatorio: i file che distribuiamo sono prodotti con la 18, e una versione precedente si rifiuta di leggerli.

Durante l'installazione, tre schermate contano.

Select Components. Lascia tutte e quattro le spunte, e in particolare Command Line Tools. Se salti quella, pg_restore non viene installato e più avanti pgAdmin ti dirà che gli manca una libreria, senza spiegare perché. È l'errore più comune di tutta la procedura.

Password. Te la chiede per l'utente amministratore, che si chiama postgres. Annotala: serve a ogni collegamento.

Port. Lascia 5432.

Alla fine parte Stack Builder e ti propone componenti aggiuntivi (pgAgent, pgBouncer e altri). Non ti serve nessuno: premi Cancel. Non installa niente e non lascia niente in sospeso.

Se hai già installato senza i Command Line Tools, non disinstallare: rilancia lo stesso installer e scegli Modify, poi spunta Command Line Tools. Il database che hai già non viene toccato.

pgAdmin 4: su Windows è già lì

pgAdmin 4 è l'interfaccia grafica. È un progetto a sé, con il suo download su https://www.pgadmin.org/download/, ma l'installer Windows di PostgreSQL lo include fra i componenti: se lasci la spunta, non devi scaricare altro. Su Linux e macOS invece va preso a parte.

Due cose che confondono, e che non sono guasti:

non compare nessuna icona sul desktop, e alla fine l'installazione non dice niente di lui. Lo trovi nel menu Start, sotto PostgreSQL 18 → pgAdmin 4;
non è obbligatorio. Tutto quello che c'è qui sotto si può fare da riga di comando con gli strumenti che arrivano col database. pgAdmin serve a vederci dentro, ed è comodo la prima volta.

2. Creare il database

Ne basta uno solo per tutti i demo: ogni file che scarichi si porta dietro il proprio schema, quindi convivono senza pestarsi.

Apri pgAdmin 4. Nell'albero a sinistra trovi Servers e sotto la connessione alla tua macchina. Attenzione al vocabolario: quel livello è il servizio PostgreSQL, non un database. I database stanno sotto, nel ramo Databases, e all'inizio ce n'è uno solo, postgres, che è di servizio. Non caricarci dentro niente.

Tasto destro su Databases → Create → Database…, campo Database:

gtmeta_demo

Owner postgres, Save.

Da riga di comando è la stessa cosa:

createdb -U postgres gtmeta_demo

3. Caricare un demo

Scarica il file del demo dalla pagina Downloads del sito. È un file .backup: il formato compresso di PostgreSQL, che si carica con pg_restore. Non va scompattato e non serve nessun altro programma.

Con pgAdmin

seleziona il database gtmeta_demo nell'albero — non il livello del server, e non postgres. La voce Restore lavora sul database selezionato;
tasto destro → Restore…;
Format: Custom or tar;
Filename: il file .backup scaricato;
Restore.

Il resto delle opzioni si lascia com'è. Il file è già preparato per caricarsi sotto il tuo utente, senza cercare ruoli che sulla tua macchina non esistono.

Da riga di comando

pg_restore -U postgres -d gtmeta_demo gtmeta-demo-hrdemo-20260923.backup

Ripeti per ogni demo che vuoi: finiscono tutti nello stesso database, ciascuno nel suo schema.

4. Dirlo alla Suite

Il database ora ha i dati, ma la Suite non sa che esiste. Si collega dove le dici tu.

Entra come amministratore e vai in Administration & Settings → Connections. Trova la connessione del demo e mettici i tuoi valori:

campo	valore
server	`localhost`
porta	`5432`
database	`gtmeta_demo`
schema	quello del demo (`hr` per HRDEMO, `tpx` per TPXDEMO)
utente / password	i tuoi

Lo schema è il campo che chi arriva da Oracle tende a saltare, ed è quello che decide se le pagine trovano le tabelle.

Poi apri il progetto demo: i dati ci sono.

Se qualcosa non torna

«Nella finestra di Restore non vedo il file.» Sei nella cartella giusta ma il filtro non mostra quel tipo. Scegli All files.

«Restore è grigio.» Non hai selezionato un database. La voce lavora sul nodo selezionato.

«Manca una DLL» (libpq.dll, libcrypto-3-x64.dll). I Command Line Tools non sono installati, o pgAdmin punta a una cartella sbagliata. Controlla File → Preferences → Paths → Binary paths: la riga di PostgreSQL 18 deve puntare alla bin della 18, per esempio C:\Program Files\PostgreSQL\18\bin.

«unsupported version in file header» / «archive created with a newer version». Stai usando un pg_restore più vecchio del file. Succede quando sulla macchina convivono più versioni di PostgreSQL. Verifica lo stesso Binary paths.

«database does not exist». Il database non è stato creato, oppure il nome è scritto diverso. I nomi in PostgreSQL sono minuscoli: gtmeta_demo, non GTmeta_Demo.

«Ho disinstallato e reinstallato, e qualcosa non torna.» La disinstallazione su Windows non toglie la cartella dati, e te lo scrive. Se resta, la nuova installazione la riusa: ti ritrovi la vecchia password di postgres invece di quella appena scelta. Controlla che C:\Program Files\PostgreSQL sia sparita del tutto prima di reinstallare.

«Dopo la reinstallazione pgAdmin si ricorda ancora la connessione di prima.» È normale e non vuol dire che sia rimasto qualcosa del database. Le connessioni che vedi nell'albero sono segnalibri di pgAdmin, salvati nel tuo profilo utente (%APPDATA%\pgAdmin), non nel database. Per capire se l'installazione è davvero pulita guarda il contenuto: sotto Databases deve esserci solo postgres, e deve chiederti la password nuova.

«Le pagine si aprono ma sono vuote.» Il caricamento è andato bene ma la connessione punta altrove, o lo schema è sbagliato. Torna al punto 4.