Automatická změna struktury databáze

FreenetIS obsahuje mechanismus pro automatickou změnu struktury databáze. Tyto změny jsou provedeny po spuštění FreenetISu (po otevření v prohlížeči) po jeho aktualizaci (zde nezáleží, zda-li se jedná o aktualizace skrze balíčkovací systém, nebo z vývojářského repozitáře). Provedené změny nelze zrušit, což znamená, že snížení verze (downgrade) FreenetISu není možné (tento jev lze samozřejmě odstranit manuální změnou databáze ze zálohy, při které ovšem nejsme schopni zaručit správnost výsledného stavu sytému).

Mechanismus pro aktualizaci je úzce spjat s verzováním FreenetISu. Ve složce /db_upgrades se nachází soubory se změnami pro jednotlivé verze FreenetISu. Jména souborů jsou ve formátu upgrade_sql_VERZE.php, kde VERZE je nahrazena verzí FreenetISu. Soubory samotné musí obsahovat položku pole $upgrade_sql s indexem daným verzí FreenetISu. Tato položka obsahuje pole SQL příkazů, které jsou postupně spuštěny. Dále může obsahovat PHP funkce spouštěné před a po provedení SQL příkazů, které jsou používané pokud např. nelze data databáze převést mezi jednotlivými verzemi přímo pomocí SQL příkazů. Obě funkce mohou obsahovat libovolné PHP příkazy a musí vracet pravdivostní hodnotu (boolean).

Příklad souboru se změnami:

<?php defined('SYSPATH') or die('No direct script access.');
/*
 * This file is part of open source system FreeNetIS
 * and it is released under GPLv3 licence.
 * 
 * More info about licence can be found:
 * http://www.gnu.org/licenses/gpl-3.0.html
 * 
 * More info about project can be found:
 * http://www.freenetis.org/
 * 
 */

/** This upgrade is equal to one in 1.0.0~beta2 developer revision */
$upgrade_equal_to['1.0.0~rc1'] = '1.0.0~beta2'; 

function upgrade_1_0_0_rc1_before()
{
	echo "Some PHP code triggered before processing of all SQL commands"
	return TRUE;
}

$upgrade_sql['0.9.9~rc'] = array
(
	"ALTER TABLE `ifaces` CHANGE `device_id` `device_id` INT( 11 ) NOT NULL",

	"UPDATE ifaces i, wireless_ifaces wi
	SET wireless_mode = wmode, wireless_antenna = antenna
	WHERE wi.iface_id = i.id",

);

function upgrade_1_0_0_rc1_after()
{
	echo "Some PHP code triggered after processing of all SQL commands"
	return TRUE;
}

Pokud některý z SQL příkazů vyvolá chybu, popřípadě některá funkce vrátí FALSE, je provádění ukončeno a chyba zobrazena uživateli. Při tomto stavu je FreeneIS nefunkční, pokud takový stav nastane, doporučujeme kontaktovat vývojáře a ze zálohy si obnovit poslední fungující verzi databáze (společně se snížením verze FreenetISu).

Stav databáze je uchováván v databázové tabulce config v poli db_schema_version, které obsahuje aktuální verzi databáze. Pokud je databáze v chybovém stavu, nepovedený krok je zaznamenán v poli upgrade_midpoint_error. Tato hodnota umožňuje opětovné provedení aktualizace od chybné položky, proto při chybě stačí opravit chybnou položku a znovu spustit FreenetIS v prohlížeči.

V příkladu se ještě nachází hodnota $upgrade_equal_to['1.0.0~rc1'], která je používaná pro vývojářské účely. (Při mergi změn z větve do trunku/testingu lze hodnotu tohoto pole vyplnit vývojovou verzí, která obsahovala stejnou sadu příkazů a funkcí pro úpravu databáze. Pokud se databáze nachází ve stavu vývojové verze a je jí nabídnuta verze, která pomocí tohoto pole odkazuje na vývojovou verzi. Je tato verze přeskočena)