Vai al contenuto principale

Distribuire PostgreSQL in 5 minuti

Questa guida la accompagna nella creazione del suo primo cluster PostgreSQL dalla console Hikube, fino alla prima connessione con psql.

Obiettivi​

Al termine di questa guida, avrà:

  • Un cluster PostgreSQL distribuito nel suo progetto Hikube
  • Un database applicativo e un utente per connettersi
  • Una password generata dalla piattaforma
  • Una connessione funzionante con psql

Prerequisiti​

  • Un account Hikube e un progetto con quota sufficiente (CPU, memoria, storage)
  • Il client psql installato sul suo computer, se desidera testare una connessione da Internet

Passo 1: Creare il cluster​

  1. Acceda alla console Hikube e selezioni il suo progetto.
  2. Nel menu laterale, apra DB & Messaging → PostgreSQL. Viene visualizzata la pagina PostgreSQL Clusters.
  3. Faccia clic su Create a cluster. Si apre la procedura guidata Create a PostgreSQL cluster.

Passo 2: Configurare e confermare​

La procedura guidata comprende sei passaggi: General, Configuration, Databases, Users, Summary e Finish. Passi dall'uno all'altro con Next e Previous.

General​

Inserisca il Cluster Name (per impostazione predefinita viene proposto un nome casuale), ad esempio demo-pg. Deve contenere da 3 a 16 caratteri (lettere minuscole, cifre e trattini), iniziare con una lettera e terminare con una lettera o una cifra.

Configuration​

CampoValore consigliato per questa guidaNota
PostgreSQL Version18Versioni proposte: 15, 16, 17, 18
Instance presets1.small — 1 CPU / 2GiNessun preset è preselezionato; capacità assegnata a ogni nodo
Disk size (GB)10Capacità di storage per nodo
Number of replicas1 (Standalone)2 o 3 per l'alta disponibilità
External accessAttivatoNecessario per connettersi dal suo computer

Procedura guidata PostgreSQL, passo Configuration

Il banner nella parte superiore della procedura guidata mostra l'Estimated cost e l'impatto sulla quota del progetto.

avviso

Il Number of replicas non può più essere modificato dopo la creazione. Per la produzione, scelga direttamente 2 (High Availability) o 3 (Max High Availability).

nota

Attivi l'External access solo se ne ha bisogno: espone il database sull'Internet pubblico.

Databases​

Inserisca un Database name, ad esempio myapp (da 1 a 54 caratteri: lettere minuscole, cifre, trattini bassi e trattini; inizia con una lettera o un trattino basso, ma non con pg_), quindi faccia clic su Add.

Aggiunga almeno un database applicativo: il database postgres, sempre creato, è un database di sistema riservato alla piattaforma, e i suoi utenti non possono ricevere alcun diritto su di esso.

Users​

Aggiunga almeno un utente:

  1. Username: ad esempio app_user (solo lettere minuscole, cifre e trattini bassi, nessun trattino).
  2. Database name: selezioni myapp. L'elenco propone solo i database aggiunti nel passaggio Databases. Senza database applicativo, mostra « No application database » e l'utente viene creato senza alcun diritto.
  3. Rights: Administrator (Admin) o Read-only.
  4. Faccia clic su Add.

Summary​

Rilegga il riepilogo (Version, Instance preset, Data volume, Replicas, External exposure, Databases to create, Users to create, Estimated cost), quindi faccia clic su Create cluster.

Passo 3: Verificare lo stato​

Il passaggio Finish conferma la creazione (« Creation complete! »). Faccia clic su Finish per aprire la pagina del cluster.

Lo stato del cluster è mostrato accanto al suo nome, sia nella pagina del cluster sia nell'elenco PostgreSQL Clusters:

StatoSignificato
CreatingIl cluster è in fase di provisioning
ReadyIl cluster è operativo
ErrorLa piattaforma non è riuscita ad applicare la creazione o l'ultima modifica del cluster

Risultato atteso: dopo alcuni minuti, lo stato passa a Ready. La pagina del cluster mostra la PostgreSQL Version, le Replicas, l'Allocated Size e l'External Access (Enabled).

Passo 4: Recuperare le credenziali​

Le password vengono mostrate una sola volta, nel passaggio Finish della procedura guidata, nella sezione User Credentials:

  • Password di ogni utente creato;
  • Internal Connection String: l'indirizzo del cluster, quando l'accesso esterno è attivato.

Se la piattaforma rifiuta un utente, il passaggio mostra « User not created » e il motivo, al posto della sua password.

Procedura guidata PostgreSQL, passo Finish: credenziali degli utenti (password oscurata)

avviso

Copi queste password in un gestore di password prima di lasciare la schermata: non verranno più mostrate. In caso di smarrimento, ne generi una nuova dalla scheda Users (Actions → Change Password).

Il riquadro Connection and Databases della pagina del cluster mostra i suoi indirizzi in due zone, ciascuna con un pulsante di copia:

  • Internal, From the project's resources only: l'host interno, sempre presente, e la porta (5432). È raggiungibile dalle VM e dai cluster Kubernetes dello stesso progetto, senza accesso esterno;
  • External, From the Internet: l'indirizzo pubblico, quando l'External Access è attivato.

Passo 5: Connessione e test​

Dalla sua postazione, si connetta con psql all'indirizzo della zona External:

psql "host=<host> port=5432 dbname=myapp user=app_user sslmode=require"

Da una VM o da un cluster Kubernetes del progetto, utilizzi l'host della zona Internal: psql "host=<host-interno> port=5432 dbname=myapp user=app_user".

Inserisca la password quando richiesta, quindi verifichi la connessione:

SELECT version();
CREATE TABLE test (id serial PRIMARY KEY, message text);
INSERT INTO test (message) VALUES ('Bonjour Hikube');
SELECT * FROM test;

Risultato atteso:

 id |    message
----+----------------
  1 | Bonjour Hikube
(1 row)

Passo 6: Risoluzione rapida dei problemi​

La zona External mostra « Disabled » o « Waiting for allocation… »​

« Disabled »: l'External Access è disattivato. Lo attivi tramite Edit se deve connettersi da Internet; dal progetto, utilizzi l'host della zona Internal. « Waiting for allocation… »: l'indirizzo pubblico non è ancora stato assegnato, attenda qualche istante.

L'host interno non si risolve da una VM​

Copi il nome completo della zona Internal, senza abbreviarlo. Su Debian 13, il nome non si risolve senza configurazione: vedere Raggiungere un servizio gestito del progetto.

Il pulsante Next resta inattivo​

  • Nel passaggio Configuration: il cluster supera la quota del progetto. Riduca il preset, la dimensione del disco o il numero di repliche.
  • Nel passaggio Users: aggiunga almeno un utente.

Autenticazione rifiutata​

Verifichi il nome utente, il database di destinazione e la password. Se la password è stata smarrita, effettui una rotazione dalla scheda Users. Consulti Gestire utenti e database.

Il cluster passa in stato Error​

La piattaforma non è riuscita ad applicare la creazione o l'ultima modifica del cluster. Contatti il supporto indicando il nome del progetto e del cluster.

Passo 7: Pulizia​

  1. Apra la pagina del cluster (DB & Messaging → PostgreSQL → nome del cluster).
  2. Faccia clic su Delete cluster.
  3. Inserisca il nome esatto del cluster nel campo Resource name to confirm, quindi faccia clic su Permanently delete.
avviso

Questa azione elimina il cluster PostgreSQL e tutti i dati associati. È irreversibile.

Dalla console ha creato:

  • Un cluster PostgreSQL nel suo progetto
  • Un database e un utente con i relativi diritti
  • Un accesso esterno e una connessione psql