Actions

J2.5

Difference between revisions of "Managing Component Updates (Update SQL files)"

From Joomla! Documentation

m
(23 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{review}}
+
{{version/tutor|2.5}}{{Chunk:Managing Component Updates - Contents}}{{review}}
This tutorial is for Joomla {{JVer|1.6}}
+
== Articles in this series ==
+
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
+
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
+
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
+
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
+
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
+
 
+
 
== Update SQL files ==
 
== Update SQL files ==
 
The update SQL file(s) are located in a directory that is listed in the manifest file:
 
The update SQL file(s) are located in a directory that is listed in the manifest file:
Line 19: Line 11:
 
</source>
 
</source>
  
There is a file for each component version.  Each file name must match the version string in the manifest file for that version.  Joomla uses this string to determine which SQL files(s) to execute, and in what order they will be executed.  Joomla uses the PHP version_compare function for this.  Familiarize yourself with this command.  Your version sequence needs to adhere to the conventions of this command.
+
There is an SQL file for each component version.  Each file name must match the version string in the manifest file for that version.  Joomla uses this string to determine which SQL files(s) to execute, and in what order they will be executed.   
For example, the SQL files for version 3.1 include:
+
 
 +
''Important Note:'' These files are also used to set the version number in the <code>#__schemas</code> table. This version number must be present in the current version of the component in order for the new SQL files to be run during the update. For example, if you have version 1.0 and are updating to version 1.1, the <code>1.1.sql</code> file will not be executed if there was no <code>1.0.sql</code> file in the 1.0 release. For this reason, it is good practice to have a SQL update file for each version, even if there is no SQL change in that version. You can just use an empty file or a file with a comment line.
 +
 
 +
Joomla uses the PHP ''version_compare'' function to execute the correct SQL files..  Familiarize yourself with this function.  Your version strings need to adhere to the conventions of this function.
 +
For example, the SQL files for version 1.3 of this example include:
 
<blockquote>
 
<blockquote>
 
<pre>
 
<pre>
 
1.0.sql
 
1.0.sql
   (empty)
+
   (empty) OR
 +
  # Dummy SQL file to set schema version to 1.0 so next update will work
  
 
1.1.sql
 
1.1.sql
Line 49: Line 46:
 
* When updating from version 1.0 directly to 1.3, files 1.1.sql, 1.1.1.sql, 1.2.sql, 1.2.1.sql and 1.3.sql are all executed.  You can see the cumulative effect of the table changes in the component front-end.
 
* When updating from version 1.0 directly to 1.3, files 1.1.sql, 1.1.1.sql, 1.2.sql, 1.2.1.sql and 1.3.sql are all executed.  You can see the cumulative effect of the table changes in the component front-end.
  
Joomla executes the database updates in the sequence that would occur, as if the user had updated each version separately.  This would be necessary if an incremental database update depended on the correct update from the previous version.  An example would be: an addition of a table value during one version depended on the insertion of a new table field during the update of  the previous version.
+
Joomla executes the database updates in the sequence that would occur, as if the user had updated each version separately.  This would be necessary if an incremental database update depended on the correct update from the previous version.  An example would be: if a modification of a table value during one update depended on the addition of a new table field during a previous update.
  
Joomla uses the PHP function version_compare to define the execution order of the SQL files.  The sequencing of your component version string must adhere to that defined by the version_compare function.
+
Joomla uses the PHP function ''version_compare'' to define the execution order of the SQL files.  The sequencing of your component version string must adhere to that defined by the ''version_compare'' function.
  
 
== Contributors ==
 
== Contributors ==
 
*[[User:sm990|Kim Eckert]]
 
*[[User:sm990|Kim Eckert]]
  
[[category:Joomla! 1.6]]
+
[[Category:Joomla! 2.5]]
 +
[[Category:Component Development]]

Revision as of 07:05, 24 May 2013

Contents

Copyedit.png
This Page Needs Your Help

This page is tagged because it NEEDS REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.


Update SQL files

The update SQL file(s) are located in a directory that is listed in the manifest file:

<update> 
        <schemas> 
                <schemapath type="mysql">sql/updates</schemapath> 
        </schemas> 
</update>

There is an SQL file for each component version. Each file name must match the version string in the manifest file for that version. Joomla uses this string to determine which SQL files(s) to execute, and in what order they will be executed.

Important Note: These files are also used to set the version number in the #__schemas table. This version number must be present in the current version of the component in order for the new SQL files to be run during the update. For example, if you have version 1.0 and are updating to version 1.1, the 1.1.sql file will not be executed if there was no 1.0.sql file in the 1.0 release. For this reason, it is good practice to have a SQL update file for each version, even if there is no SQL change in that version. You can just use an empty file or a file with a comment line.

Joomla uses the PHP version_compare function to execute the correct SQL files.. Familiarize yourself with this function. Your version strings need to adhere to the conventions of this function. For example, the SQL files for version 1.3 of this example include:

1.0.sql
  (empty) OR
  # Dummy SQL file to set schema version to 1.0 so next update will work

1.1.sql
  UPDATE `#__democompupdate_mytable` SET myvalue='Version 1.1 text' WHERE id=1;

1.1.1.sql
  UPDATE `#__democompupdate_mytable` SET myvalue='Version 1.1.1 text' WHERE id=1;

1.2.sql
  INSERT INTO `#__democompupdate_mytable` (id,myvalue) VALUES (2,'Version 1.2 text');

1.2.1.sql
  UPDATE `#__democompupdate_mytable` SET myvalue='Version 1.2.1 text' WHERE id=2;

1.3.sql
  INSERT INTO `#__democompupdate_mytable` (id,myvalue) VALUES (3,'Version 1.3 text');

This example has complete install files for component versions 1.0 (initial), 1.1.1 and 1.3. Update SQL files are included for additional incremental component versions (1.1, 1.2 and 1.2.1) between these three versions. These extra versions illustrate the process for updates that span more than one incremental version.

  • When updating from version 1.0 to version 1.1.1, both files 1.1.sql and 1.1.1.sql are executed. The SQL commands update the value of the first, and only, row in the database table. The command in 1.1.1.sql over-writes the value that was written by 1.1.sql.
  • When updating from version 1.1.1 to version 1.3, files 1.2.sql, 1.2.1.sql and 1.3.sql are executed. The commands in 1.2.sql and 1.3.sql each create a new row in the database table.
  • When updating from version 1.0 directly to 1.3, files 1.1.sql, 1.1.1.sql, 1.2.sql, 1.2.1.sql and 1.3.sql are all executed. You can see the cumulative effect of the table changes in the component front-end.

Joomla executes the database updates in the sequence that would occur, as if the user had updated each version separately. This would be necessary if an incremental database update depended on the correct update from the previous version. An example would be: if a modification of a table value during one update depended on the addition of a new table field during a previous update.

Joomla uses the PHP function version_compare to define the execution order of the SQL files. The sequencing of your component version string must adhere to that defined by the version_compare function.

Contributors