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['1.0.0~rc1'] = 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).

Aktuální stav databáze

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.

Relace mezi změnami

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í). 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. Soubor se změnami odkazované verze je v commitu odstraněn!!)

Přechod ze starší verze mechanismu

Starší verze FreeneISu (vývojová verze před vydáním verze 1.0.0) obsahovala starší verzi mechanismu (založenou na SVN revizi). Pokud provádíte čistou instalaci nad novou databází, tento problém se Vás netýká.

Přechod mezi tímto mechanismem lze provest pomocí několika příkazů svn.

1) Otervřte terminál (příkazovou řádku) a přesuňte se do adresáře s instalací FreenetISu, typicky:

$ cd /var/www/freenetis

2) Přejděte na poslední revizi s upgradem databáze před vydání verze 1.0.0

$ svn -r 1559 up

3) Spusťte v prohlížeči FreenetIS a pokud jsou úpravy úspěšně provedeny přejděte na další krok.

4) Přejděte na nejnovější verzi FreenetISu. Nový mechanismus již automaticky rozpozná verzi databáze (starý mechanismus) a provede přechod.

$ svn up

POSLEDNÍ KROK JE OVŠEM NEDOPORUČOVANÝ, JELIKOŽ OD VYDÁNÍ VERZE 1.0.0 SE UPUSTILO OD DISTRIBUCE FREENETISU PROMOCÍ SUBVERSION, PROTO POSLEDNÍ KROK DOPORUČUJEME NAHRADIT PŘEINSTALACÍ FREENETISU Z BALÍČKOVACÍCH SYSTÉMU (data samozřejmě zůstanou zachována, jelikož i při přeinstalaci můžete zvolit Vaši původní databázi).