Mia mamma usa Linux! » Database http://www.miamammausalinux.org Perché niente è impossibile da capire... Se lo spieghi bene ! Tue, 27 Jul 2010 12:03:21 +0000 en hourly 1 http://wordpress.org/?v=3.0.1 MySQL Cluster, un database ad alta affidabilità : Parte 3 http://www.miamammausalinux.org/2006/03/mysql-cluster-un-database-ad-alta-affidabilita-parte-3/ http://www.miamammausalinux.org/2006/03/mysql-cluster-un-database-ad-alta-affidabilita-parte-3/#comments Wed, 01 Mar 2006 11:30:15 +0000 Raoul Scarazzini http://www.miamammausalinux.org/?p=149 mysql

In questo terzo ed ultimo articolo completeremo il discorso sul cluster MySQL imparando a consultare i log, a capire le fasi di avvio ed i meccanismi di registrazione. Infine effettueremo il backup ed il restore delle basi dati registrate.

Consultare i log

Prima di effettuare qualsiasi tipo di operazione per comprendere la gestione dei log, è necessario avviare il cluster.
Partendo dal presupposto che tutti i file sono configurati come illustrato negli scorsi numeri, dal management server è necessario lanciare il comando :

$ ndb_mgmd --config-file=/mysql/config.ini

E su ciascuno dei nodi dati :

$ ndbd -n

L’opzione “-n”, come già spiegato, inizializza i nodi dati senza avviarli. L’avvio effettivo dei nodi dati andrà forzato attraverso la shell ndb_mgm e consentirà di controllare attraverso i log le fasi di avvio. Sempre attraverso questa shell, è possibile verificare lo stato attuale del cluster :

$ ndb_mgm
-- NDB Cluster -- Management Client --
ndb_mgm> show
Connected to Management Server at: management.mycluster.local:1186
Cluster Configuration
---------------------
[ndbd(NDB)]     2 node(s)
id=2    @192.168.0.2  (Version: 5.0.12, not started)
id=3    @192.168.0.3  (Version: 5.0.12, not started)
 
[ndb_mgmd(MGM)] 1 node(s)
id=1    @192.168.0.1  (Version: 5.0.12)
 
[mysqld(API)]   1 node(s)
id=4 (not connected, accepting connect from any host)

Quanto visualizzato, conferma che stiamo operando su di un cluster che comprende due nodi dati (in stato “not started”), un nodo di management ed un nodo client, al momento non connesso.
I nodi dati ed il nodo di management registrano i log nella cartella che è stata dichiarata nella sezione DataDir all’interno del file config.ini del management server.
Nel nostro caso, la DataDir dei nostri nodi è /mysql/. Al di sotto di questa, su ciascun nodo, si trovano file denominati ndb_ID_out.log, dove “ID” rappresenta l’identificativo del nodo, quindi ad esempio, il nodo di management scriverà i log all’interno del file ndb_1_out.log.
Visualizzando il contenuto di questi file, ci si può fare una chiara idea di ciò che i vari nodi stanno facendo.
Partendo dalla macchina di management, il contenuto del file sarà questo :

$ tail /mysql/ndb_1_out.log
NDB Cluster Management Server. Version 5.0.12 (beta)
Id: 1, Command port: 1186

Questo conferma che il management è stato avviato ed è in ascolto sulla porta 1186.
Sul nodo due, il file conterrà :

$ tail /mysql/ndb_2_out.log
2005-10-28 10:10:54 [NDB] INFO     -- Angel pid: 11026 ndb pid: 11027
2005-10-28 10:10:54 [NDB] INFO     -- NDB Cluster -- DB node 2
2005-10-28 10:10:54 [NDB] INFO     -- Version 5.0.12 (beta) --
2005-10-28 10:10:54 [NDB] INFO     -- Configuration fetched at management.mycluster.local port 1186

Mentre nel nodo tre, il file avrà questo contenuto :

$ tail /mysql/ndb_3_out.log
2005-10-28 10:10:59 [NDB] INFO     -- Angel pid: 11061 ndb pid: 11062
2005-10-28 10:10:59 [NDB] INFO     -- NDB Cluster -- DB node 3
2005-10-28 10:10:59 [NDB] INFO     -- Version 5.0.12 (beta) --
2005-10-28 10:10:59 [NDB] INFO     -- Configuration fetched at management.mycluster.local port 1186

In entrambi i casi, abbiamo la conferma che i nodi dati si sono avviati nella maniera corretta e sono collegati al management server tramite la porta 1186.
Da notare come vengano indicati anche i pid (ossia i numeri identificativi) dei DUE processi relativi al nodo dati : quello angelo, che consente il controllo dei processi dalla console remota ndb_mgm, e quello effettivo, che si occupa della gestione dell’interscambio dati.
Le informazioni relative allo stato generale del cluster sono memorizzate sul management server nel file denominato ndb_1_cluster.log. In questo file vengono registrati tutti gli eventi che riguardano il cluster. Appena avviato ed una volta effettuate le connessioni da parte dei nodi dati e client, il suo contenuto dovrebbe essere simile al seguente :

$ tail /mysql/ndb_1_cluster.log
2005-10-28 10:10:47 [MgmSrvr] INFO     -- NDB Cluster Management Server. Version 5.0.12 (beta)
2005-10-28 10:10:47 [MgmSrvr] INFO     -- Id: 1, Command port: 1186
2005-10-28 10:10:54 [MgmSrvr] INFO     -- Mgmt server state: nodeid 2 reserved for ip 192.168.0.2, m_reserved_nodes 0000000000000006.
2005-10-28 10:10:54 [MgmSrvr] INFO     -- Node 1: Node 2 Connected
2005-10-28 10:10:55 [MgmSrvr] INFO     -- Mgmt server state: nodeid 2 freed, m_reserved_nodes 0000000000000002.
2005-10-28 10:10:59 [MgmSrvr] INFO     -- Mgmt server state: nodeid 3 reserved for ip 192.168.0.3, m_reserved_nodes 000000000000000a.
2005-10-28 10:10:59 [MgmSrvr] INFO     -- Node 1: Node 3 Connected
2005-10-28 10:11:00 [MgmSrvr] INFO     -- Mgmt server state: nodeid 3 freed, m_reserved_nodes 0000000000000002.

I nodi 2 e 3 sono stati inizializzati e tramite la connessione al management node, hanno ottenuto il proprio “Node ID” e la configurazione del cluster. Questa fase preliminare dell’avvio dei nodi prevede l’allocazione delle porte che verranno usate per la comunicazione inter-nodo ed infine l’allocazione della memoria in relazione a quanto dichiarato nella configurazione.

Log e Checkpoints

Per studiare le fasi di avvio del cluster attraverso i Log, è necessario comprendere i meccanismi con cui i dati vengono registrati su disco.
MySQL Cluster è un database distribuito su più nodi e le informazioni in esso contenute sono replicate in maniera sincrona. Questo significa che un’operazione di aggiornamento, definita “transazione”, prima di essere registrata nel database, cioè prima di raggiungere lo stato “commited”, deve essere effettuata sulla replica primaria e su ciascuna delle secondarie.
Anche se il database risiede completamente nella memoria del cluster, è ovvio che ciascun nodo possiede un filesystem nel quale vengono fisicamente memorizzati i dati. Sarebbe altrimenti impossibile recuperare i dati una volta spente le macchine, visto che il contenuto della RAM è svuotato ad ogni avvio del computer. Questo filesystem si trova su ogni nodo nella directory dichiarata come DataDir nel file di configurazione. Ad esempio, per il nodo con id 2, il filesystem verrà memorizzato all’interno della directory /mysql/ndb_2_fs.
Ciascun nodo, tiene traccia delle transazioni all’interno del “REDO log”. La funzione del REDO log è quella di fornire un backup in caso l’intero cluster cada. I log sono controllati in maniera centralizzata, ma vengono effettuati localmente, sul filesystem di ciascun nodo.
Il REDO log è registrato in memoria e ad intervalli regolari (di default ogni 2 secondi) scritto su disco. Ogni volta che il REDO log viene scritto, viene effettuato un “Global Checkpoint” o “GCP” :

Figura 1

Figura 1

La frequenza con cui i GCP vengono eseguiti può essere variata all’interno del file di configurazione del management server, indicando per l’opzione TimeBetweenGlobalCheckpoints un valore in millisecondi fra 10 e 32000.
Per alleggerire il carico di informazioni registrate nei REDO log (che è un file incrementale e che quindi continua ad ingrandirsi) e consentire una rapida ricostruzione in caso di totale caduta del cluster, MySQL effettua, sempre ad intervalli regolari, dei “Local Checkpoints” o “LCP”.
Durante un LCP viene creata una copia su disco, definita “Snapshot”, di tutto il database e viene alleggerito il Redo Log al quale viene rimossa la coda delle operazioni svolte sino a quel momento :

Figura 2

Figura 2

Un LCP impiega parecchio tempo a completarsi e viene effettuato mentre il database viene aggiornato. Quanto viene scritto quindi, è da considerarsi inconsistente, in quanto potrebbero esserci delle transazioni non concluse, delle tabelle su cui persiste un lock e così via. Per questo motivo, al momento dell’avvio di un LCP, viene creato un UNDO log, ossia un registro delle operazioni effettuate dal database durante il LCP.
L’UNDO log consente di rendere lo snapshot del database, una volta terminato il LCP, di nuovo consistente :

Figura 3

Figura 3

Anche in questo caso la frequenza degli LCP può variare in funzione alle esigenze, settando nel file di configurazione l’opzione TimeBetweenLocalCheckpoints.
Riassumendo, se un solo nodo per qualsiasi ragione cade, si ricostruirà seguendo queste fasi :

  • Riconnessione al server di management e segnalazione della propria presenza agli altri membri;
  • Copia dei metadata, ossia tabelle, indici ed informazioni del cluster dal management server;
  • Copia dei dati dal nodo primario;
  • Riassunzione dello stato di nodo primario;

Se invece sarà tutto il sistema a cadere, allora il database verrà ricostruito partendo dall’ultimo LCP e dalle parti di REDO Log che sono state registrate su disco dall’ultimo GCP. Le transazioni registrate DOPO l’ultimo GCP verranno perse. Questa serie di operazioni è definita “System recovery”.

Le fasi di avvio del Cluster

A questo punto possiamo seguire le fasi di avvio del cluster direttamente dal file di log della macchina di management, lanciando il comando

$ tail -f /mysql/ndb_1_cluster.log

e forzando da una nuova shell della macchina di management l’avvio dei nodi dati tramite il programma ndb_mgm :

$ ndb_mgm
-- NDB Cluster -- Management Client --
ndb_mgm> all start
Connected to Management Server at: management.mycluster.local:1186
NDB Cluster is being started.
NDB Cluster is being started.

Nel file di ndb_1_cluster.log si potranno seguire le operazioni preliminari di avvio del cluster :

2005-10-28 11:06:59 [MgmSrvr] INFO     -- Node 2: Start initiated (version 5.0.12)
2005-10-28 11:06:59 [MgmSrvr] INFO     -- Node 3: Start initiated (version 5.0.12)
2005-10-28 11:06:59 [MgmSrvr] INFO     -- Node 2: Start phase 0 completed
2005-10-28 11:06:59 [MgmSrvr] INFO     -- Node 2: Communication to Node 3 opened
2005-10-28 11:06:59 [MgmSrvr] INFO     -- Node 3: Start phase 0 completed
2005-10-28 11:06:59 [MgmSrvr] INFO     -- Node 3: Communication to Node 2 opened
2005-10-28 11:06:59 [MgmSrvr] INFO     -- Node 2: Node 3 Connected
2005-10-28 11:06:59 [MgmSrvr] INFO     -- Node 3: Node 2 Connected

Da questo punto in poi, i nodi attraverseranno le varie fasi che porteranno all’avvio effettivo del cluster. Queste, definite stage, sono 12 e partono da 0 :

  • Stage 0 : Se il processo ndbd è stato avviato tramite un “initial start”, cioè con l’opzione –initial (si veda l’articolo precedente), viene pulito il filesystem del nodo relativo.
  • Stage 1 : E’ la prima vera fase di avvio in cui vengono stabilite le connessioni tra i nodi ed avviati gli heartbeat (letteralmente “battito cardiaco”), ossia i processi di controllo esistenza di ciascun nodo verso gli altri.
    Una comunicazione heartbeat prevede uno scambio di messaggi come “Io ci sono. Tu ci sei ?” che consentono ad ogni nodo di decidere come agire in caso di problemi. Ad esempio, una mancata risposta ad un heartbeat da parte di un nodo primario imporrebbe al nodo contenente la replica secondaria di far diventare la sua copia di dati primaria.
  • Stage 2 : In questa fase viene eletto il nodo bilanciatore, che può essere o il management node o uno dei nodi sql client. La funzione del nodo bilanciatore sarà quella di decidere come distribuire il carico delle richieste sui nodi dati.
  • Stage 3 : Vengono inizializzate alcune variabili interne del cluster.
  • Stage 4 : Se viene forzata la pulitura del filesystem relativo a tutto il cluster o al singolo nodo, viene creato il “REDO log”.
  • Stage 5 : In questa fase, un nodo che è stato riavviato (e deve quindi reinserirsi nel cluster) viene sincronizzato con il nodo master ed incluso nelle transazioni.
  • Stage 6 e 7 : Viene effettuato l’aggiornamento di variabili interne.
  • Stage 8 : Vengono ricostruiti tutti gli indici.
  • Stage 9 : Viene effettuato l’aggiornamento di variabili interne.
  • Stage 10 : Le applicazioni possono connettersi ai nodi ed incominciare ad effettuare interscambio dati.
  • Stage 11 : Un nodo immesso all’interno del cluster assume il ruolo di replica primaria ed effettua l’invio della replica allo slave associato.

Il passaggio da una fase all’altra è segnalato all’interno dei log con il messaggio “Start phase completed” :

...
2005-10-28 11:06:59 [MgmSrvr] INFO     -- Node 2: Start phase 1 completed
...

Chiaramente, non avendo ancora collegato un client e non avendo effettuato alcun riavvio, al termine della fase 9 il nostro cluster è avviato :

...
2005-10-28 11:07:05 [MgmSrvr] INFO     -- Node 2: Started (version 5.0.12)
2005-10-28 11:07:05 [MgmSrvr] INFO     -- Node 3: Communication to Node 4 opened
2005-10-28 11:07:05 [MgmSrvr] INFO     -- Node 3: Communication to Node 5 opened
2005-10-28 11:07:05 [MgmSrvr] INFO     -- Node 3: Communication to Node 0 opened
2005-10-28 11:07:05 [MgmSrvr] INFO     -- Node 3: Start phase 8 completed (initial start)
2005-10-28 11:07:05 [MgmSrvr] INFO     -- Node 3: Start phase 9 completed (initial start)
2005-10-28 11:07:05 [MgmSrvr] INFO     -- Node 3: Started (version 5.0.12)
2005-10-28 11:07:06 [MgmSrvr] INFO     -- Node 3: Node 1: API version 5.0.12
2005-10-28 11:07:06 [MgmSrvr] INFO     -- Node 2: Node 1: API version 5.0.12
2005-10-28 11:07:06 [MgmSrvr] INFO     -- Node 3: Prepare arbitrator node 1 [ticket=399a0001367af1d4]
2005-10-28 11:07:06 [MgmSrvr] INFO     -- Node 2: Started arbitrator node 1 [ticket=399a0001367af1d4]

E’ da notare come l’ultimo messaggio indichi chi sia l’arbitrator node (il bilanciatore del carico), cioè il management server.
A questo punto, per completare l’avvio del Cluster ed iniziare ad accedere alle tabelle, possiamo avviare il server mysqld che si collegherà al cluster

$ mysqld --defaults-file=/mysql/my.cnf &

ed osservare quanto viene scritto nei log :

2005-10-28 15:57:26 [MgmSrvr] INFO     -- Mgmt server state: nodeid 4 reserved for ip 192.168.0.4, m_reserved_nodes 0000000000000012.
2005-10-28 15:57:27 [MgmSrvr] INFO     -- Node 3: Node 4 Connected
2005-10-28 15:57:27 [MgmSrvr] INFO     -- Node 2: Node 4 Connected
2005-10-28 15:57:27 [MgmSrvr] INFO     -- Node 2: Node 4: API version 5.0.12
2005-10-28 15:57:27 [MgmSrvr] INFO     -- Node 3: Node 4: API version 5.0.12

Il client mysqld si è collegato al server di management, ha scaricato la configurazione e si è collegato direttamente ai nodi dati del cluster con cui effettuerà interscambio dati.
Un’ultima nota riguardo ai log del cluster riguarda l’esecuzione dei Local Checkpoints che verrà segnalata all’interno del file /mysql/ndb_1_cluster.log sulla macchina di management con righe simili a quella che segue :

2005-10-28 11:07:05 [MgmSrvr] INFO     -- Node 2: Local checkpoint 1 started. Keep GCI = 1 oldest restorable GCI = 1

Questa riga indica che è stato avviato il LCP con identificativo 1 sul Nodo 2 e che l’ultimo GCP ripristinabile è quello con identificativo 1.
Ovviamente, mano a mano che passerà il tempo, altre indicazioni di questo tipo seguiranno :

...
...
2005-10-28 12:01:43 [MgmSrvr] INFO     -- Node 2: Local checkpoint 2 started. Keep GCI = 1 oldest restorable GCI = 2
2005-10-28 12:56:21 [MgmSrvr] INFO     -- Node 2: Local checkpoint 3 started. Keep GCI = 1609 oldest restorable GCI = 3
...
...
2005-11-01 04:16:15 [MgmSrvr] INFO     -- Node 2: Local checkpoint 100 started. Keep GCI = 157530 oldest restorable GCI = 8890
2005-11-01 05:10:53 [MgmSrvr] INFO     -- Node 2: Local checkpoint 101 started. Keep GCI = 159138 oldest restorable GCI = 8890
...
...

Come si può osservare, la frequenza tra un Local Checkpoint ed un altro è di circa un ora.

Backup e Restore

Terminata la spiegazione relativa ai log, concludiamo il discorso relativo al Cluster MySQL con le operazioni di Backup e Restore.

Backup

Effettuare backup periodici di una base dati è essenziale per svariate ragioni : riparare ad errori causati dalle applicazioni, effettuare un aggiornamento del cluster (che non è possibile eseguire in linea) e ripristinare l’intera base dati in seguito ad un totale crash del sistema.
I metodi di backup sono essenzialmente due : logico e fisico.

Backup logici : I backup logici riguardano l’esportazione della struttura logica del database in file sql. Tali backup possono essere effettuati attraverso gli strumenti canonici di mysql quali ad esempio il programma mysqldump.
Questi si rivelano utili per il trasferimento dell’intera base dati ad un altro tipo di database, essendo scritti nel linguaggio sql standard, universalmente comprensibile.
Un esempio di come effettuare un backup tramite mysqldump è il seguente :

$ mysqldump  ndb_test > ndb_test_BACKUP.sql

Questo comando creerà un file denominato ndb_test_BACKUP.sql nella directory corrente che conterrà tutti gli statement sql necessari alla totale ricostruzione del database ndb_test che abbiamo creato nel precedente articolo.
Questo metodo di backup risulta comodo se si ha la necessità di esportare database dalle dimensioni ridotte o semplicemente singole tabelle, ma su basi dati dalle dimensioni sostenute, non risulta una scelta vincente.

Backup fisici : I backup fisici riguardano le copie fisiche dei filesystem dei nodi. Questo tipo di backup è realizzabile unicamente attraverso l’utilizzo degli strumenti offerti dalla suite mysql-max e proprio per questo, su basi dati di grandezza notevole, è più performante di un backup logico.
Per avviare un backup è sufficiente avviare la console di management e digitare il comando “start backup” :

ndb_mgm> start backup
Waiting for completed, this may take several minutes
Node 2: Backup 1 started from node 1
Node 2: Backup 1 started from node 1 completed
StartGCP: 300415 StopGCP: 300418
 #Records: 4098 #LogRecords: 0
 Data: 65688 bytes Log: 0 bytes

Quanto visualizzato, conferma la corretta esecuzione del backup : nella directory /mysql di ciascun nodo, è stata creata una sottodirectory denominata BACKUP che conterrà a sua volta tante sottodirectory quanti saranno i backup che effettueremo. Per il nodo 2 ad esempio, questa sarà la struttura delle directory :

$ pwd
/mysql/BACKUP/BACKUP-1
$ ls
BACKUP-1-0.2.Data  BACKUP-1.2.ctl  BACKUP-1.2.log

I file creati sono tre. Questo perché la struttura dei backup MySQL Cluster è composta da tre parti : i metadata (ossia le informazioni sulla struttura del database), i dati delle tabelle ed il log relativo alle transazioni.
I tre file creati hanno quindi le seguenti corrispondenze :

  • BACKUP-..ctl contenente i metadata;
  • BACKUP--..Data contenente i metadata;
  • BACKUP-..log contenente i log delle transazioni;

Restore

Per effettuare il restore di backup logici è sufficiente eseguire gli statement sql presenti nel file creato con il comando mysqldump.
Discorso a parte va fatto per i backup fisici, il cui restore si può effettuare solo tramite l’utilizzo del programma ndb_restore.
Anche se il backup è stato effettuato in maniera centralizzata, ossia attraverso la console di management, i file di backup effettivi risiedono su ciascun nodo, pertanto il restore va lanciato tante volte quanti sono i nodi dati presenti nel cluster.
Per prima cosa quindi, considerando come le tabelle che verranno ripristinate non dovranno esistere, è necessario rimuoverle dal database di test creato nello scorso articolo :

$ mysql
Welcome to the MySQL monitor.  Commands end with ; or g.
Your MySQL connection id is 1 to server version: 5.0.12-beta-max
 
Type 'help;' or 'h' for help. Type 'c' to clear the buffer.
 
mysql> drop table ndb_test.test;
Query OK, 1 row affected (0.22 sec)
 
mysql> quit
Bye

Successivamente, va considerato che il programma ndb_restore agisce come un nodo sql e per connettersi al server di management necessita di un node id disponibile.
La configurazione del cluster a cui il management node fa riferimento prevede la connessione di un solo nodo client, che quindi non deve essere occupato dal server mysqld. Prima di lanciare le operazioni di backup è necessario stoppare dalla macchina di management il server mysqld, ad esempio in questo modo :

$ pkill mysqld

a questo punto è possibile avviare il test di restore recandosi sul nodo 2 e lanciando questo comando :

$ ndb_restore --connect="nodeid=4;host=management.mycluster.local:1186" --nodeid=2 --backupid=1 --restore_meta --restore_data /mysql/BACKUP/BACKUP-1/
Ndb version in backup files: Version 5.0.12
Connected to ndb!!
Successfully restored table ndb_test/def/test
_____________________________________________________
Processing data in table: ndb_test/def/test(2) fragment 0
_____________________________________________________
Processing data in table: sys/def/NDB$EVENTS_0(1) fragment 0
_____________________________________________________
Processing data in table: sys/def/SYSTAB_0(0) fragment 0
Restored 0 tuples and 0 log entries

Il comando eseguito è autoesplicativo, vengono passati i parametri di connessione (–connect), l’identificativo del nodo a cui appartiene il backup (–nodeid), l’identificativo del backup (–backupid), cosa ripristinare (–restore_meta e -–restore_date) ed infine la directory in cui risiede il backup.
Successivamente, la stessa operazione andrà lanciata dal nodo 3 con le dovute modifiche :

$ ndb_restore --connect="nodeid=4;host=management.mycluster.local:1186" --nodeid=3 --backupid=1 --restore_data /mysql/BACKUP/BACKUP-1/
Ndb version in backup files: Version 5.0.12
Connected to ndb!!
_____________________________________________________
Processing data in table: ndb_test/def/test(2) fragment 1
_____________________________________________________
Processing data in table: sys/def/NDB$EVENTS_0(1) fragment 1
_____________________________________________________
Processing data in table: sys/def/SYSTAB_0(0) fragment 1
Restored 0 tuples and 0 log entries

Da notare come non sia presente l’opzione –restore-meta in quanto essendo i metadati già stati ripristinati nel precedente restore, tale operazione non è più necessaria.
Una volta riavviato dalla macchina di management il server mysqld :

$ mysqld --defaults-file=/mysql/my.cnf &

Potremo verificare il corretto ripristino della tabella test attraverso la shell del comando mysql :

mysql> use ndb_test;
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A
 
Database changed
mysql> show tables;
+--------------------+
| Tables_in_ndb_test |
+--------------------+
| test               |
+--------------------+
1 row in set (0.01 sec)

Conclusioni

Ovviamente la tabella di test considerata, non contenendo alcun record, risulta poco attendibile per un test significativo, ma è più che sufficiente per comprendere le meccaniche del funzionamento di questo prodotto. Ciò che si è voluto illustrare è come MySQL Cluster possa rappresentare, una volta debitamente configurato, un’alternativa gratuita, valida e soprattutto ad alta affidabilità rispetto ad altri costosi concorrenti commerciali.
Segnalo alcuni link da cui ho tratto parte delle informazioni presentate in questi articoli :
Il manuale ufficiale di MySQL Cluster : http://dev.mysql.com/doc/refman/5.0/en/ndbcluster.html
Un esempio su come realizzare un cluster a due nodi : http://www.davz.net/static/howto/mysqlcluster
Dell’altra ottima documentazione : http://www.browardphp.com/mysql_manual_en/manual_NDBCluster.html

La serie comprende questi articoli :

MySQL cluster, un database ad alta affidabilità : Parte 1
MySQL cluster, un database ad alta affidabilità : Parte 2
MySQL cluster, un database ad alta affidabilità : Parte 3

Nota :

Questo articolo è originariamente apparso nell’edizione italiana di Linux Journal nel Dicembre 2005/Gennaio 2006.

]]> http://www.miamammausalinux.org/2006/03/mysql-cluster-un-database-ad-alta-affidabilita-parte-3/feed/ 0 MySQL cluster, un database ad alta affidabilità : Parte 2 http://www.miamammausalinux.org/2006/02/mysql-cluster-un-database-ad-alta-affidabilita-parte-2/ http://www.miamammausalinux.org/2006/02/mysql-cluster-un-database-ad-alta-affidabilita-parte-2/#comments Wed, 01 Feb 2006 11:30:19 +0000 Raoul Scarazzini http://www.miamammausalinux.org/?p=139 mysql

In questo secondo articolo cercheremo di capire come si installa e configura il cluster MySQL sulla base dei concetti esposti nel precedente, che ne è l’ideale introduzione.

Preparare l’ambiente

Nel preparare l’ambiente per il primo test sul cluster MySQL, dobbiamo tenere in considerazione i discorsi affrontati nello scorso articolo sull’argomento Single Point Of Failure (o SPOF) e soprattutto, su come questi vadano evitati cercando di ridondare le risorse critiche il cui malfunzionamento potrebbe compromettere la stabilità del sistema.
E’ quindi impensabile, seppur possibile, effettuare dei test su una singola macchina. Il numero minimo di macchine su cui si dovrà lavorare sarà tre. Due nodi di storage ed uno di management.
Sui nodi storage faremo in modo di configurare delle repliche incrociate dei dati per testare, in caso di perdita di un nodo, come il sistema rimanga accessibile. Sul terzo nodo configureremo, oltre al demone per il management al quale i nodi di storage si collegheranno per ricevere le impostazioni di configurazione, anche un demone MySQL server in ascolto per poter manipolare i dati e permettere ad eventuali altre applicazioni di connettersi al cluster.
La struttura del nostro progetto è riassunta in figura1

Figura 1

Figura 1

Nella figura, fra parentesi viene indicato il nome host. Tale nome verrà indicato nelle configurazioni che effettueremo. Se però non si dispone di un DNS, indicare l’indirizzo IP sarà comunque corretto.
Un’utile scappatoia potrebbe essere quella di aggiungere al file /etc/hosts presente in ogni macchina, le righe relative a ciascuna macchina facente parte del nostro cluster, in questa forma :

127.0.0.1	localhost.localdomain		localhost
192.168.0.1	management.mycluster.local	management
192.168.0.2	storage_a.mycluster.local	storage_a
192.168.0.3	storage_b.mycluster.local	storage_b

Certo il progetto non rispetta in pieno le rigide regole anti-SPOF elencate nello scorso articolo, ma trattandosi di un ambiente di test e non di produzione, risulta più che sufficiente.
Nel momento in cui si vorrà portare in produzione il progetto, allora ci si dovrà preoccupare di aumentare il numero di nodi di storage (sempre in numero pari), dividere management e MySQL server e ridondare ciascuno.

Scegliere il corretto software

Abbiamo già spiegato nel precedente articolo come i binari di MySQL che si trovano nelle comuni distribuzioni non abbiano le funzionalità HA. Per ottenere dei binari che soddisfino queste esigenze esistono due metodi : il primo sta nel ricompilare con apposite opzioni i sorgenti, il secondo nell’utilizzare il pacchetto binario mysql-max.
Salvo esigenze specifiche, utilizzare il pacchetto mysql-max-5.0.12-beta-linux-i686.tar.gz scaricabile da questo indirizzo http://dev.mysql.com/downloads/mysql/5.0.html risulta una scelta vincente, mentre per sistemi con architetture differenti come ia64 o amd64, esistono le versioni di mysql-max relative.
Il link indicato porta non a caso alla versione 5.0 del pacchetto, che viene indicata come BETA. Infatti, anche se al momento la versione stabile è la 4.1, nel corso dell’articolo ci concentreremo sulla 5.0. Per prima cosa perché non manca molto affinché diventi la release ufficiale ad essere distribuita ed inoltre presenta notevoli miglioramenti che vale la pena vedere in funzione.
Un elenco delle funzionalità aggiuntive presenti nella versione 5.0 lo si osserva in figura 2.

Figura 2

Figura 2

Sempre all’indirizzo indicato per i download esiste la possibilità di scaricare anche i pacchetti rpm, convertibili senza problemi per le distribuzioni Debian in pacchetti deb tramite il software alien.
In tutto i pacchetti di binari sono quattro : MySQL-ndb-management, che contiene gli eseguibili per il nodo di management, MySQL-ndb-storage, contenente quelli per i nodi storage ed infine i pacchetti MySQL-ndb-tools e MySQL-ndb-extra contenenti programmi di utilità.
Esiste anche la possibilità di ricompilare manualmente i sorgenti scaricandosi il pacchetto .tar.gz ed indicando in fase di configurazione l’opzione –with-ndb-cluster. Tale operazione è però sconsigliata dagli stessi sviluppatori per ragioni di ottimizzazione e stabilità.
Nel corso dell’articolo utilizzeremo il pacchetto di binari tar.gz su tutte le macchine del cluster, poiché contiene tutti gli eseguibili necessari per far funzionare i nodi di storage, quello di management ed il server MySQL oltre a numerosi programmi di utilità e parecchi esempi.
Nulla vieta, una volta compresi i ruoli dei vari programmi, di utilizzare i pacchetti rpm per le installazioni in modo da ridurre il carico di spazio occupato dall’installazione.

Installazione

Utilizzando come stabilito i binari precompilati nel pacchetto .tar.gz, l’installazione è quanto di più semplice possa esservi. Basterà, su ciascuna macchina, scompattare il file in una directory stabilita, ad esempio /usr/local.
Essendo il nome della neo creata directory piuttosto lungo, converrà creare anche un link simbolico che ne faciliti l’accesso :

$ cd /usr/local/
$ tar -xzvf /<directory del file>/mysql-max-5.0.12-beta-linux-i686.tar.gz
$ ln -s  mysql-max-5.0.12-beta-linux-i686 mysql

All’interno di questa directory si trova tutto il necessario per la costruzione del cluster.
Sarà utile creare, sempre su ciascuna macchina, anche una cartella /mysql sotto la quale verranno posti i file di configurazione ed i dati stessi.
Infine, per non dover lanciare i comandi ricorrendo tutte le volte ai path completi, possiamo aggiungere la directory dei binari /usr/local/mysql/bin/ alla variabile d’ambiente $PATH, inserendo questa riga all’interno del file /etc/profile :

$ export PATH=$PATH:/usr/local/mysql/bin/

In questo modo tutti gli eseguibili del pacchetto mysql-max saranno disponibili senza che sia necessario indicarne tutto il path.

Configurare il Management server

La configurazione del server di Management risiede in un singolo file, denominato config.ini.
Tale file andrà creato nella directory /mysql del management server con questo contenuto :

[NDB_MGMD]
id=1
HostName=management
 
[NDBD DEFAULT]
NoOfReplicas=2
DataMemory=1950M
IndexMemory=450M
 
[NDBD]
id=2
HostName=storage_a
DataDir=/mysql/
 
[NDBD]
id=3
HostName=storage_b
DataDir=/mysql/
 
[MYSQLD]

Come si può notare, il file è diviso in sezioni, ciascuna delle quali inizia con una direttiva tra parentesi quadre. Ogni sezione termina quando inizia l’altra.
Prima di analizzare nel dettaglio ogni riga inserita, va detto che la configurazione indicata risulta ridotta, nel senso che esistono moltissime direttive per esigenze specifiche e sono tutte documentate da MySQL a questo indirizzo : http://dev.mysql.com/doc/mysql/en/mysql-cluster-config-file.html.

  • [NDB_MGMD] : Contiene le impostazioni relative al management server, nel nostro caso abbiamo dichiarato che tale nodo avrà identificativo 1 e che l’hostname relativo sarà “management”. Ancora una volta va sottolineato che tale nome deve essere risolto dal DNS, altrimenti il cluster non potrà
    funzionare. In alternativa, si può inserire l’indirizzo IP.
  • [NDBD_DEFAULT] : Contiene le impostazioni comuni a tutti i nodi dati (NDBD). In questo caso sono stati indicati il numero di repliche (due secondo la struttura illustrata in figura1) e la quantità riservata alla memoria dati e indici.
    Tale cifra è ottenibile con questa operazione

    DataMemory = Node RAM * Total Nodes / Replicas

    La quantità di memoria degli indici va stabilita in base alle esigenze, un buon compromesso può essere circa il 20% della DataMemory.
    I valori indicati nell’esempio sopra, sono quindi del tutto indicativi, poiché dipendono dalle macchine utilizzate per effettuare i test.

  • [NDBD] : Ciascuna di queste sezioni contiene le impostazioni del singolo nodo dati, per il quale vengono indicati l’identificativo numerico, il nome host (o l’indirizzo IP) e la directory nella quale verranno memorizzati i dati.
    Le sezioni NDBD dovranno essere tante quante i nodi dati.
  • [MYSQLD] : Ciascuna di queste sezioni contiene le impostazioni dei singoli nodi sql. Per nodi sql si intendono server mysql, applicazioni che si basano sulle MySQL cluster API (di cui abbiamo parlato nello scorso articolo) o le stesse applicazioni della suite di mysql-max.
    In questo caso è stato previsto quindi un solo client collegabile.

La configurazione del nodo di management termina qui, il file config.ini dovrà essere letto dal file eseguibile ndb_mgmd. Questo file eseguibile agirà da demone e rimarrà in ascolto per le connessioni dei nodi dati.

Configurare i nodi storage

Tutte le impostazioni dei nodi dati risiedono sul management server ed ognuno di essi prima di fare qualsiasi cosa vi si connette per capire come è composto il cluster e quale ruolo deve svolgere all’interno di questo.
Anche in questo caso esiste un file eseguibile che agisce da demone e che consente di effettuare il collegamento, “scaricare” la configurazione dal management server e comunicare con gli altri nodi dati per creare l’NDB Cluster, questo file è ndbd.
L’unica cosa da configurare è l’accesso al server di management, e ciò si ottiene creando un file denominato /etc/my.cnf che conterrà le impostazioni di configurazione lette da ndbd.
E’ comunque possibile passare all’eseguibile i dati di connessione direttamente a riga di comando.
Il file /etc/my.cnf conterrà quanto segue :

[MYSQL_CLUSTER]
ndbcluster
ndb-connectstring=management.mycluster.local

Chiaramente quanto scritto andrà ripetuto anche sul secondo nodo dati storage_b.
La configurazione dei nodi storage è così completata.

Configurare il server MySQL

L’ultima parte della configurazione riguarda il MySQL server che nel nostro caso abbiamo deciso di configurare sulla stessa macchina del management (ma che potrebbe risiedere su di una a se stante).
Per prima cosa, è necessario creare l’utenza mysql (gruppo mysql) con cui verrà eseguito il server :

$ groupadd mysql
$ useradd -g mysql mysql

Fatto questo, si può procedere all’installazione dei database di sistema, utilizzando il file
contenuto nella cartella scritps/ che si trova nell’alberatura creata dell’installazione del file tar.gz descritta poco sopra :

$ cd /usr/local/mysql/
$ scripts/mysql_install_db -–user=mysql

Chiaramente si è forzata l’utenza mysql per l’esecuzione delle operazioni per ovvie ragioni di sicurezza.
Una volta completata questa operazione, non rimane che settare i permessi delle directory relative :

$ chown -R root:mysql .
$ chown -R mysql data/

Come ultima cosa, è necessario creare un file denominato my.cnf ad esempio sotto la cartella /mysql contenente, oltre ad alcune opzioni per il server stesso, le impostazioni di connessione al cluster :

[MYSQLD]
user=mysql
port=3306
socket=/tmp/mysql.sock
datadir=/usr/local/mysql/data
basedir=/usr/local/mysql
 
[MYSQL_CLUSTER]
ndbcluster
ndb-connectstring=management.mycluster.local

Le opzioni relative al server MySQL rispecchiano la nostra installazione : l’utente con cui verrà eseguito il server sarà “mysql”, la porta su cui sarà in ascolto sarà quella standard “3306”, il file di socket per le connessioni sarà /tmp/mysql.sock, le directory dei dati e del server saranno rispettivamente /usr/local/mysql/data e /usr/local/mysql.
Le altre opzioni presenti nell’area [MYSQL_CLUSTER] sono le stesse dei due nodi storage. Si riferiscono infatti al server di management.
La configurazione del MySQL server è quindi completa.

Avviare il nodo di management

La sequenza in cui le varie componenti del cluster verranno andranno sarà la seguente : server di management, nodi storage ed infine server MySQL.
Come osservato in fase di configurazione, il programma demone che rimarrà in ascolto come management server è ndb_mgmd, questo significa che sulla macchina management.mycluster.local andrà eseguito il seguente comando :

$ ndb_mgmd --config-file=/mysql/config.ini

Il parametro passato è ovviamente il file di configurazione da noi creato.
La porta TCP su cui il demone rimane in ascolto è la 1186, per verificare quindi che questa sia aperta è possibile lanciare il seguente comando :

$ netstat -natp | grep ndb
tcp        0      0 0.0.0.0:1186            0.0.0.0:*               LISTEN     10303/ndb_mgmd
tcp        0      0 192.168.0.1:35563       192.168.0.1:1186          ESTABLISHED10303/ndb_mgmd
tcp        0      0 192.168.0.1:1186        192.168.0.1:35565         ESTABLISHED10303/ndb_mgmd
tcp        0      0 192.168.0.1:1186        192.168.0.1:35563         ESTABLISHED10303/ndb_mgmd

Un output simile quello riportato, indica che il processo è in esecuzione ed in ascolto.
Da questo punto in avanti, per gestire il cluster utilizzeremo il programma ndb_mgm :

$ ndb_mgm
-- NDB Cluster -- Management Client --
ndb_mgm>

All’interno della shell ndb_mgm, è possibile osservare lo stato del cluster, avviare e stoppare i nodi, modificare i metodi di logging e così via. Una panoramica dei comandi disponibili si ottiene digitando help e premendo invio, per il momento, limitiamoci a digitare show e premere invio :

ndb_mgm> show
Connected to Management Server at: management.mycluster.local:1186
Cluster Configuration
---------------------
[ndbd(NDB)]     2 node(s)
id=2 (not connected, accepting connect from storage_a)
id=3 (not connected, accepting connect from storage_b)
 
[ndb_mgmd(MGM)] 1 node(s)
id=1    @192.168.0.1  (Version: 5.0.12)
 
[mysqld(API)]   1 node(s)
id=4 (not connected, accepting connect from any host)

Si può osservare come sia stata visualizzata tutta la configurazione del cluster : Il management server ndb_mgmd(MGM) è in attesa di connessioni da parte dei due nodi dati ndbd(NDB) (ciascuno dei quali associato alla rispettiva macchina, storage a o b) e di un server MySQL mysqld(API).

Avviare i nodi dati

Per avviare i nodi dati che costituiranno l’NDB Cluster, dobbiamo recarci su ciascuna delle macchine storage ed avviare il programma ndbd :

$ ndbd

Per verificare che il processo sia in esecuzione, possiamo filtrare l’output del comando ps come segue :

$ ps aux | grep ndbd
root      3845  0.0  0.0  6476 2872 ?        S    12:41   0:00 ndbd
root      3846  3.5  6.1 1930968 251212 ?    S    12:41   0:00 ndbd
root      3878  0.0  0.0  3692  668 pts/0    S    12:41   0:00 grep ndbd

Come si noterà dall’output, pur avendo lanciato solo una volta il comando, nell’elenco dei processi si trovano due processi ndbd. Non c’è nulla di sbagliato in questo, infatti il demone ndbd prevede che esista un processo base che si occupi dei dati ed un processo “angelo custode” che consenta al nodo dati di essere gestito da remoto.
Il concetto si può capire pensando alle operazioni di restart di un nodo che prevedono il kill del processo ndbd ed il suo nuovo avvio. Se dal management server si volesse effettuare un’operazione come quella descritta ed esistesse un unico processo ndbd sul nodo dati, sarebbe impossibile farlo ripartire una volta stoppato. Vi è quindi la necessità che a guidare le operazioni del processo ndbd principale vi sia un angelo custode.
A questo punto se ritorniamo sul management server e sempre dalla shell ndb_mgm lanciamo il comando show, otterremo quanto segue :

$ ndb_mgm
-- NDB Cluster -- Management Client --
ndb_mgm> show
Connected to Management Server at: management.mycluster.local:1186
Cluster Configuration
---------------------
[ndbd(NDB)]     2 node(s)
id=2    @192.168.0.2  (Version: 5.0.12, Nodegroup: 0, Master)
id=3    @192.168.0.3  (Version: 5.0.12, Nodegroup: 0)
 
[ndb_mgmd(MGM)] 1 node(s)
id=1    @192.18.0.1 (Version: 5.0.12)
 
[mysqld(API)]   1 node(s)
id=4 (not connected, accepting connect from any host)

Quanto visualizzato conferma che i due nodi dati sono correttamente avviati, appartengono ad un unico Nodegroup e che il nodo nodo con id 2 è Master.
Fra tutte le opzioni passabili da riga di comando all’eseguibile ndbd, due in particolare meritano una spiegazione “-n” e “–initial”.
“-n” o “–nostart” sta per “Don’t start ndbd immediately”, questo significa che il nodo dati diverrà attivo solo quando riceverà il comando start dal management node. Il nodo dati sarà quindi in stato “not started”. Supponiamo di aver avviato a questo punto il nodo dati 3 con il comando “ndbd -n”. Un comando show dalla console di ndb_mgm produrrà quindi tra le altre questa riga :

[...]
id=3    @192.168.0.3 (Version: 5.0.12, not started)
[...]

Il nodo dati 3 rimarrà in stato “not started” sino a che dalla shell di ndb_mgm non verrà forzato lo start del nodo :

ndb_mgm> 3 start
Database node 3 is being started.

Fatto questo, il nodo dati 3 sarà “online” :

[...]
id=3    @192.168.0.3 (Version: 5.0.12, Nodegroup: 0)
[...]

L’altra importante opzione passabile ad ndbd è “–initial”. Passare questa opzione significa forzare la pulizia del filesystem relativo al nodo dati. Se l’initial start è effettuato su di un solo nodo, allora i dati verranno ricostruiti in base alle repliche presenti sull’altro, mentre se l’operazione viene effettuata su tutti i nodi, allora l’intera base dati viene ripulita.
Questa opzione torna utile quando vengono effettuate delle modifiche strutturali al cluster come ad esempio la modifica della memoria disponibile.
Vedremo nel prossimo articolo come sfruttare questo parametro.

Avviare il mysqld

Per avviare il mysqld basterà lanciare il comando mysqld a cui andrà passato il percorso del file di configurazione creato poco sopra tramite l’opzione “–defaults-file=” :

$ mysqld --defaults-file=/mysql/my.cnf &

Il carattere & alla fine del comando consente di mettere il processo in background per poter continuare a lavorare nella console.
E’ possibile inoltre verificare che il processo mysqld sia in ascolto sulla porta configurata :

$ netstat -natp | grep mysqld
tcp        0      0 0.0.0.0:3306                0.0.0.0:*                   LISTEN      15129/mysqld
tcp        0      0 192.168.0.1:34398          192.168.0.1:1186           ESTABLISHED 15129/mysqld
tcp        0      0 192.168.0.1:34402          192.168.0.2:32782          ESTABLISHED 15129/mysqld
tcp        0      0 192.168.0.1:34401          192.168.0.3:32779          ESTABLISHED 15129/mysqld

A questo punto l’avvio del cluster può dirsi completato, infatti ndb_mgm conferma che tutte le componenti sono operative :

$ ndb_mgm
-- NDB Cluster -- Management Client --
ndb_mgm> show
Connected to Management Server at: management.mycluster.local:1186
Cluster Configuration
---------------------
[ndbd(NDB)]     2 node(s)
 
 
 
 
id=2    @192.168.0.2  (Version: 5.0.12, Nodegroup: 0)
id=3    @192.168.0.3  (Version: 5.0.12, Nodegroup: 0, Master)
 
[ndb_mgmd(MGM)] 1 node(s)
id=1    @192.168.0.1  (Version: 5.0.12)
 
[mysqld(API)]   1 node(s)
id=4    @192.168.0.1  (Version: 5.0.12)

Utilizzo del motore NDB

Per effettuare dei test di funzionamento del motore cluster, utilizzeremo il programma client MySQL dalla macchina di management :

$ /usr/local/mysql/bin/mysql
 
Welcome to the MySQL monitor.  Commands end with ; or g.
Your MySQL connection id is 2 to server version: 5.0.12-beta-max
 
Type 'help;' or 'h' for help. Type 'c' to clear the buffer.
 
mysql>

Per prima cosa verificheremo che nell’elenco dei motori MySQL disponibili sia presente anche quello del cluster NDB, con questo comando :

mysql> show engines;
+------------+---------+----------------------------------------------------------------+
| Engine     | Support | Comment                                                        |
+------------+---------+----------------------------------------------------------------+
...
|
| NDBCLUSTER | YES     | Clustered, fault-tolerant, memory-based tables                 |
| NDB        | YES     | Alias for NDBCLUSTER                                           |
...
+------------+---------+----------------------------------------------------------------+
18 rows in set (0.00 sec)

Se tra le righe risultanti appariranno anche quelle relative ad NDBCLUSTER, avremo la conferma del supporto al motore cluster da parte del server MySQL installato sulla macchina di management.
Occorre però un chiarimento. Tale server possiede le medesime funzionalità di un comune server MySQL ed anzi, se non si sfruttano direttive particolari in fase di creazione delle tabelle, queste verranno gestite dal motore di default, che si chiama MyISAM, e non dal motore NDB.
Per capire meglio questo concetto, procediamo col creare un database di test :

mysql> CREATE DATABASE ndb_test;
Query OK, 1 row affected (0.00 sec)

All’interno creeremo una semplice tabella da un campo di tipo integer contenente un singolo valore :

mysql> USE ndb_test;
Database changed
mysql> CREATE TABLE test (i INT);
Query OK, 0 rows affected (0.02 sec)
 
mysql> INSERT INTO test (i) VALUES (1);
Query OK, 1 row affected (0.00 sec)
 
mysql> SELECT * FROM test;
+------+
| i    |
+------+
|    1 |
+------+
1 row in set (0.00 sec)

Al momento la tabella NON è ancora gestita dal motore NDB, e ciò è confermato da questo comando :

mysql> SHOW CREATE TABLE test;
+-------+-----------------------------------------------------------------------------------------+
| Table | Create Table                                                                            |
+-------+-----------------------------------------------------------------------------------------+
| test  | CREATE TABLE `test` (
  `i` int(11) default NULL
) ENGINE=MyISAM DEFAULT CHARSET=latin1 |
+-------+-----------------------------------------------------------------------------------------+
1 row in set (0.00 sec)

ENGINE=MyISAM indica infatti che la tabella viene gestita localmente dal motore MyISAM.
Per fare in modo di porre sotto motore NDB la tabella, è necessario forzare il motore da usare in fase di creazione, aggiungendo alla fine del comando CREATE TABLE la clausola ENGINE=NDBCLUSTER :

mysql> CREATE TABLE test (i INT) ENGINE=NDBCLUSTER;

oppure modificare la tabella appena creata come segue :

mysql> ALTER TABLE test ENGINE=NDBCLUSTER;
Query OK, 1 row affected (0.44 sec)
Records: 1  Duplicates: 0  Warnings: 0

A questo punto i dati della tabella (una sola, importantissima riga !) sono replicati sui nodi del cluster e sono raggiungibili attraverso il server mysqld da qualsiasi applicazione :

mysql> SHOW CREATE TABLE test;
+-------+---------------------------------------------------------------------------------------------+
| Table | Create Table                                                                                |
+-------+---------------------------------------------------------------------------------------------+
| test  | CREATE TABLE `test` (
  `i` int(11) default NULL
) ENGINE=ndbcluster DEFAULT CHARSET=latin1 |
+-------+---------------------------------------------------------------------------------------------+
1 row in set (0.05 sec)

Un ultimo importante chiarimento riguarda eventuali altri server MySQL che potranno essere collegati al cluster NDB. Infatti il motore NDB agisce a livello di tabelle non di database. Questo significa che non è il database ad essere replicato, ma solo le tabelle. Su ciascun ulteriore server MySQL collegato dovranno quindi esistere i database relativi. Nel nostro caso ad esempio, se volessimo accedere alla tabella test da un’altro server MySQL configurato nel management server, dovremmo prima creare il database ndb_test al cui interno, senza fare nient’altro, troveremo le tabelle del cluster.

Conclusioni

Abbiamo visto in questo articolo come configurare ed avviare il cluster MySQL creando al suo interno una tabella di test.
Nel prossimo impareremo a consultare i log, effettueremo dei test di funzionamento simulando dei crash sui singoli nodi per accertarci che non esistano SPOF ed effettueremo modifiche sulla struttura del database. Infine impareremo ad effettuare backup e restore dei dati in modo da poter approfondire tutte le funzionalità di questo interessante progetto.

La serie comprende questi articoli :

MySQL cluster, un database ad alta affidabilità : Parte 1
MySQL cluster, un database ad alta affidabilità : Parte 2
MySQL cluster, un database ad alta affidabilità : Parte 3

Nota :

Questo articolo è originariamente apparso nell’edizione italiana di Linux Journal nel Dicembre 2005/Gennaio 2006.

]]> http://www.miamammausalinux.org/2006/02/mysql-cluster-un-database-ad-alta-affidabilita-parte-2/feed/ 0 MySQL cluster, un database ad alta affidabilità : Parte 1 http://www.miamammausalinux.org/2005/12/mysql-cluster-un-database-ad-alta-affidabilita-parte-1/ http://www.miamammausalinux.org/2005/12/mysql-cluster-un-database-ad-alta-affidabilita-parte-1/#comments Thu, 01 Dec 2005 11:30:22 +0000 Raoul Scarazzini http://www.miamammausalinux.org/?p=127 mysql

Cerchiamo di capire con questa serie di articoli come sia possibile impiegare il più famoso database utilizzato per applicazioni web in soluzioni di alta affidabilità.

MySQL : Solo un server SQL ?

Quanti non hanno sentito parlare almeno una volta di MySQL ? MySQL è il database più diffuso sul web per una svariata serie motivi, la velocità, la facilità d’impiego, la semplicità di accesso ed il supporto per i sistemi operativi più utilizzati. E’ inoltre un progetto Opensource che pur avendo alla base una reale azienda che deve produrre profitto, la svedese MySQL AB, distribuisce il proprio software liberamente.
Il database infatti è liberamente scaricabile dal sito ufficiale http://www.mysql.com nelle versioni per i sistemi operativi Linux, Solaris, Mac OSX, FreeBSD e tantissimi altri. Un elenco completo delle piattaforme supportate si trova a questo indirizzo : http://dev.mysql.com/downloads/mysql/5.0.html.
Detto questo, quello che molti non sanno è che MySQL AB sta sviluppando in parallelo al motore database standard anche una versione cluster, quello che viene definito un database ad alta affidabilità. Il progetto originale partì dalla necessità di un’importante azienda di telefonia di avere un motore database ad alta affidabilità che permettesse ricerche estremamente rapide.
La struttura relativamente semplice degli archivi dell’azienda si coniugava alla perfezione con le funzionalità offerte da MySQL, a cui mancava soltanto il supporto per l’alta affidabilità. Il prodotto finale di questi studi fu appunto MySQL cluster che da allora MySQL AB continua a far crescere in parallelo al motore standard.
Cercheremo di capire nel corso di questo articolo (e dei successivi) come funzioni e quali siano le potenzialità di questo progetto.

Cos’è un database ad alta affidabilità ?

Un database ad alta affidabilità (o HA, High Available) è semplicemente quello che dice di essere : una base dati sempre disponibile, che presenta ridondanza di processi e di dati, che non ha cioè singoli punti di rottura (o SPOF, Single Point Of Failure).
All’interno di un’architettura senza SPOF tutte le componenti presenti (Hardware e Software) sono ridondate. Se una componente smette di funzionare, l’integrità del sistema non è compromessa.
Tale concetto viene applicato a tutti i tipici cluster di servizi, come nel caso di uno share di rete NFS o un Web server debbano essere ridondati al fine di garantire che, in caso di interruzione dei processi principali, i servizi continuino ad essere erogati.
In un database, avere ridondanza di processi significa che se per una qualsiasi ragione, il processo Master (ossia quello a cui le applicazioni client fanno solitamente riferimento) dovesse cadere, il database rimarrebbe comunque accessibile (grazie ad un secondo processo, che diventerebbe a sua volta Master).
Avere ridondanza di dati invece, significa che il dato non è registrato in una singola posizione. Se questo si corrompe quindi, si ha la possibilità di ripristinarne il contenuto in base alla sua copia che risiede in una diversa posizione.
Tutte queste funzionalità permettono di avere un database senza SPOF : se si dovesse danneggiare una qualsiasi componente, logica o fisica, il sistema non risulterebbe compromesso.

Come ottenere un database ad alta affidabilità ?

Definito quindi il concetto di database HA, va capito nella realtà come sia possibile ottenerne uno, ovvero come si possano eliminare tutti i potenziali SPOF.
Il discorso SPOF non va sottovalutato, ma è necessario porsi dei limiti nella considerazione di tutti i possibili punti di rottura. Questo significa che se una singola macchina risulta essere un unico SPOF, ed è quindi necessario averne due, allora anche la stanza in cui saranno presenti le due macchine sarà uno SPOF e quindi sarebbe bene separare in stanze diverse le due macchine, ma a quel punto l’edificio stesso diventerebbe uno SPOF e proseguendo di questo passo si arriverebbe ben presto a capire come l’universo stesso sia un unico immenso SPOF !
Quindi, senza tirare in ballo la meccanica quantistica per creare un database cluster, è chiaro come sia necessario trovare il giusto equilibrio tra affidabilità e funzionalità.
Separare su macchine diverse le componenti del database è un buon compromesso : i processi, ossia la parte software che permette l’accesso al dato ed i dati stessi saranno su macchine distinte.
Questa logica, divide il cluster in due livelli : quello SQL, inerente ai processi, e quello Storage, inerente ai dati. Entrambi i livelli devono essere esenti da SPOF e devono quindi prevedere ridondanza.

La ridondanza di processi (livello SQL)

E’ necessario che il motore Sql che gestisce le richieste di accesso e le operazioni di lettura/scrittura sia sempre disponibile. Ad un motore Sql generalmente corrisponde un processo in ascolto presso un determinato indirizzo IP su una particolare porta. Rendere questa situazione ridondata, significa avere più di un motore Sql. Ciascuno di questi motori, idealmente, dovrebbe essere posto dietro ad un bilanciatore, cioè un software che renda disponibile un solo indirizzo IP di riferimento ma che distribuisca il carico delle richieste effettuate attraverso tutti i motori che sono stati configurati. Esistono diversi software adatti a questo scopo, ma una discussione in merito andrebbe oltre gli scopi del presente articolo. Per il momento, si può concludere dicendo che questa situazione eliminerebbe il SPOF legato al motore Sql.

La ridondanza dei dati (livello Storage)

Al pari della ridondanza dei processi, che riguarda più che altro l’alta affidabilità dell’accesso alla base dati, c’è la ridondanza dei dati stessi, che si può ottenere sostanzialmente in due modi o con una combinazione di entrambi : la ridondanza fisica e la ridondanza logica.
Per ottenere ridondanza fisica è sufficiente avere hardware dedicato a questo scopo, ad esempio controller RAID che gestiscano la duplicazione dei dati su due o più dischi in maniera trasparente. In caso di rottura fisica del disco, questa viene segnalata in modo da poter essere corretta (con la sostituzione del disco), ma l’accesso ai dati rimane comunque garantito.
Un po’ più complicato è il discorso relativo alla ridondanza logica. Per capire questo concetto, è necessario comprendere il significato di replica. Il numero di repliche all’interno di un database indica il numero copie multiple dello stesso dato. Le operazioni effettuate sul dato sono replicate su tutte le copie e fino a che questa operazione non è completata, la transazione che ha generato la modifica non è considerata conclusa. E’ chiaro quindi come esistano repliche primarie (le prime ad essere utilizzate) e repliche secondarie (le copie effettive) ed è altrettanto logico che avere due repliche del medesimo dato sullo stesso sistema non rispetti il principio dell’assenza di SPOF.
La soluzione ideale quindi sarebbe quella di avere come minimo due repliche distribuite su due diversi sistemi, come in figura 1.

Figura 1

Figura 1

Qui l’intero database è diviso in due partizioni. Nel primo sistema abbiamo la replica primaria della prima partizione e la replica secondaria della seconda partizione, mentre nel secondo, viceversa, è presente la replica primaria della seconda partizione e quella secondaria della prima. In questo modo in caso di rottura, blocco o qualsiasi evento comprometta il funzionamento di uno dei due sistemi, l’intera base dati è ricostruibile e l’accesso ai dati sempre disponibile.

La situazione ideale quindi, prevede che esista una base dati distribuita su almeno due sistemi, ciascuno dei quali contenente la propria replica primaria e la secondaria dell’altro sistema. L’accesso ai dati sarà reso disponibile da due motori Sql attraverso un unico indirizzo IP, gestito dal bilanciatore che distribuirà il carico delle richieste. In tutta questa struttura esiste un solo SPOF che è rappresentato dal bilanciatore stesso, che quindi a sua volta andrebbe ridondato.
Questa è la situazione perfetta (forse paranoica !) ed è illustrata in figura 2.

Figura 2

Figura 2

MySQL cluster

Definita quindi la struttura generale dei database cluster, possiamo spostare la nostra attenzione su come è composto un cluster MySQL.
Come tutti i database cluster, anche quello MySQL presenta la consueta architettura a due livelli : il livello SQL ed il livello Storage, denominato anche NDB Cluster, dove l’acronimo NDB sta per Network DataBase.
Ciascuna componente presente in un livello, è definita Nodo. Esisteranno quindi nodi client, ossia componenti appartenenti al livello SQL e nodi dati, cioè componenti del livello storage. Esiste anche una terza tipologia di nodo, denominato di management (gestione) che rappresenta il fulcro intorno al quale ruota il MySQL cluster e sul quale verrà fatto un discorso a parte.

I nodi client

I nodi client sono ciò che permettono alle utenze di effettuare operazioni sui dati e si dividono essenzialmente in tre categorie :

  1. Istanze dei server MySQL : la maggioranza dei casi, veri e propri server MySQL che si connettono alla base dati e si interfacciano all’esterno attraverso i classici processi demone mysqld.
  2. Applicazioni esterne che utilizzano l’accesso nativo ai dati : si tratta di applicazioni che non usano l’intermediario MySQL per accedere al database, ma lo fanno direttamente utilizzando quelle che vengono definite NDB API. Questi client effettuano l’accesso ai dati direttamente dal codice del programma costruito.
  3. Client nativi del cluster MySQL : ossia le applicazioni stesse del cluster, programmi cioè che consentono l’accesso e la manutenzione del cluster attraverso ad esempio operazioni di backup o restore. Tali applicazioni sono denominate NDB clients.

Tutti e tre i casi illustrati consentono all’utente di avere un interfaccia di accesso ai dati, in alcuni casi “consueta” (Il tipico server MySQL) ed in altri meno (le NDB API, delle quali bisogna avere una conoscenza piuttosto approfondita della programmazione database a basso livello).

I nodi dati

I nodi dati sono la struttura che si occupa della memorizzazione effettiva dei dati e compongono il già citato NDB Cluster.
Tutta quest’area lavora in maniera trasparente rispetto ai client. Il modo e la posizione in cui i dati vengono frammentati e la gestione delle repliche non sono conosciute dai client. Essi accedono, con i metodi illustrati poco sopra, solo all”entità NDB cluster.
A ciascuno dei nodi dati è associato un processo demone denominato ndbd.
Una cosa importante da capire è la sostanziale differenza di NDB cluster dagli altri prodotti database cluster in commercio, come ad esempio Oracle RAC. In questi infatti, l’alta affidabilità è garantita da una totale ridondanza. Questo significa che esistono due macchine identiche, ma una sola è attiva e si preoccupa di tenere allineata la seconda che rimane pronta a subentrare in caso di guasto.
All’interno di NDB cluster, tutti i nodi che fanno parte del sistema pur rispettando le regole di ridondanza e assenza di SPOF, contribuiscono al funzionamento del cluster incrementandone notevolmente le prestazioni.

Il nodo management

La parte più importante del cluster MySQL è rappresentata dal nodo di management, il nodo al quale tutte le componenti del cluster si connettono appena avviate per conoscere il resto del sistema.
In questo nodo è configurata la struttura del cluster : quanti e quali sono i nodi dati, quante repliche avranno le partizioni del sistema, quanta memoria sarà disponibile e così via.
Dal nodo di management è possibile avviare e stoppare i nodi dati, verificare lo stato del loro funzionamento, effettuare backup e restore, settare la tipologia dei log di ciascun client e stoppare l’intero cluster.
E’ interessante notare che, una volta che il cluster sia stato avviato, il nodo di management potrebbe tranquillamente smettere di funzionare. Tutti i nodi del cluster infatti, una volta ricevuti i parametri di configurazione dal nodo di management, iniziano a comunicare direttamente fra loro. Certo è che se si dovesse interrompere il processo del nodo di management sarebbe impossibile effettuare le altre operazioni descritte sopra, ma è importante capire che il cluster stesso, una volta che sia completamente avviato, sia indipendente dal nodo di management.
Il nodo di management è un processo demone, avviato tramite un file eseguibile chiamato ndb_mgmd che rimane in ascolto su una porta alle richieste dei nodi client.

In figura 3 viene illustrata la struttura logica del cluster MySQL.

Figura 3

Figura 3

Replicazione e frammentazione dei dati nel cluster MySQL

Ora che abbiamo capito la logica del cluster MySQL cerchiamo di concentrarci su come esso tratti la distribuzione dei dati. Questa è divisa in due parti : la frammentazione dei dati e la replicazione degli stessi.
La frammentazione dei dati consiste nel partizionare una tabella in un numero pari di frammenti che vengono divisi all’interno di un numero pari di nodi. La replicazione consiste nella duplicazione dei frammenti all’interno dei nodi.
Osserviamo la figura 4 :

Figura 4

Figura 4

In questo esempio, il database è organizzato in due nodi e due repliche. Tutto si rifà alla teoria dei cluster di database che abbiamo precedentemente spiegato ed illustrato in figura1. Qui ciò che veniva chiamato partizione è chiamato frammento ma il concetto non cambia : ciascun frammento di tabella è presente su entrambi i nodi, in un nodo come frammento primario e nell’altro come replica di questo. Il danneggiamento di un nodo non compromette l’intero sistema in quanto ogni sistema possiede le informazioni necessarie a ricostruire il totale delle informazioni presente nel sistema.
Si noterà come nella figura venga menzionato il “Nodegroup”.
All’interno del cluster MySQL il numero di Nodegroup si ottiene con questa semplice equazione :

Numero di Nodegroup = Numero di data nodes / Numero di repliche

Nel caso di figura4 quindi con due nodi dati e due repliche avremo un solo Nodegroup. Se invece avessimo a disposizione quattro macchine, potremmo organizzare il carico come illustrato in figura5, dove esistono 4 nodi dati con due repliche e quindi due NodeGroups.
Le tabelle in questo esempio sono frammentate in quattro partizioni e sono divise a coppie nei Nodegroup : ciascun Nodegroup contiene metà delle informazioni del database e ciascun nodo dati possiede un frammento primario dei quattro in cui è divisa la tabella.
Anche questa struttura non possiede SPOF.

Figura 5

Figura 5

Le combinazioni possibili del numero di repliche, dati e nodi non devono superare i limiti del cluster MySQL che sono di un massimo di : 4 repliche dei dati, 48 nodi dati, 64 nodi totali. Lavorando per coerenza con un numero pari di repliche e nodi dati, si possono ottenere situazioni che partono da due nodi con due repliche fino a quarantotto nodi con quattro repliche.
E’ chiaro che maggiore sarà il numero di repliche, minori saranno le performance in quanto le transazioni di scrittura non saranno completate sino a che l’informazione non verrà scritta in tutte le sue repliche.

Come organizzare CPU e Memoria sui nodi dati

L’organizzazione delle risorse fisiche del database è abbastanza semplice, nel senso che esistono delle regole precise su cui basarsi.

CPU

Ogni nodo dati deve essere associato ad una CPU, quindi è perciò sconsigliato configurare un sistema a singola CPU affinché esegua più di un processo ndbd (ossia il processo nodo dati del cluster). Per eseguire più di un nodo dati su una singola macchina è necessario usare sistemi Multi CPU, ma bisogna ricordarsi di eliminare lo SPOF macchina singola, pertanto, è necessario predisporre un minimo di due macchine con dual CPU.
Anche dal punto di vista logico, nel momento in cui si decide di mettere sulla stessa macchina due nodi data, è bene separare le risorse in modo che se una macchina va in crash il sistema non risulta compromesso : quindi nel caso in cui si decida di avere un database con quattro nodi data distribuiti su due macchine dual CPU sarà bene organizzare i Nodegroup come in figura 6 :

Figura 6

Figura 6

Con questa organizzazione, se anche una macchina va in crash, il sistema non è compromesso.

Memoria

La quantità di memoria disponibile nel cluster, viene calcolata con questa semplice equazione :

Memoria totale cluster = Memoria RAM Nodo dati * Numero totale di nodi / Numero di repliche

Quindi se avremo quattro gigabyte di memoria su ogni nodo dati, quattro nodi dati totali e due repliche, il nostro cluster avrà otto gibabyte di memoria disponibile.

Conclusioni

Abbiamo visto in questo articolo come è strutturato logicamente e come funziona il cluster MySQL. Nel prossimo eseguiremo una prova effettiva, configurando un cluster a due nodi ed imparando a gestire il tutto dal Management server.

La serie comprende questi articoli :

MySQL cluster, un database ad alta affidabilità : Parte 1
MySQL cluster, un database ad alta affidabilità : Parte 2
MySQL cluster, un database ad alta affidabilità : Parte 3

Nota :

Questo articolo è originariamente apparso nell’edizione italiana di Linux Journal nel Dicembre 2005/Gennaio 2006.

]]> http://www.miamammausalinux.org/2005/12/mysql-cluster-un-database-ad-alta-affidabilita-parte-1/feed/ 0 Una classe PHP per l’accesso a Firebird – Parte 3: Gestione delle Transazioni http://www.miamammausalinux.org/2004/12/una-classe-php-per-accesso-a-firebird-parte-3/ http://www.miamammausalinux.org/2004/12/una-classe-php-per-accesso-a-firebird-parte-3/#comments Wed, 01 Dec 2004 11:30:45 +0000 Raoul Scarazzini http://localhost/miamammausalinux.org/?p=78 firebird    php

Negli articoli precedenti abbiamo costruito parte di una classe PHP per l’accesso ad un database Firebird. Allo stato attuale delle cose, la nostra classe ci consente di effettuare query, navigare nei resultset ed operare sui campi BLOB.
In questo articolo cercheremo di completare il lavoro provando a capire cosa sono le Transazioni ed implementando un metodo che ci consenta di gestirle al meglio.

Panoramica sulle Transazioni

Nell’operare su basi dati complesse può capitare che per effettuare una determinata operazione sia necessario più di un singolo passo, ad esempio : Un cliente si collega ad un servizio B2B ed inserisce il suo ordine.
Quella che appare come una banale operazione di inserimento in realtà a livello dati potrebbe comportare ad esempio la scrittura della testata d’ordine nella tabella ordini, dei dettagli ordine in un’altra tabella contenente le varie righe, l’aggiornamento della tabella dello storico ordini ed infine l’aggiornamento del campo “data ultima operazione” nella tabella dei clienti.
Come si può facilmente capire, la singola operazione “inserisci ordine” è in realtà composta da 4 sotto-operazioni che dipendono l’una dall’altra in maniera inscindibile : se venissero inserite le righe di dettaglio dell’ordine senza che l’operazione di registrazione della testata fosse andata a buon fine, il database si troverebbe in uno stato inconsistente e non permetterebbe di effettuare l’inserimento restituendo un messaggio di errore.
Per mantenere la coerenza della nostra base dati, nel momento in cui una qualsiasi delle nostre sotto-operazioni dovesse fallire, anche tutte le altre andrebbero annullate.
In questo caso ed in mille altri simili, fare a meno delle Transazioni è praticamente impossibile.
Per definizione quindi, una Transazione è un’insieme di istruzioni SQL che deve essere trattato come un’unita’ “atomica”, cioe’ non scomponibile. Una Transazione viene completata solo se tutte le operazioni che la compongono vengono eseguite con successo. Nel caso in cui una delle operazioni fallisce oppure la Transazione viene esplicitamente annullata, tutte le operazioni precedenti devono essere ritenute nulle, come se non fossero mai state effettuate.
Usare le Transazioni risulta inoltre particolarmente utile nell’implementazione di meccanismi di locking (blocco) per permettere un accesso concorrente ai dati di un database, in quanto le modifiche operate sul database dalle istruzioni di una Transazione non hanno effetto su questo (e quindi non sono visibili ad altre Transazioni) fino a quando la Transazione non viene completata con successo.
Ogni volta che una Transazione viene avviata può concludersi in due modi : Successo o Insuccesso.
In caso di successo tutti gli inserimenti, cancellazioni e aggiornamenti vengono registrati nel database, in caso di insuccesso, il database non sarà in alcun modo modificato e si troverà nello stato immediatamente precedente all’avvio della Transazione.

Avviare una Transazione in Firebird

In Firebird ogni operazione effettuata su un database in realtà è parte di una Transazione. Nel momento stesso in cui viene effettuata una connessione ad un database, viene avviata, in maniera automatica e trasparente ai nostri occhi, una Transazione “di default”, che parte cioè automaticamente, senza bisogno di avviarla tramite istruzioni SQL.
Questo concetto viene spiegato con un esempio nel riquadro 1, e va chiarito da subito che non limita in alcun modo la possibilità di definire proprie Transazioni.
Per avviare manualmente una Transazione, è necessario utilizzare questa istruzione SQL :

SET TRANSACTION <ACCESS MODE> <LOCK RESOLUTION> <ISOLATION LEVEL> <TABLE RESERVATION> <DATABASE SPECIFICATION>

Cerchiamo di capire in maniera sintetica il significato di ciascuno dei parametri passabili all’istruzione :

ACCESS MODE : può essere READ ONLY o READ WRITE, questo parametro descrive il tipo di accesso effettuabile dalla Transazione sulle tabelle del database, se di sola lettura o di lettura e scrittura.

  • LOCK RESOLUTION : può essere WAIT o NO WAIT e descrive il tipo di comportamento che la Transazione deve assumere di fronte a record posti in stato di blocco (LOCK). Nel primo caso la Transazione attenderà sino a che il record non sarà sbloccato, nel secondo caso genererà un errore di tipo “LOCK CONFLICT”.
  • ISOLATION LEVEL : può essere SNAPSHOT, SNAPSHOT TABLE STABILITY o READ COMMITTED. Questo parametro descrive l’iterazione della Transazione con le altre (eventuali) in corso, il tipo di accesso alle medesime tabelle. Se dichiariamo SNAPSHOT, verrà restituita ad un’altra Transazione la vista del database al momento in cui la nostra è inziata; Indicando SNAPSHOT TABLE STABILITY non verranno consentite modifiche da parte di altre Transazioni alle tabelle che la nostra sta leggendo o updatando; per finire, con READ COMMITTED verrà consentito l’update sull’ultima versione registrata (quindi conclusa con una COMMIT RETAIN, la cui spiegazione viene affrontata nel paragrafo “Terminare una Transazione”) della riga in questione.
  • TABLE RESERVATION : consente indicando RESERVING di bloccare immediatamente l’accesso alle tabelle che verranno indicate.
  • DATABASE SPECIFICATION : indicando USING si può specificare una serie di database disponibili ai quali questa Transazione può accedere.

Utilizzare la Transazione di default equivale a dichiarare quanto segue :

SET TRANSACTION READ WRITE WAIT ISOLATION LEVEL SNAPSHOT;

Quindi per necessità diverse, saranno diversi i parametri che verranno passati all’istruzione SQL.
E’ possibile anche nominare le Transazioni, per distinguerle l’una dall’altra. L’argomento in se richiederebbe un’articolo a parte e non riguarda direttamente lo scopo del nostro articolo, quindi
ricordo che per approfondire l’argomento un’ottimo strumento gratuito rimane la documentazione di Interbase 6 scaricabile dal sito ufficiale di Firebird :
http://firebird.sourceforge.net/index.php?op=doc&id=userdoc
in particolare il capitolo 4 del libro “EMBEDDED SQL GUIDE” : “WORKING WITH TRANSACTIONS”.

Terminare una Transazione

Ora che è chiaro come viene avviata una Transazione, prima di proseguire, cerchiamo di capire come è possibile terminarla. Come già accennato i due stadi possibili sono successo ed insuccesso.
Le istruzioni associate a questi stadi sono COMMIT e ROLLBACK.
In caso di COMMIT tutti i cambiamenti effettuati all’interno del database diventano permanenti.
In caso di ROLLBACK, tutti i cambiamenti effettuati vengono annullati. Tipicamente, un’istruzione di ROLLBACK viene utilizzata in caso di errore durante lo svolgimento delle operazioni della Transazione per riportare il database allo stato iniziale.
Concludere una Transazione con uno di questi due metodi significa liberare le risorse allocate, rendendo più efficiente e veloce il database.
C’è un’ulteriore parametro passabile ad entrambe le istruzioni, questo è RETAIN.
Se viene aggiunta questa voce ad una delle due istruzioni, la Transazione non viene terminata, ma vengono invece registrate (o annullate) tutte le modifiche effettuate dall’avvio a quel momento. La Transazione rimane dunque aperta, passibile di altre istruzioni SQL comprese nuove COMMIT RETAIN o ROLLBACK RETAIN. E’ facile capire anche come il lanciare immediatamente dopo un comando comprensivo della voce RETAIN un’istruzione di tipo COMMIT o ROLLBACK non produca effetto alcuno se non il terminare la Transazione in corso.

Utilizzare le Transazioni in PHP

Il nostro obiettivo è quello di creare un metodo che consenta alla nostra classe di operare con le Transazioni.
Il supporto che PHP fornisce per gestire le Transazioni di Firebird si basa sul concetto di handle, ed anche se già dovrebbe essere chiaro in quanto parte fondamentale dei precedenti articoli, facciamo un veloce riepilogo : Un handle è un indirizzo di memoria al quale è associata la nostra connessione. In PHP questo indirizzo di memoria viene generalmente registrato all’interno di una variabile che viene usata ogni qualvolta si vogliono effettuare query sul database.
Il metodo exec_query, presente nella nostra classe infatti necessita (essendo basato sul metodo PHP ibase_query) di due parametri : l’handle del database e la stringa sql da eseguire.
Per le transazioni, il concetto è lo stesso. Ad ogni Transazione avviata corrisponde un handle, tutte le operazioni che si vorranno effettuare all’interno di questa dovranno far riferimento al suo handle specifico.
Per comodità definiremo un solo metodo per la gestione di tutte e tre le operazioni che in base ad un parametro definito, avvierà una Transazione, la completerà con una COMMIT o la annullerrà con una ROLLBACK.
Le funzioni che PHP mette a disposizione in merito all’argomento sono tre :

  • ibase_trans : richiede in input gli argomenti della Transazione (vedi Riquadro 2) e l’handle del database selezionato, mentre restituisce in output l’handle della transazione.
  • ibase_commit : dato in input l’handle della Transazione, effettua il commit e restituisce un valore booleano tra TRUE o FALSE a seconda di successo o insuccesso.
  • ibase_rollback : dato in input l’handle della Transazione, effettua il rollback ed in output si comporta alla stessa maniera di ibase_commit.

Organizzando il nostro metodo, potremmo pensare di usare due parametri : il primo denominato $action che conterrà la descrizione dell’operazione da svolgere : “start” per l’avvio di una transazione e “commit” o “rollback” per il termine di questa in uno dei due modi. Il secondo parametro, $tr_id, lo considereremo un “jolly” nel senso che in caso di avvio della Transazione conterrà gli argomenti di questa (si veda sempre il Riquadro 2), mentre per commit o rollback conterrà l’handle della Transazione da terminare.
A questo punto mettendo in pratica quanto accennato, il codice del nostro metodo, potrebbe presentarsi come segue :

FUNCTION transaction ($action, $tr_id = NULL)
{
 switch ($action)
 {
  case "start" :
   $this->connect();
   RETURN ibase_trans($tr_id, $this->Link_ID);
   break;
  case "commit" :
   RETURN ibase_commit($tr_id);
   break;
  case "rollback" :
   RETURN ibase_rollback($tr_id);
   break;
  DEFAULT :
   RETURN NULL;
   break;
 }
}

Tramite il costrutto switch, decido che tipo di operazione effettuare. Il valore restituito dalla funzione dipenderà dall’operazione selezionata : in caso di “start” sarà l’handle della Transazione, mentre per gli altri due casi sarà TRUE in caso di successo o FALSE se l’operazione fallisce.
Se viene indicato in $action un valore diverso dai tre illustrati, la funzione restituisce NULL.
Unica nota è il fatto che per azione uguale a “start” prima di eseguire la funzione ibase_trans, richiamo la funzione $this->connect() vista nel primo articolo, per fare in modo che la proprietà $this->Link_ID della classe sia un database handle effettivo.

Dalla teoria alla pratica

Una volta aggiunto questo nuovo metodo alla nostra classe, possiamo procedere con la creazione di un esempio effettivo.
Struttureremo lo script in modo che presenti una checkbox che consenta di scegliere una fra tre opzioni : in un caso effettuerà un inserimento nella tabella PEOPLE e terminerà con una ROLLBACK, nell’altro con una COMMIT ed in più aggiungeremo la possibilità di cancellare il record eventualmente inserito (in modo da poter ripetere l’esempio più volte). Alla fine effettueremo una SELECT sulla tabella e ne visualizzeremo l’esito in modo da osservare i cambiamenti prodotti dalle nostre operazioni.
La checkbox porterà allo script la variabile $_POST[“selection”] che tramite il costrutto switch presente nello script, selezionerà l’operazione da svolgere.
Il risultato finale sarà quanto appare nel riquadro 3 : Lo script presenta argomenti trattati nei precenti articoli quali il passaggio di parametri alla query e la stampa in una tabella del result set di una query e che qui non verranno ulteriormente approfonditi, le parti da esaminare a fondo sono quelle in cui viene avviata la Transazione

   $tr_id = $db->transaction("start", IBASE_DEFAULT);

In questo modo assegnamo alla variabile $tr_id l’handle della transazione e proprio in funzione di questo, la query di inserimento verrà lanciata con questa variabile come parametro di handle :

   if (!$db->exec_query($tr_id, $ssql))

Se l’operazione ha successo, viene effettuata (a seconda della scelta) l’operazione di rollback o commit che terrà come riferimento sempre $tr_id come handle :

    $db->transaction("rollback", $tr_id);

o

    $db->transaction("commit", $tr_id);

Il risultato consentirà di visualizzare il comportamento del database nei due diversi casi : solo per COMMIT il record viene inserito, la modifica non avrà effetto per ROLLBACK.
Un’ulteriore ed interessante test potrebbe riguardare l’argomento passato alla Transazione in fase di avvio : se al posto di IBASE_DEFAULT indichiamo IBASE_READ e proviamo ad inserire il record, sia che effettuiamo una commit, sia che effettuiamo una rollback, otteniamo questo errore :
“attempted update during read-only transaction”, ciò conferma ancora di più l’importanza che ricoprono gli argomenti passati alla Transazione in fase di avvio.
Il risultato finale dopo una COMMIT appare in Figura 1.

Figura 1

Figura 1

Conclusioni

Bene. Abbiamo finito. La nostra classe ora consente di effettuare tutte le operazioni che generalmente si fanno su un database Firebird.
Inutile sottolineare un’ultima volta come l’implementazione di tutti i metodi presentati è puramente indicativa. Le potenzialità di un progetto simile sono pressoché infinite.

Riquadro 1 : Le transazioni di “default”

Proviamo a fare una veloce prova sul db di test /home/janet/dbtest.gdb (creato negli scorsi articoli) utilizzando l’utilissimo tool da linea di comando “isql” presente nella directory di installazione di Firebird (generalmente /opt/interbase/bin), effettuando un inserimento nella tabella PEOPLE seguito da un’istruzione di ROLLBACK :

[root@conflitto janet]# /opt/interbase/bin/isql
Use CONNECT or CREATE DATABASE to specify a database
SQL> CONNECT /home/janet/dbtest.gdb USER sysdba PASSWORD masterkey;
Database:  /home/janet/dbtest.gdb, User: sysdba
SQL> SELECT PCODE, PNAME, PSURNAME FROM PEOPLE;
 
       PCODE PNAME                          PSURNAME
============ ============================== ==============================
 
           0 Vito                           Corleone
           1 Michael                        Corleone
           2 Sonny                          Corleone
           3 Fredo                          Corleone
           4 Tom                            Hagen
           5 Peter                          Clemenza
           6 Kay                            Adams Corleone
 
SQL> INSERT INTO PEOPLE (PCODE, PNAME, PSURNAME) VALUES (6, 'Luca', 'Brasi');
SQL> SELECT PCODE, PNAME, PSURNAME FROM PEOPLE;
 
       PCODE PNAME                          PSURNAME
============ ============================== ==============================
 
           0 Vito                           Corleone
           1 Michael                        Corleone
           2 Sonny                          Corleone
           3 Fredo                          Corleone
           4 Tom                            Hagen
           5 Peter                          Clemenza
           6 Kay                            Adams Corleone
           6 Luca                           Brasi
 
SQL> ROLLBACK;
SQL> SELECT PCODE, PNAME, PSURNAME FROM PEOPLE;
 
       PCODE PNAME                          PSURNAME
============ ============================== ==============================
 
           0 Vito                           Corleone
           1 Michael                        Corleone
           2 Sonny                          Corleone
           3 Fredo                          Corleone
           4 Tom                            Hagen
           5 Peter                          Clemenza
           6 Kay                            Adams Corleone
 
SQL> QUIT;

All’inizio in tabella, effettuando la prima select, osserviamo come siano presenti solamente 6 record. Una volta effettuato l’inserimento, e rilanciata la select, ci accorgiamo di come il nuovo record inserito esista.
Forzando il ROLLBACK della Transazione, il record inserito sparisce, riportando il database allo stato inziale, come se noi non avessimo effettuato nessun tipo di operazione.
Questo dimostra come pur non avendo dichiarato esplicitamente l’avvio della Transazione, siamo in grado di controllarne il flusso tramite le istruzioni ROLLBACK e COMMIT.
Un’altra piccola nota : nel momento in cui viene effettuata una ROLLBACK o una COMMIT sulla Transazione di default, ne viene subito avviata una nuova, a sottolineare come ogni operazione sul database viene obbligatoriamente associata ad una Transazione. E’ questo lo stesso motivo per cui rimanendo nell’ambiente isql possiamo continuare a lanciare ROLLBACK o COMMIT a rotazione pur non effettuando nessun tipo di operazione : queste istruzioni chiuderanno la Transazione di default e Firebird sistematicamente ne creerà una nuova.

Riquadro 2 : Gli argomenti di ibase_trans

La scelta del parametro trans_args passabile alla funzione ibase_trans va effettuata tra questi valori predefiniti :

  • IBASE_DEFAULT
  • IBASE_READ
  • IBASE_WRITE
  • IBASE_COMMITTED
  • IBASE_CONSISTENCY
  • IBASE_CONCURRENCY
  • IBASE_REC_VERSION
  • IBASE_REC_NO_VERSION
  • IBASE_WAIT
  • IBASE_NOWAIT

Ciascuno di questi guida uno specifico comportamento della Transazione.
Purtroppo non esiste nemmeno sul sito ufficiale di PHP una spiegazione specifica su ciascuna singola voce, solo alcune (le più usate) sono abbastanza autoesplicative.
Indicando IBASE_DEFAULT ad esempio, si avvia una Transazione le cui proprietà sono quelle di default ossia access mode READ ONLY, lock resolution NO WAIT ed isolation level SNAPHOT.
Nell’attesa che il supporto di PHP da questo punto di vista migliori, è necessario sperimentare in ambiente di prova le opzioni che si vogliono utilizzare in modo da non incorrere in spiacevoli inconvenienti.

Riquadro 3 : Test con ROLLBACK e COMMIT

<html>
<body>
 
<?php  
 // Inclusione file ib_class 
 include("ib_class.inc"); 
 
 // Creazione classe Ibase_DB 
 $db = new ib_class("localhost", "/home/janet/dbtest.gdb", "", 0, 3, "SYSDBA", "masterkey"); 
 
 switch ($_POST["selection"]) {
  case "rollback" :  
   $tr_id = $db->transaction("start", IBASE_DEFAULT);
   echo ibase_errmsg();
   // Test Rollback
   $ssql = "INSERT INTO PEOPLE (pcode, pname, psurname) VALUES (?, ?, ?)";
   // Definisco i parametri
   $db->add_param(7);
   $db->add_param("Luca");
   $db->add_param("Brasi");   
   // Esecuzione query 
   if (!$db->exec_query($tr_id, $ssql)) 
    // C'e' un errore, lo visualizzo 
    echo "Si è verificato un errore : " . $db->Error;
   else
    $db->transaction("rollback", $tr_id);
   break;
 
  case "commit" :    
   $tr_id = $db->transaction("start", IBASE_DEFAULT);
   // Test Commit
   $ssql = "INSERT INTO PEOPLE (pcode, pname, psurname) VALUES (?, ?, ?)";  
   // Definisco i parametri
   $db->add_param(7);
   $db->add_param("Luca");
   $db->add_param("Brasi");   
   // Esecuzione query 
   if (!$db->exec_query($tr_id, $ssql)) 
    // C'e' un errore, lo visualizzo 
    echo "Si è verificato un errore : " . $db->Error;
   else
    $db->transaction("commit", $tr_id);
   break;
 
  case "delete": 
   // Cancello gli eventuali inserimenti
   $ssql = "DELETE FROM PEOPLE WHERE pcode = ?";  
   // Definisco i parametri
   $db->add_param(7);
   // Esecuzione query 
   if (!$db->exec_query(0, $ssql)) 
    // C'e' un errore, lo visualizzo 
    echo "Si è verificato un errore : " . $db->Error;
   break;
 
  default : break;
 } 
?>
 
<form action="<?=$_SERVER["PHP_SELF"];?>" method="post">
<input type="radio" name="selection" value="rollback">Inserisci ed effettua rollback (il record non viene inserito)
<br>
<input type="radio" name="selection" value="commit">Inserisci ed effettua commit (il record viene inserito)
<br>
<input type="radio" name="selection" value="delete">Cancella il record inserito
<br>
<input type="submit">
</form>
<p>Stato tabella :
 
<?php 
 $ssql = "SELECT a.PCODE, a.PNAME, a.PSURNAME FROM PEOPLE a ORDER BY a.PCODE"; 
 
 // Esecuzione query 
 if (!$db->exec_query(0, $ssql)) 
  // C'e' un errore, lo visualizzo 
  $db->display_error(1, $ssql); 
 else 
 {  
  echo "<table border="1">";
  // Creo le colonne della tabella
  while (list($colonna)=each($db->Fields_Info))
   echo "<th>" . $db->Fields_Info[$colonna]["alias"] . "</th>";
  // Creo le righe della tabella
  while ($db->next_record())
  {
   echo "<tr>";
   for ($fld = 0; $fld < $db->Num_Fields; $fld++)
    echo "<td>" . $db->Record[$db->Fields_Info[$fld]["alias"]] . "</td>";
   echo "</tr>";
  }
  echo "</table>";
 }
?>
 
</body> 
</html>

Allegati

Il file relativo alla classe a questo indirizzo : ib_class.inc.

La serie comprende questi articoli :

Una classe PHP per l’accesso a Firebird – Parte 1: costruzione della classe e implementazione dei metodi base
Una classe PHP per l’accesso a Firebird – Parte 2: Gestione dei campi BLOB
Una classe PHP per l’accesso a Firebird – Parte 3: Gestione delle Transazioni

Nota :

Questo articolo è originariamente apparso nell’edizione italiana di Linux Journal nel Dicembre 2004/Gennaio 2005.

]]> http://www.miamammausalinux.org/2004/12/una-classe-php-per-accesso-a-firebird-parte-3/feed/ 0 Una classe PHP per l’accesso a Firebird – Parte 2: Gestione dei campi BLOB http://www.miamammausalinux.org/2004/11/una-classe-php-per-accesso-a-firebird-parte-2/ http://www.miamammausalinux.org/2004/11/una-classe-php-per-accesso-a-firebird-parte-2/#comments Mon, 01 Nov 2004 12:00:07 +0000 Raoul Scarazzini http://localhost/miamammausalinux.org/?p=66 firebird    php

Nello scorso articolo abbiamo iniziato a costruire una classe PHP per l’accesso ad un database Firebird. Sulla base di proprietà e metodi specifici abbiamo inziato ad effettuare query ed a navigare nei resultset di queste.
Quello che ci apprestiamo a fare ora è entrare nello specifico, costruendo metodi che ci permettano di gestire un tipo di campo particolare denominato BLOB.
Quanto segue si basa totalmente sulla classe presentata e costruita nello scorso articolo, senza quella base i nuovi metodi implementati non hanno senso.

Panoramica sui campi BLOB

In genere quando si definisce un campo in una tabella bisogna sapere a priori quale dovrà essere la sua dimensione massima. Molte volte però non è possibile stabilire a priori quanti dati dovrà contenere un campo, basti pensare alle note di un’ordine : come si può stabilire quanto un cliente scriverà all’interno di queste ? La risposta si trova appunto nei campi BLOB.
Un campo BLOB a differenza di tutte le altre tipologie definibili in un RDBMS ha la caratteristica di essere dimensionato dinamicamente, non viene definita cioè la grandezza del campo in fase di creazione.
In genere campi di questo tipo vengono utilizzati per gestire grandi quantità di dati di grandezza varibile : Immagini bitmap, file audio, file video, capitoli di libri e tantissime altre tipologie.
Proprio a causa di questa particolare attitudine, i campi BLOB non si possono gestire in maniera “comune” tramite operazioni di SELECT o INSERT, ma necessitano di misure particolari sia per la scrittura che per la lettura. Questo perchè non viene registrato direttamente il contenuto del campo all’interno della tabella, ma solo il suo identificativo, il BLOB_ID. I dati del BLOB vengono registrati in un’altra area del database, suddivisi in segmenti. Il BLOB_ID rappresenta l’indirizzo di partenza di questi segmenti.
Questo concetto è spiegato egregiamente in Figura 1.

Figura 1

Figura 1

Definire un campo BLOB

In Firebird la definizione di un campo BLOB all’interno di una tabella avviene in questo modo :

NOMECAMPO BLOB SUB_TYPE <tipo subtype> SEGMENT SIZE <grandezza>

Questo tipo di sintassi ci permette di dichiarare il nome del campo, il fatto che sia di tipo BLOB, il sottotipo (SUB_TYPE) e la grandezza dei sagmenti ad esso associati (SEGMENT SIZE).
SUB_TYPE rappresenta il sotto-tipo del campo, un valore che descrive la natura del dato in esso contenuto. In firebird ne esistono 9 tipi (da 0 a 8) :

  • 0
  • 1 o TEXT
  • 2 o BLR
  • 3 o ACL
  • 4 o RANGES
  • 5 o SUMMARY
  • 6 o FORMAT
  • 7 o TRANSACTION_DESCRIPTION
  • 8 o EXTERNAL_FILE_DESCRIPTOR :

Una spiegazione completa di ciascuno di questi particolari sottotipi la si può trovare a questo URL :
http://www.ibphoenix.com/a502.htm
per i nostri esempi noi adotteremo il subtipo TEXT, usato appunto per registrare e manipolare testo. Se non si è certi di quale tipo scegliere, si può non indicare nulla in quanto di default verrà considerato il sottotipo 0 che generalmente viene usato per dati binari o indefiniti.
SEGMENT SIZE rappresenta la grandezza massima che i segmenti del campo BLOB possono assumere. Il valore indicato può arrivare fino a 32767 bytes. Se non si indica il valore di grandezza del segmento, Firebird considera default SEGMENT SIZE 80.
Anche in questo caso sarebbe bene approfondire il concetto di SEGMENT SIZE sulla documentazione ufficiale di Interbase 6.0 nel pdf denominato DataDef.pdf, pagine relative ai campi BLOB (Le pagine dalla 76 in poi). Questa documentazione pur riferendosi ad una versione di Interbase passata (la prima ed unica OpenSource, 6.0) si adatta per i concetti esposti anche a Firebird. La sipuò trovare sul sito ufficiale di Firebird a questo indirizzo :
http://firebird.sourceforge.net/index.php?op=doc&id=userdoc
scaricare e consultare questa documentazione non è affatto un lavoro in utile, in particolare, relativamente ai campi BLOB, il capitolo 8 del libro “EMBEDDED SQL GUIDE”.
Seppur datata risulta in diverse occasioni assai preziosa. .

Prepararsi al lavoro

Nello scorso articolo avevamo già definito nel database di test una tabella con un campo BLOB :

CREATE TABLE PEOPLE (
    pcode    INTEGER NOT NULL,
    psurname VARCHAR(30) NOT NULL,
    pname    VARCHAR(30) NOT NULL,
    pquote   BLOB SUB_TYPE TEXT SEGMENT SIZE 240,   
    PRIMARY KEY (pcode)
);

La riga che a noi interessa è chiaramente quella contenente la dichiarazione del campo BLOB :

    pquote   BLOB SUB_TYPE TEXT SEGMENT SIZE 240,

Questa segnala a Firebird di creare un campo BLOB di sottotipo TEXT (quello che ci interessa memorizzare sono frasi “memorabili”, quindi essenzialmente testo) con segmenti di 240 bytes.
Questo campo ci permetterà di sperimentare le funzioni PHP per la gestione dei BLOB in Firebird.

Utilizzare i campi BLOB in PHP

Ciò che ci interessa implementare nella nostra classe PHP relativamente ai campi BLOB, sono le due operazioni fondamentali : lettura e scrittura.
Come già accennato precedentemente, per reperire un campo BLOB da una tabella non è sufficente effettuare una SELECT su questo e scriverne il contenuto in output semplicemente con una echo, come se si trattasse di un campo qualsiasi (ad esempio VARCHAR).
Se si dovesse procedere in questa maniera, non si riceverebbe alcun errore dal compilatore PHP, ma a video non apparirebbe il testo contenuto nel BLOB, bensì il suo ID, il quale apparendo in forma binaria risulterebbe del tutto incomprensibile.
Quindi procedendo correttamente i passi da svolgere per reperire il contenuto di un campo BLOB diventano i seguenti :

  • Ricavare tramite SELECT il BLOB_ID del campo interessato;
  • Aprire l’area di memoria del database identificata dal BLOB_ID;
  • Reperire il contenuto del BLOB da quest’area per elaborarlo secondo le nostre esigenze;
  • Chiudere l’area di memoria in questione.

Lo stesso concetto va applicato (anche se in maniera opposta) all’inserimento, i cui passi possono essere rappresentati come segue :

  • Creare un’area di memoria nel database;
  • Inserire in questa i valori relativi al contenuto (Testo o dati binari relativi ad immagini, video etc.);
  • Registrare l’ID di quest’area di memoria nel campo BLOB della tabella;
  • Chiudere l’area di memoria.

Per effettuare queste due serie di operazioni creeremo due metodi dal nome autoesplicativo : blob_field_in e blob_field_out.

PHP offre le funzioni di gestione dei campi BLOB in Interbase/Firebird, ma purtroppo sul sito ufficiale queste non sono documentate, poco male se si pensa che fino a pocotempo fa non erano nemmeno menzionate !
Un elenco completo delle funzioni disponibili lo si trova qui :
http://it2.php.net/manual/it/ref.ibase.php

Reperire valori da un campo BLOB

Dettati i presupposti possiamo inziare a creare un metodo che visualizzi il contenuto di un campo BLOB ricavato dal resultset di una query.
I parametri di cui il nostro metodo avrà bisogno saranno sicuramente il nome del campo interessato ed il formato di uscita dei dati, in modo da poter effettuare una pre-elaborazione dell’output e velocizzare i tempi di lavorazione.
Partendo dal presupposto che tramite il metodo exec_query (illustrato nel precedente articolo) abbiamo nell’array Record della nostra classe una riga del resultset della query effettuata, possiamo iniziare a concentrarci sui metodi PHP :
Per prima cosa è necessario reperire il BLOB_ID del nostro campo, la prima funzione che viene in nostro aiuto è ibase_blob_open : a questa va passato semplicemente il valore binario ricavato dalla query per farsi restituire il BLOB_ID relativo. Ora che conosciamo qual’è l’indirizzo di memoria dei dati che ci interessano, possiamo iniziare a reperirli tramite la funzione ibase_blob_get. A questa è necessario passare chiaramente il BLOB_ID ed in più la lunghezza in byte di quanti dati si vogliono reperire. La funzione restituirà tanti byte quanti ne sono stati richiesti fino a che non arriverà alla fine del campo, momento in cui il valore restituito diventerà FALSE.
Essendo il valore BLOB diviso in segmenti e non sapendo a priori la grandezza di questi, per effettuare un reperimento preciso useremo un comodo espediente : generiamo un numero casuale tramite la funzione rand e utilizziamo come lunghezza di byte il resto della divisione tra questo numero e 1024. Questo numero non potrà mai superare 1024, di conseguenza ci consentirà di reperire aree dati minori di 1024 bytes (1 Kb).
Seppur questo step possa sembrare superfluo (si potrebbe passare un valore fisso inferiore a 1024 sempre e comunque) è necessario e fondamentale per non sovraccaricare la memoria durante le operazioni di reperimento di grosse moli di dati da campi BLOB…Provare per credere !
Accodando i vari “pezzi” del nostro BLOB in una variabile potremmo finalmente avere in locale i dati che ci interessano ed operare su di essi per emetterli a seconda del formato d’uscita richiesto.
Una volta che quanto ci interessa si trova in una variabile locale, possiamo chiudere il BLOB attraverso la funzione ibase_blob_close alla quale va passato solo il BLOB_ID interessato.
I formati d’uscita potrebbero essere 3 : restituire il dato così come lo si riceve, restituire il dato con i caratteri speciali html convertiti in “escape sequences” per prevenire l’esecuzione di codice html o anche javascript maligno ed infine restituire il dato formattato per l’html (quindi con gli “accapo” trasformati in tag
), ma sempre con il discorso sicurezza applicato ai caratteri speciali html.
In conclusione il nostro metodo potrebbe presentarsi così :

function blob_field_out($field_name, $html)
{
 $blob_text = "";
 if ($this->Record[$field_name])
 {
  $blob_id = ibase_blob_open($this->Record[$field_name]);
  while ($piece = ibase_blob_get ($blob_id, rand() % 1024))
   $blob_text .= $piece;
  ibase_blob_close($blob_id);
  switch ($html) 
  {
   case "s" : break;
   case 0 || NULL || FALSE : $blob_text = htmlspecialchars($blob_text); break;
   default : $blob_text = nl2br(htmlspecialchars($blob_text)); break;
  }
 }
 return $blob_text;
}

Tutta la funzione dipende comunque dal fatto che $this->Record[$field_name] sia valorizzato, in caso contrario il valore restituito sarà una stringa vuota.
Il ciclo while serve per accodare i valori reperiti dal campo BLOB all’interno della variabile $blob_text e fino a che verrà assegnato un valore a $piece, $blob_text continuerà ad incrementarsi.
Il costrutto switch ci consente invece di selezionare il tipo di formato output : passando quindi “s” come secondo parametro al nostro metodo, considereremo il contenuto del BLOB affidabile e così come ci viene restituito, se invece questo non sarà valorizzato (0, NULL o FALSE) restituiremo il tutto “corretto” da eventuali entità html (la funzione htmlspecialchars non fa altro che questo), mentre se il parametro $html un valore qualsiasi diverso da questi oltre ad effettuare un controllo sulle entità html convertiremo anche i caratteri “n” o newline in accapo html ossia “<br>”.

Inserire valori in un campo BLOB

Inserire dei valori BLOB all’interno di una tabella significa creare un’area di memoria all’interno del database, scrivere in questa i dati che ci interessano, registrare il BLOB_ID associato nella tabella interessata e chiudere l’area di memoria aperta.
Il nostro metodo dovrà richiedere in input due parametri : il primo è il database handle, che rappresenterà l’indirizzo relativo alla connessione sulla quale stiamo lavorando, il secondo conterrà i dati da inserire nel campo BLOB.
Tramite il metodo PHP ibase_blob_create al quale va passato l’handle del nostro database reperiremo il BLOB_ID relativo ad una nuova area di memoria creata. Questo prezioso valore ci consentirà di inserire dati all’interno di quest’area tramite la funzione ibase_blob_add alla quale passeremo il BLOB_ID e la variabile contenente i dati da registrare. Infine faremo restituire al nostro metodo quanto riceveremo dalla funzione ibase_blob_close , ossia il BLOB_ID da registrare all’interno del campo della tabella.

function blob_field_in($dbh == NULL, $blob_text)
{
 if (!is_null($dbh) && is_resource($dbh))
  $this->Link_ID = $dbh;
 else
  $this->connect();
 
 $blob_id = ibase_blob_create($this->Link_ID);
 ibase_blob_add($blob_id, $blob_text);
 return ibase_blob_close($blob_id);
}

Se $dbh è valorizzato (non deve essere nullo e deve essere una risorsa), allora verrà usato questo handle per svolgere le operazioni, in caso contrario verrà richiamata la funzione connect.

Dalla teoria alla pratica

Una volta aggiunti questi due nuovi metodi alla nostra classe, possiamo procedere con la creazione di un esempio effettivo di inserimento di un record contenente un BLOB e la visualizzazione di questo.
Il codice contenuto nel Riquadro 1 riassume tutti i concetti esposti sinora.
Si parte con l’inclusione del file classe, la creazione di questa mediante il suo costruttore, e si inserisce tramite i parametri il nuovo record all’interno della tabella.
Particolare attenzione va posta alla riga

 $db->add_param($db->blob_field_in(0, $blob));

che aggiunge alla lista dei parametri anche il BLOB_ID ricavato dalla funzione blob_field_in che ci siamo costruiti, a questa vengono passati due parametri : 0 che rappresenta una connessione vuota ed obbliga quindi la funzione a stabilirne una nuova e $blob ossia la variabile che contiene il testo (con accapo) da inserire nel nostro BLOB.
Una volta eseguito con successo l’inserimento vengono proposti i due tipi di visualizzazione del risultato : nel primo il campo viene presentato così come è estratto dalla tabella, e come si può vedere dalla Figura 2, ciò che appare è assolutamente incomprensibile, nel secondo grazie alla riga

    echo "<td>" . $db->blob_field_out("PQUOTE", 1) . "</td>";

Viene visualizzato il risultato corretto (Figura 3), ossia quanto restituito dalla funzione blob_field_out, alla quale abbiamo passato il nome del campo interessato “PQUOTE” e 1 per indicare di convertire gli accapo in “<br>”.

Figura 2

Figura 2

Figura 3

Figura 3

Conclusioni

Ancora una volta ci tengo ad indicare come l’implementazione di tutti i metodi presentati è puramente indicativa. Si può fare tutto e più di tutto con questi strumenti che l’OpenSource ci mette a disposizione, questa è solo una delle tante vie.
In questo secondo articolo abbiamo cercato di capire il concetto di BLOB e di implementare metodi che ne consentano l’utilizzo, nel prossimo parleremo di transazioni, cercando anche in questo caso di creare metodi specifici che ci consentano di lavorare al meglio spremendo Firebird fino all’ultimo bit.

Riquadro 1 : Inserimento di un campo BLOB, visualizzazione scorretta e corretta

<html>
<body>
<?php
 // Inclusione file ib_class
 include("ib_class.inc");
 
 // Creazione classe db
 $db = new ib_class("localhost", "/home/janet/dbtest.gdb", "", 0, 3, "SYSDBA", "masterkey");
 
 // Inserimento BLOB
 
 // Stringa sql
 $ssql = "INSERT INTO PEOPLE (PCODE, PNAME, PSURNAME, PQUOTE)  VALUES (?, ?, ?, ?)";
 
 // Definizione variabile BLOB (con caratteri accapo)
 $blob = "It made me think of what you once told me:n"In five years the Corleone family will be completely legitimate."n
That was seven years ago.";
 
 // Passaggio parametri
 $db->add_param(6);
 $db->add_param("Kay");
 $db->add_param("Adams Corleone");
 $db->add_param($db->blob_field_in(0, $blob));
 
 // Esecuzione query
 if (!$db->exec_query(0, $ssql))
  // C'e' un errore, lo visualizzo
  echo "Si è verificato un errore : " . $db->Error;
 else
 {
  echo "Inserimento blob completato con successo !<p>";
 
  // Stringa sql
  $ssql = "SELECT a.PNAME, a.PQUOTE FROM PEOPLE a";
 
  // Visualizzazione senza utilizzo di blob_field_out
  echo "<p><i>Senza <b>blob_field_out</b></i><br>";
 
  // Esecuzione query
  if (!$db->exec_query(0, $ssql))
   // C'e' un errore, lo visualizzo
   echo "Si è verificato un errore : " . $db->Error;
  else
  {
   echo "<table border="1">n";
   echo "<th>Nome</th><th>Frase memorabile</th>n";
 
   // Creo le righe della tabella
   while ($db->next_record())
   {
    echo "<tr>";
    echo "<td>" . $db->Record["PNAME"] . "</td>";
    echo "<td>" . $db->Record["PQUOTE"] . "</td>";
    echo "</tr>n";
   }
   echo "</table>";
  }
 
  // Visualizzazione con blob_field_out
  echo "<p>Con <i><b>blob_field_out</b></i><br>";
 
  // Esecuzione query
  if (!$db->exec_query(0, $ssql))
   // C'e' un errore, lo visualizzo
   echo "Si è verificato un errore : " . $db->Error;
  else
  {
   echo "<table border="1">n";
   echo "<th>Nome</th><th>Frase memorabile</th>n";
 
   // Creo le righe della tabella
   while ($db->next_record())
   {
    echo "<tr>";
    echo "<td>" . $db->Record["PNAME"] . "</td>";
    echo "<td>" . $db->blob_field_out("PQUOTE", 1) . "</td>";
    echo "</tr>n";
   }
   echo "</table>";
  }
 }
?>
</body>
</html>

Allegati

Il file relativo alla classe a questo indirizzo : ib_class.inc.

La serie comprende questi articoli :

Una classe PHP per l’accesso a Firebird – Parte 1: costruzione della classe e implementazione dei metodi base
Una classe PHP per l’accesso a Firebird – Parte 2: Gestione dei campi BLOB
Una classe PHP per l’accesso a Firebird – Parte 3: Gestione delle Transazioni

Nota :

Questo articolo è originariamente apparso nell’edizione italiana di Linux Journal nel Novembre 2004.

]]> http://www.miamammausalinux.org/2004/11/una-classe-php-per-accesso-a-firebird-parte-2/feed/ 0 Una classe PHP per l’accesso a Firebird – Parte 1: costruzione della classe e implementazione dei metodi base http://www.miamammausalinux.org/2004/10/una-classe-php-per-accesso-a-firebird-parte-1/ http://www.miamammausalinux.org/2004/10/una-classe-php-per-accesso-a-firebird-parte-1/#comments Fri, 01 Oct 2004 11:30:44 +0000 Raoul Scarazzini http://localhost/miamammausalinux.org/?p=56 firebird    php

Nell’esteso panorama degli RDBMS (Relational Database Management System) si sta pian piano ritagliando una fetta di mercato un progetto giovane, ma già molto maturo : Firebird.
Nato da una costola del più famoso Interbase della Borland, FireBird rappresenta un’ottimo punto di partenza per quanti vogliono impementare soluzioni database stabili ed efficenti.
Cercheremo in questa serie di articoli di imparare ad accedere a questo motore per database da PHP, costruendo, sulla base della programmazione ad oggetti, una classe di accesso personalizzata che chiameremo ib_class.
L’ideale, per essere subito operativi, è che nel sistema su cui si lavorerà ci sia installato il motore per database Firebird (la versione attuale e consigliata è la 1.0.3), un webserver (per esempio Apache, 1.3.x o 2.x è indifferente) che supporti Php (4.3.x) e che lo stesso PHP sia compilato con supporto Interbase (e quindi Firebird).

Prima di iniziare

Quella che segue è una breve panoramica su ciò che è la programmazione ad oggetti, su ciò che sono le classi, e su come vengono implementate ed utilizzate in PHP. Essendo l’obiettivo primario di questo articolo creare una classe PHP specifica, se si desidera approfondire gli argomenti in questione si può far riferimento al testo “Object Oriented Programming – Guida completa” edito da Apogeo per quanto riguarda lo studio della programmazione ad oggetti, mentre all’indirizzo http://it.php.net/oop per trovare spiegazioni ed esempi inerenti la programmazione ad oggetti in PHP.
Inoltre non dimentichiamoci mai del buon vecchio google (www.google.com) per effettuare qualsiasi tipo di ricerca tecnica.

OOP : Object Oriented Programming.

I concetti di classe ed oggetto (o istanza) sono alla base della programmazione ad oggetti (OOP, Object Oriented Programming). Una classe rappresenta l’astrazione di un oggetto mentre un oggetto è istanza di una classe : Creare un oggetto significa istanziare una classe.
Una struttura dati è definita classe quando racchiude in se delle variabili (denominate proprietà o attributi) e le funzioni per la manipolazione di queste (denominate metodi).
E’ importante che la struttura dati di una classe sia trasparente per chi la utilizza : si opererà su questa solo tramite i metodi in essa definiti, quindi sarà necessario conoscere come questi operano e quale è la loro funzione, non come sono stati implementati. In questo modo si garantisce che la classe diventi fruibile non solo da chi l’ha costruita, bensì da tutti coloro che conoscono come questa funziona e cosa fa.

Panoramica sulle classi in PHP.

PHP è un linguaggio procedurale che però supporta il paradigma della programmazione orientata agli oggetti, proprio per questo possiede una serie di parole chiave necessarie ad implementare classi.
Una classe in PHP viene creata tramite la parola chiave class e nel corpo della sua dichiarazione si trovano tutte le variabili (proprietà) e le funzioni (metodi) che ne descrivono l’implementazione.
Le proprietà di una classe vengono dichiarate tramite la parola chiave var mentre per i metodi viene usata la parola chiave function.
Per poter accedere alle funzioni e alle variabili interne di una classe, viene usata la pseudo-variabile $this. Questo perchè, in fase di progettazione, non si conosce il nome con cui la classe verrà istanziata all’interno dei vari programmi. Questa pseudo-variabile può essere quindi letta come “questo oggetto”, this appunto.
Per scorrere proprietà e metodi di un oggetto viene usato l’operatore “->” che consente, un pò come succede nello scorrimento delle directory tramite l’operatore “/” di reperire un valore associato ad un percorso : se volessi accedere al file file.txt sotto la cartella /files dovrei far riferimento a questo così : /files/file.txt, negli oggetti la sintassi per accedere ai dati richiama questo concetto : $this->nomeproprietà per le proprietà e $this->nomemetodo() per i metodi.
E’ da notare come la variabile si chiami $this->nomeproprietà, e non $this->$nomeproprietà, pur essendo questa dichiarata come var $nomeproprietà : ciò accade perchè le variabili in PHP vanno scritte con un unico simbolo dollaro.
Come ultima cosa è necessario far notare che, al di fuori della classe stessa, non è mai buona norma assegnare dei valori alle prioprietà di un oggetto, è molto meglio creare dei metodi che effettuino questi assegnamenti.
In PHP 5 è stato introdotto un sistema per evitare che le proprietà di un oggetto vengano modificate all’esterno di questo : dichiarando una variabile con la parola chiave private anzichè var.
Visto che implementeremo la nostra classe con la versione 4 di PHP, per il momento consideriamo quanto detto solo a livello teorico, cercando di non assegnare direttamente i valori alle proprietà.

Il costruttore, questo sconosciuto

Se tra i metodi dichiarati all’interno di una classe ne esiste uno con il nome uguale a questa, esso viene chiamato costruttore. Il costruttore viene invocato ogni volta che un’istanza della classe viene creata ed ha il compito di inizializzare le proprietà del nucoo oggetto. In PHP ciò avviene tramite la parola chiave new :
$nomeoggetto = new nomeclasse();
Se non esiste un costruttore, new istanzierà solamente la classe e sarà necessario che ogni parametro abbia dei valori di default.
Una volta creato l’oggetto, le proprietà di questo saranno accessibili in questo modo $nomeoggetto->nomeproprietà ed i metodi con $nomeoggetto->nomemetodo()
Non è obbligatorio avere un costruttore all’interno di una classe, ma questo metodo è talmente utile da non poterne fare a meno.
Per creare una classe che si rispetti quindi, si fa presto a capire come il primo metodo da implementare sia il costruttore.

Prepariamoci al lavoro

Ora che abbiamo introdotto tutti gli argomenti che tratteremo nel corso dell’articolo, siamo pronti per iniziare a lavorare.
Si può partire analizzando quali dovranno essere le funzionalità della nostra classe in base alle operazioni che dovrà svolgere : essendo una classe per l’accesso ad un database, sicuramente dovrà consentirci di stabilire una connessione, di effettuare query sulle tabelle e di navigare all’interno dei risultati delle nostre interrogazioni. E questo solo per cominciare.
E’ facile intuire come ad ogni funzionalità indicata, dovrà corrispondere un metodo.
Ciascuno di questi metodi dovrà basarsi sulle funzioni che PHP mette a disposizione per l’accesso ad Interbase/Firebird. Un elenco completo di queste funzioni lo si può trovare sul sito ufficiale di PHP, all’indirizzo http://it.php.net/manual/it/ref.ibase.php.
Quello che dovremo fare, per iniziare, sarà realizzare quattro metodi base :
Un metodo che consenta a chi opera con la classe di istanziarla : dovremo creare cioè il costruttore, partendo dal presupposto che questo metodo dovrà inizializzare le proprietà dell’oggetto ed avere lo stesso nome della classe.
Un metodo che permetta di connettersi ad un database Firebird basato sulla funzione ibase_connect;
Un metodo che consenta di effettuare delle query. La funzione che ci verrà in aiuto a questo punto sarà ibase_query;
Un ultimo metodo che permetta di operare sui resultset delle query, di scorrere cioè all’interno dei risultati in modo da poterli presentare nei nostri programmi;
E’ chiaro che questi sono i metodi base, nella stesura di questi necessiteremo di crearne degli altri “minori”, sino ad ottenere una classe pronta per essere usata negli accessi a database Interbase/Firebird.
Per concludere, cercheremo di sviluppare un esempio che acceda ad un database di test (la cui creazione è illustrata nel riquadro1) e che sfrutti tutti i metodi sinora illustrati.
Bene, pronti ? Via !

Creiamo il file

Partendo dal presupposto che la classe si chiamerà ib_class creiamo un file denominato ib_class.inc che contenga l’intestazione della nostra classe insieme alle prime proprietà essenziali : il nome host, che identifica appunto l’Host presso il quale “alloggia” il nostro db, il percorso (path) del database insieme allo username ed alla password di accesso, il Set di caratteri, il numero di buffers ed il dialetto sql usato dal server :

<?php
 
class ib_class {
 
var $Host          = "";      // Host (anche macchina remota)
var $Database      = "";      // Database (file con path)
var $User          = "";      // Utente
var $Password      = "";      // Password
var $Charset       = "";      // Set di caratteri
var $Buffers       = 0;       // Numero di buffers
var $Dialect       = 3;       // Dialetto SQL
 
};
 
?>

Quanto sopra può essere considerato come la vera base della nostra classe. Queste proprietà non a caso rappresentano i dati da passare alla funzione ibase_connect per effettuare la connessione al database che vedremo più avanti.
Ora si può procedere con la creazione di tutti gli altri metodi (e proprietà) specifici, il risultato finale sarà quanto appare nel file ib_class.inc contenuto nel CD, ma chiaramente procedere passo per passo aiuterà a capire meglio i concetti.

Istanziare la classe tramite il costruttore

Il nostro costruttore non dovrà fare altro che assegnare i valori che gli vengono passati dal chiamante (tramite la funzione new) alle proprietà del nostro oggetto.
Il metodo dovrà dichiarare i parametri che gli devono essere passati in input (che rispecchiano le proprietà sino ad ora dichiarate della nostra classe) e tramite l’ausilio della pseudo-variabile $this effettuare dei semplici assegnamenti.
Ecco come potrebbe apparire :

function ib_class ($Host, $Database, $Charset, $Buffers, $Dialect, $User, $Password)
{
 $this->Host = $Host;
 $this->Database = $Database;
 $this->Charset = $Charset;
 $this->Buffers = $Buffers;
 $this->Dialect = $Dialect;
 $this->User = $User;
 $this->Password = $Password;
}

Un esempio di come si potrà creare un istanza del nostro oggetto in uno script è quello che segue :

$db = new ib_class("localhost", "/home/janet/dbtest.gdb", "", 0, 3, "SYSDBA", "masterkey");

In questo modo, viene istanziata la classe ib_class nella variabile $db. Essa verrà inizializzata con i valori relativi al database di test che abbiamo creato seguendo quanto spiegato nel riquado 1. L’istanza della classe (il nostro oggetto) sarà da qui in avanti rappresentata dalla variabile $db.
Piccola considerazione : è facile capire come, dichiarando $db come variabile di sessione in questo modo :

$_SESSION[“db”] = $db;

non avremo bisogno ogni qualvolta ci servirà il nostro oggetto, di reistanziare la classe script per script. Potremo garantire così, tramite la propagazione delle sessioni, di avere in ogni script il nostro oggetto istanziato correttamente. Interessante no ?

Connettersi ad un database Firebird

Ogni volta che si stabilisce una connessione con Firebird (ed in genere con tutti gli RDBMS) a questa viene assegnato un’indirizzo di memoria, il suo handle. Tutte le iterazioni con il database (query, transazioni etc.) andranno effettuate utilizzando un handle specifico.
Quello che a noi interessa ottenere è il valore relativo al link di una connessione e registrarlo nel nostro oggetto in una nuova proprietà, denominata $this->Link_ID.
La funzione PHP che consente di stabilire una connessione con un database Firebird è ibase_connect : Questa funzione necessita in input dei dati relativi al database (altro non sono che le proprietà che abbiamo già dichiarato del nostro oggetto) ed in caso di successo restituisce l’handle della connessione.
Il metodo che andremo a dichiarare semplicemente eseguirà la funzione ibase_connect con i parametri del nostro oggetto e assegnerà l’handle restituito da questa funzione alla proprietà Link_ID.
Il valore restituito dal metodo sarà vero o falso, a seconda dell’esito della funzione ibase_errmsg che a sua volta restitusce (se esiste) il testo del messaggio di errore.
A livello di codice, il nostro metodo sarà così strutturato :

function connect()
{
 $this->Link_ID = @ibase_connect(
  $this->Host . ":" .
  $this->Database,
  $this->User,
  $this->Password,
  $this->Charset,
  $this->Buffers,
  $this->Dialect,
  $this->Role);
 // Se c'è errore allora metto il messaggio in Error e ritorno FALSE
 $this->Error = ibase_errmsg();
 return ibase_errmsg() ? FALSE : TRUE;
}

ibase_connect automaticamente controlla se esiste già un link oppure ne va creato uno nuovo e lo restituisce in output. In questi termini il nostro metodo potrà essere invocato più volte di fila senza che necessariamente stabilisca per ogni esecuzione una nuova connessione. Come si può intuire, questa funzionalità favorisce il basso traffico di rete (e quindi la maggiore velocità).
Da notare il carattere “@” che precede la chiamata alla funzione ibase_connect. Questo indica al motore PHP di non visualizzare errori o warnings in uscita dalla funzione. Ciò è molto utile se si personalizza la gestione degli errori, come abbiamo fatto noi, assegnando alla nuova proprietà $this->Error del nostro oggetto il valore di uscita della funzione ibase_errmsg. In questo modo potremo decidere quando e come far apparire gli eventuali messaggi di errore, senza generare immotivati timori negli utilizzatori dei nostri programmi ;-)

Effettuare delle query

Il metodo per l’esecuzione delle query diverrà essenziale per qualsiasi operazione ci troveremo a fare. Proprio per questo è necessario porre particolare cura nella sua implementazione.
La funzione PHP da tenere come riferimento è ibase_query. Per essere eseguita con successo, questa necessita dell’handle del database e di una valida stringa sql. Se ha successo e vi sono righe nel risultato (come si ha ad esempio con le query SELECT), restituisce un identificatore di risorsa, mentre se ha successo ma non ci sono righe risultato, restituisce semplicemente TRUE. In caso di fallimento il valore restituito sarà FALSE.
Il concetto di identificatore di risorsa, non si scosta molto da quello di handle : esso rappresenta infatti la parte di memoria riservata al resultset (l’insieme dei valori risultanti da una query di tipo SELECT) generato da una query.
Il nostro metodo deve eseguire queste operazioni :
Controllo esistenza di una connessione
Esecuzione della query
Controllo esistenza di un resultset e settaggio della nuova proprietà $this->Query_ID con il valore dell’identificatore di risorsa.
Restituzione del valore “vero” o “falso” a seconda dell’esito della query.
I parametri che il nostro metodo riceverà in input saranno due : il database handle, $dbh e la stringa sql da eseguire, $query_string. E’ da notare come nella dichiarazione della variabile $dbh venga ad essa assegnato un valore di default, ciò risulterà molto utile nella verifica della validità che viene effettuata all’inizio della funzione.
Se $dbh è valorizzato (non deve essere nullo e deve essere una risorsa), allora verrà usato questo handle per svolgere le operazioni, in caso contrario verrà richiamata la funzione connect. Passare un handle diverso da quello di default, tornerà utile quando in futuro parleremo di transazioni.
Esaminiamo insieme il codice di questo metodo :

function exec_query($dbh = NULL, $query_string)
{
 if (!is_null($dbh) && is_resource($dbh))
  $this->Link_ID = $dbh;
 else
  $this->connect();
 
 array_unshift($this->Query_Params, $this->Link_ID, $query_string);
 $this->Query_ID = @call_user_func_array("ibase_query", $this->Query_Params);
 
 if ($this->Query_ID)
 {
  $this->Row = -1;
  // La query e' andata a buon fine, setto la variabile Query_Sql della classe ...
  $this->Query_Sql = $query_string;
  // ...Azzero i parametri...
  $this->Query_Params = array();
  // ...E se non e' una operazione di modifica creo i metadata
  if ((substr(strtoupper($query_string), 0, 6) != "INSERT")&&
      (substr(strtoupper($query_string), 0, 6) != "UPDATE")&&
      (substr(strtoupper($query_string), 0, 6) != "CREATE")&&
      (substr(strtoupper($query_string), 0, 6) != "DELETE"))
   $this->metadata();
 }
 
 // Se c'è errore allora metto il messaggio in Error e ritorno FALSE
 $this->Error = ibase_errmsg();
 return ibase_errmsg() ? FALSE : TRUE;
}

Dopo aver effettuato il controllo sul database handle già descritto, particolare attenzione va posta verso le due righe

 array_unshift($this->Query_Params, $this->Link_ID, $query_string);
 $this->Query_ID = @call_user_func_array("ibase_query", $this->Query_Params);

Queste fanno riferimento alla nuova proprietà $this->Query_Params del nostro oggetto, un array che contiene i parametri che la funzione ibase_queryrichiede in input.
array_unshift inserisce uno o più elementi all’inizio di un array, mentre call_user_func_array passa come parametri ad una funzione indicata i valori presenti in un array. Questo significa che se $this->Query_Params è vuota, ad ibase_query() saranno passati solamente due parametri (handle e stringa sql), mentre nel caso contrario tutti i valori presenti in $this->Query_Params verranno passati a ibase_query nell’ordine in cui sono presenti nell’array.
Per spiegare il funzionamento di queste due righe, consideriamo questa query che vuole estrarre tutti i record della tabella PEOPLE che abbiano PSURNAME uguale a “Corleone” :

$ssql = “SELECT a.* FROM PEOPLE WHERE a.PSURNAME = ?”;
ibase_query($dbh, $ssql, “Corleone”);

anzichè scrivere direttamente

$ssql = “SELECT a.* FROM PEOPLE WHERE a.PSURNAME = 'Corleone'”;
ibase_query($dbh, $ssql);

abbiamo indicato il carattere “?” al posto della stringa effettiva fra apici e nel richiamare la procedura ibase_query non abbiamo passato come parametri solamente l’hanlde e la stringa sql, ma anche “Corleone”.
Applicando questi concetti al nostro oggetto, consideriamo un nuovo metodo denominato add_param(); il cui scopo è quello di accodare i parametri all’interno dell’array $this->Query_Params :

function add_param($param)
{
 $this->Query_Params[] = $param;
}

e realizziamo l’esempio sopracitato :

$ssql = “SELECT a.* FROM PEOPLE WHERE a.PSURNAME <> ?”;
$db->add_param(“Corleone”);
$db->exec_query(0, $ssql);

Una volta eseguita la query con la funzione ibase_query, se $this->Query_ID viene valorizzato, e quindi la query ha avuto esito positivo, vengono settate le nuove proprietà $this->Row (che rappresenta il numero di riga corrente) e $this->Query_Sql (contenente il codice sql eseguito) ed infine viene azzerato l’array dei parametri.
Per concludere, se l’istruzione sql è una SELECT, viene richiamata la funzione $this->metadata() :

function metadata()
{
 $c=0;
 while ($campo = ibase_field_info($this->Query_ID,$c))
 {
  $info[$c]["name"] = $campo["name"];
  $info[$c]["alias"] = $campo["alias"];
  $info[$c]["relation"] = $campo["relation"];
  $info[$c]["length"] = $campo["length"];
  $info[$c]["type"] = $campo["type"];
  $info[$c]["index"] = $c;
  $c++;
 }
 $this->Fields_Info=$info;
 $this->Num_Fields=ibase_num_fields($this->Query_ID);
 // L'array viene anche restituito
 return $info;
}

Il cui scopo è quello di creare l’array associativo $this->Fields_Info con le proprietà dei campi della tabella risulato attraverso la funzione ibase_field_info(), la quale, richiamata per ogni campo, restituisce un array con informazioni relative a questo nella forma name, alias, relation, length e type.
$this->metadata() assegna anche alla nuova proprietà Num_Fields dell’oggetto il risultato della funzione ibase_num_fields() che restituisce il numero di campi della tabella risultato.
Infine exec_query controlla che non vi siano errori nello stesso identico sistema di connect, restituendo TRUE o FALSE a seconda del valore restituito da ibase_errmsg().

Operare sui resultset delle query

Prima di addentrarci nel primo esempio effettivo di utilizzo della nostra classe è necessario capire come fare a muoversi all’interno di un resultset restituito da una query.
La funzione PHP che ci viene in aiuto in questo caso è ibase_fetch_row. Questa funzione necessita in input dell’identificatore di risorsa relativo ad una query eseguita e restituisce un array con struttura indicecampo->valore. Il primo passo da compiere quindi è creare una proprietà di tipo array nel nostro oggetto denominata Record che servirà a contenere l’associazione restituita da ibase_fetch_row.
Ma noi vogliamo di più.
Oltre a questa associazione ne vogliamo creare un’ulteriore di tipo nomecampo->valore, in questo modo non saremo costretti a ricordarci quale sia l’indice di un campo per conoscerne il valore, basterà sapere il nome di questo ed accederci tramite Record[“nomecampo”].
Ad esempio se il primo campo di un resultset sarà denominato CHIAVE avremo due modi per accedere al suo valore : tramite l’indice campo $db->Record[0] oppure tramite il nome campo $db->Record[“CHIAVE”].
Analizziamo nel dettaglio il nostro metodo :

function next_record()
{
 if ($this->Record = ibase_fetch_row($this->Query_ID))
 {
  $this->Row += 1;
  $stat = 1;
 }
 else
 {
  if ($this->Auto_Free)
   $this->free_result();
  $stat = 0;
 }
 //Assegnazione valori Array associativo Record[“nomecampo”] = valorecampo
 $flds = $this->Num_Fields;
 for ($fld = 0; $fld < $flds; $fld++)
  $this->Record[$this->Fields_Info[$fld]["alias"]] = $this->Record[$fld];
 //ritorno stat: 1=0K, 0=nessun record & effettuato il free se c'è auto_free
 return $stat;
}

La proprietà dell’oggetto Row (che rappresenta il numero di riga corrente) viene incrementata fino a che l’assegnazione $this->Record = ibase_fetch_row($this->Query_ID) produce esito positivo.
L’associazione Record[“nomecampo”]->valore, viene creata partendo dalla proprietà $this->Fields_Info[$fld]["alias"] che è stata valorizzata dal metodo $this->metadata() in exec_query();
Ciclando sul numero di campi del resultset ($this->Num_Fields), aggiunge un elemento all’array record che ha per chiave il nome del campo e per valore quello relativo all’indice di questo.
next_record restituirà 1 fino a che non si troverà sull’ultimo record, momento in cui la variabile $stat (e quindi il valore restituito dal metodo) sarà 0. A questo punto verrà effettuato un check anche sulla nuova proprietà $this->Auto_Free, se questa è valorizzata, allora verrà lanciato il metodo $this->free_result() :

function free_result()
{
 ibase_free_result($this->Query_ID);
 $this->Query_ID = 0;
}

Questo metodo funziona sulla base della funzione ibase_free_result, che libera la memoria allocata da un resultset.

Mettiamo in pratica

L’esempio contenuto nel riquadro 2 contiene tutti gli argomenti che abbiamo trattato sin’ora : Una volta incluso il file “ib_class.inc” contenente il codice della nostra classe si procede con la creazione di una sua istanza nella variabile $db.
La fase successiva prevede la dichiarazione della stringa contenente il codice SQL che vogliamo far eseguire. In questo caso si tratta di voler estrarre dalla tabella PEOPLE tutte le persone che hanno un cognome (PSURNAME) contenente la parola “Corleone” indipendentemente dalle maiuscole o minuscole.
A questo punto viene aggiunto il parametro stringa di confronto e viene eseguita la query.
Da notare come l’if sia impostato direttamente sull’esito della query. Se la query non va a buon fine, viene visualizzato il testo dell’errore mentre in caso di successo viene creata una tabella con i risultati visualizzati.
Prima verranno stampate con un ciclo while le colonne <th> della tabella utilizzando l’array $db->Fields_Info che è stato creato da $this->metadata in $db->exec_query, infine lo script ciclerà sulla funzione $db->next_record fino a che questa restituirà un valore effettivo (cioè fino a che non arriverà alla fine dell’elenco) visualizzando il valore di ciascun campo in una cella.
L’output effettivo di questo script non dovrebbe essere troppo diverso da quello presentato nella figura 1.

Figura 1

Figura 1

Conclusioni

Chiaramente l’implementazione di tutti i metodi dell’oggetto è puramente indicativa. Ciascuno di essi infatti può essere modificato ed ottimizzato in funzione delle proprie specifiche esigenze. Una personalizzazione mirata è alla base dello sviluppo di un buon progetto.
In questo primo articolo abbiamo realizzato la base per la nostra classe di accesso, nei successivi implementeremo nuovi metodi per renderla più completa possibile : introdurremo metodi specifici per la gestione dei campi Blob, delle transazioni e per tutte le varie tipologie di campi.

Riquadro 1 : Creazione ambiente di test

Prima di iniziare a fare i test con gli script PHP e la nostra classe e’ necessario creare un database di prova, sul quale poter combinare tutti i possibili danni di cui siamo capaci senza nuocere a nessuno…
Assumiamo come directory di lavoro /home/janet e creiamo un file denominato dbtest.sql con il nostro editor di testo preferito :

vi /home/janet/dbtest_create.sql

scrivendoci all’interno i dati per la creazione del nostro db :

SET SQL DIALECT 3;
 
CREATE DATABASE 'localhost:/home/janet/dbtest.gdb'  USER 'SYSDBA' PASSWORD 'masterkey';
 
CREATE TABLE PEOPLE (
    pcode    INTEGER NOT NULL,
    psurname VARCHAR(30) NOT NULL,
    pname    VARCHAR(30) NOT NULL,
    pquote   BLOB SUB_TYPE TEXT SEGMENT SIZE 240,   
    PRIMARY KEY (pcode)
);
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (0, 'Corleone', 'Vito', 'I''ll make him an offer he can''t refuse.');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (1, 'Corleone', 'Michael', 'Don''t ask me about my business, Kay.');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (2, 'Corleone', 'Sonny', 'Goddamn FBI don''t respect nothin''.');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (3, 'Corleone', 'Fredo', 'I''m smart and I want respect !');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (4, 'Hagen', 'Tom', 'Mr. Corleone never asks a second favor once he''s refused the first, understood ?');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (5, 'Clemenza', 'Peter', 'Mikey, why don''t you tell that nice girl you love her ?');
 
COMMIT;

Una volta scritto quanto sopra, salviamo il file e lanciamo questo comando come utente root :

/opt/interbase/bin/isql -i /home/janet/dbtest_create.sql

Se non riceviamo messaggi di errore, dovremmo trovarci nella directory /home/janet il nostro file dbtest.gdb pronto da usare.

Riquadro 2 : il primo script con la nostra classe

<html>
<body>
<?php 
 // Inclusione file ib_class 
 include("ib_class.inc"); 
 
 // Creazione classe db 
 $db = new ib_class("localhost", "/home/janet/dbtest.gdb", "", 0, 3, "SYSDBA", "masterkey"); 
 
 // Stringa sql
 $ssql = "SELECT a.PSURNAME, a.PNAME FROM PEOPLE a WHERE upper(a.PSURNAME) LIKE upper(?)"; 
 
 // Aggiungo il parametro
 
 $db->add_param("%Corleone%");
 
 // Esecuzione query 
 if (!$db->exec_query(0, $ssql)) 
  // C'e' un errore, lo visualizzo 
  echo "Si è verificato un errore : " . $db->Error; 
 else 
 { 
  echo "<table border="1">";
 
  // Creo le colonne della tabella
  while (list($colonna)=each($db->Fields_Info))
   echo "<th>" . $db->Fields_Info[$colonna]["alias"] . "</th>";
 
 
 
  // Creo le righe della tabella
  while ($db->next_record()) 
  {
   echo "<tr>";
   for ($fld = 0; $fld < $db->Num_Fields; $fld++)
    echo "<td>" . $db->Record[$fld] . "</td>";
   echo "</tr>";
  }
  echo "</table>";
 }  
?>
</body>
</html>

Allegati

Il file relativo alla classe a questo indirizzo : ib_class.inc.

La serie comprende questi articoli :

Una classe PHP per l’accesso a Firebird – Parte 1: costruzione della classe e implementazione dei metodi base
Una classe PHP per l’accesso a Firebird – Parte 2: Gestione dei campi BLOB
Una classe PHP per l’accesso a Firebird – Parte 3: Gestione delle Transazioni

Nota :

Questo articolo è originariamente apparso nell’edizione italiana di Linux Journal nel Ottobre 2004.

]]> http://www.miamammausalinux.org/2004/10/una-classe-php-per-accesso-a-firebird-parte-1/feed/ 2