Automatic change of database structure

FreenetIS includes a mechanism for automatically changing the structure of the database. These changes are made ​​after the start FreenetIS (after opening the browser ) after the update ( here it does not matter whether it is an update through the package system , or from the development repository ) . The changes can not be canceled , which means that the downgrade FreenetIS not possible ( of course, this phenomenon can be removed manually changing the database from a backup , in which, however, we can not guarantee the correctness of the final state of the system) .

The mechanism for updating is closely related to [ http://wiki.freenetis.org/index.php/Verzování_FreenetIS versioning FreenetIS ] . In the folder '/ db_upgrades ' is a file with the changes for each version FreenetIS . The file names are in the format ' upgrade_sql_VERZE.php , where 'Version is replaced by version FreenetIS . File itself must contain an entry field '$ upgrade_sql ' s index of a given version FreenetIS . This item contains an array of SQL statements that are executed sequentially . It may also contain PHP functions that run before and after the execution of SQL commands that are used for example if the data can not be transferred between different versions of directly using SQL commands. Both functions can contain arbitrary PHP commands and must return a boolean value ( boolean) .

Example file changes:

<?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;
}

The current state of the database

State database is stored in a database table in the field db_schema_version , which contains the current version of the database . If the database is in an error state , foiled step is recorded in the upgrade_midpoint_error . This value allows you to re-perform the update from the wrong items , so the errors just correct a wrong entry and re-run FreenetIS browser .

Relation between changes

In the example, there is the item $ upgrade_equal_to [ '1 .0.0 ~ rc1 '] , which is used for development purposes . ( When you merge changes from branch to trunk / testing the value of this field can fill development version , which contained the same set of commands ( and functions) . If the database is in a state of development versions and is offered a version that uses this field refers to the development version . Skipped this version . File with changes of the referenced version after commit will be deleted ! )

If any of the SQL statement generates an error, or some function returns FALSE , the implementation is completed and the error displayed to the user . When such a situation occurs and FreeneIS become inoperable, we recommend you contact the developer of backup and restore the last working version of the database (along with a reduction FreenetISu version ) .

Transition from older versions

Older versions FreeneIS (development version prior to version 1.0.0 ) includes an earlier version of the mechanism ( based on SVN revision ) . If you perform a clean installation of a new database , this problem does not concern you .

The transition between this mechanism can be accomplished using several commands svn .

1 ) Open a terminal ( command prompt ) and navigate to the directory with the installation FreenetISu , typically :

$ Cd / var / www / freenetis

2 ) Go to the latest revision to upgrade the database before the release of version 1.0.0

$ Svn up -r 1559

3) Start the browser FreenetIS and if adjustments are carried out successfully go to the next step .

4 ) Go to the latest version FreenetISu . A new mechanism has been automatically detects the version of the database (old type) and makes a transition .

$ Svn up

The last step , however, is advised against because since the release 1.0.0 has departed from the pattern FREENETIS graduation Subversion , SO LAST STEP recommends replacing reinstalling FREENETIS of package systems (data , of course, remain the same , as well as when you choose to reinstall your original database ).

Safely change the database to version 1.0.0

Do not include to FreenetIS 1.0.0 version available safeguards for multiple start the upgrade. This problem occurs when multiple people / services FreenetIS access to the database upgrade. Follow these steps to avoid problems when upgrading the database: ( 'This instruction applies FreenetISu to version 1.0.0, since this version (included) is automatically guarantee correct operation.')

1) Turn off all services accessing the FreenetISu (CRON, redirect. QoS, monitoring, ...). Eg. CRON on Debian off as follows:

 / etc / init.d / cron stop

2) Turn off the apache server

 / etc/init.d/apache2 stop

3) Perform the upgrade

 wget http:// <path_to_mount_directory> your FreenetIS>

4) Restart the apache and services

 / etc/init.d/apache2 start
 / etc / init.d / cron start