View source for Using XMLDB

Note: This page is a work in progress. It is intended to help developers of third-party modules, and other plugins, to help them switch to XMLDB.

==What is XMLDB and how can it help you==

XMLDB stores the database definition in an XML format that can be used to install Moodle on any database. Everywhere in Moodle now uses XMLDB.

In every module (or other plugin) folder, there is a ''db/'' folder where the database structure is stored. In the past, this used to contain separate files ''mysql.php'', ''mysql.sql'', etc. for different databases. It meant that you had to create different files for each database system. If there were more databases you wanted your module to be compatible with, you had to create more files. Switching to XMLDB means that you only have to create one file, and there is an editor to help you, so it saves you time.

==Getting started==

The XMLDB database definition is stored in the file ''db/install.xml''. You can use a built-in XMLDB editor to create or edit any ''install.xml'' files. If you're using MySQL as your default database schemes. XMLDB editor's powerful tools allowing retrofit MySQL table to XMLDB format.

The XMLDB editor is located in administration block, go to ''Miscellaneous > XMLDB editor''. Find your module name. Initially you won't be able to click on ''Create'' link and also can't edit your module (If the ''Create'' link is clickable you can skip this step). Since you must make your module folder has write permission first (And if you haven't created ''db/'' folder in your module folder yet, create it now). In Linux operating system, ''chmod'' your ''/db'' folder to 777 solves this. Now you're ready to create your module's XMLDB files.

Note that XMLDB editor is not a tool for creating your module, though it can help you with the database. It is a tool to manage XMLDB database file (think about phpmyadmin manages SQL database). You can create tables/fields/keys/indexes or export your existing MySQL tables to XMLDB.

Another XMLDB's advantage is you can create table comments as you want. To describe it to other developer.

XMLDB editor is really easy to work with. We strongly recommend you to play with it for a while and read [[XMLDB editor]] and  about XMLDB structure [[XMLDB defining an XML structure]].

===Create ''install.xml''===

If you never create ''install.xml'' before (your ''db/'' doesn't have ''install.xml''), click ''Create'' first. install.xml will store your database info for this module.

===Start editing===

To start editing ''install.xml'', click ''Load'' and then ''Edit''. You need to do this every time before editing any XMLDB file.  If this is your first time, there is a default table named like your module stored.

===Create new table===

# Go to ''New Table''.
# Enter table name and comment, click ''change''.

===Add field in table===

# Click ''Edit'' on your desired table.
# Click ''New Field'', You can now edit field information like name, comment, type, length, etc. See [[XMLDB column types]] for XMLDB column type comparing with other database system.
# When you're done, click ''Change''.

===Retrofit MySQL table to XMLDB===

XMLDB editor can retrofit MySQL table to XMLDB. In other word, it can create XMLDB table from existing SQL. This is useful if your module database already using MySQL.
First, your module has to be installed. Then follow these steps:

# Click ''New Table from MySQL''
# In ''Create Table'' box, choose your table from MySQL database. In ''After Table'' choose where would you like to add this table to (It doesn't matter, just for arrangement). Click ''Create''.
# Do it again until every table added, you are done!

Note: Table name must contains only lowercase character, number, underscore and length must not exceed 28 characters. More info here: [[XMLDB defining an XML structure]]

===Other operation===

It's intuitive once you use it. There are visible links for editing, moving up or down and deleting.

==See also==

*[[XMLDB editor]]
*[[XMLDB introduction]]
*[[XMLDB defining an XML structure]]
*[[XMLDB column types]]

[[Category:XMLDB]]