Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

XMLDB defining an XML structure: Difference between revisions

From MoodleDocs
m (Minor grammatical error corrected)
(Remove references to STATEMENT and SENTENCES)
Line 4: Line 4:
== Justification ==
== Justification ==


Before Moodle 1.7, all the DB install and upgrade was developed twice (once to handle MySQL installations and another to handle PostgreSQL installations). This approach, although working, has caused some headaches in the past, mainly because it was really difficult to keep both lines of development 100% on sync. Some developers do they work against one RDBMS and it was complex to develop to the other one (two test environments, skills on both databases, slower development cycle...). And all this was happening with ''only'' two supported RDBMS!
Moodle supports a number of Database Engines, including MySQL, MariaDB, Postgresql, OCI, and MS SQL Server. Each of
these has a slightly different format for some of their table creation statements.


One of the main objectives of Moodle 1.7 is to extend the the number of supported RDBMS to other flavours (more exactly, to Oracle and MSSQL). And the old approach (one line of development for each DB) could become an absolute nightmare.  
XMLDB has been created as a standardised format to describe the structure of the database in a human-readable format
which the Moodle installer can turn into DDL commands to create the database structure.


Because of this we have planned to build one structure to define all the DB objects used by Moodle. This structure will provide the necessary level of abstraction to be shared by all the RDBMS systems, so the "multiple lines of development" explained in the previous paragraph will be out forever, giving us one robust and well defined way to handle DB objects independently of the underlying RDBMS being used.
The Moodle XMLDB editor must be used to correctly define the XMLDB structure for all tables within Moodle. It is also able to convert the XMLDB structure into upgrade scripts which can be copied and pasted into Moodle <tt>upgrade.php</tt> files.
 
== Implementation ==
 
Initially all our best wishes were to use the [http://phplens.com/lens/adodb/docs-datadict.htm#xmlschema AdoDB XML Schema]. As Moodle is using ADOdb libraries to communicate with databases it sounded like the natural approach to solve the problem. But, finally, two reasons prevented us to use it:
 
# Although working, it seems to be one feature in progress, with important changes/evolutions arriving at the time of write this document.
# Its lack of support for "prefixes" (one Moodle key feature, to allow multiple instances to run in the same server), would force us to create some awful tricks to generate the objects.
 
So, finally, we decided to build our own XML files, with everything we need to define every object present in the DB.


== The XMLDB editor ==
== The XMLDB editor ==
Line 42: Line 35:
We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the '''install.xml''' files.
We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the '''install.xml''' files.


It's organised in a top-botton structure, where you start '''loading''' (or '''creating''') a new XMLDB file. Then, you can '''edit''' such file and its '''general structure''' will be showed. This structure have two type of elements, '''tables''' and '''statements''' and the XMLDB Editor allows you to '''add''', '''edit''', '''delete''', and '''move''' them easily. Also, for initial creation of tables, one small but effective '''reverse-enginery''' tool has been developed (only under MySQL) allowing you to retrofit any table from the DB to the XMLDB Editor.
It's organised in a top-bottom structure, where you start '''loading''' (or '''creating''') a new XMLDB file. Then, you can '''edit''' such file and its '''general structure''' will be showed. This structure has one type of elements, '''tables''' and the XMLDB Editor allows you to '''add''', '''edit''', '''delete''', and '''move''' them easily. Additionally it is possible to turn an existing table (under MySQL and MariaDB) into an XMLDB structure, allowing you to retrofit any table from the DB to XMLDB Editor.


'''Note: If you can't click on the create links....''' you must first create the /db folder (as shown in the list, but it may not really exist) and then make sure it is writeable by the webserver
'''Note: If you can't click on the create links....''' you must first create the /db folder (as shown in the list, but it may not really exist) and then make sure it is writeable by the webserver
Line 50: Line 43:
Fields can be edited and you can specify their '''name''', '''type''', '''length''', '''decimals''', '''null-ability''', '''defaults''' and so one. Exactly the same for both '''keys''' and '''indexes'''.
Fields can be edited and you can specify their '''name''', '''type''', '''length''', '''decimals''', '''null-ability''', '''defaults''' and so one. Exactly the same for both '''keys''' and '''indexes'''.


While editing statements, you must think about them like "collections of sentences". Once you select the '''type''' (only inserts are allowed for now) and '''table''' you are interested you'll be able to introduce the exact values easily, being able to '''duplicate''' them easily to gain some speed if you have a lot of sentences in your development. Sentences can be '''edited''' and '''deleted''' easily too.
One interesting feature is that all the XMLDB Editor pages allow you to enter one '''comment''' about the item being modified (table, index, key, field, etc). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.
 
One interesting feature is that all the XMLDB Editor pages allow you to enter one '''comment''' about the item being modified (table, index, key, field, statement...). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.


Please, don't forget to read and understand the next section, where we talk about '''some important guidelines''' to create and handle XMLDB files.
Please, don't forget to read and understand the next section, where we talk about '''some important guidelines''' to create and handle XMLDB files.
Line 87: Line 78:
*** KEYS
*** KEYS
*** INDEXES
*** INDEXES
** STATEMENTS, none or more, each one with
*** SENTENCES
*** SENTENCES


Line 117: Line 107:


Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).
Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).
=== The STATEMENT element ===
This is the other '''big container''' in the XMLDB Schema (at the same level as the '''TABLES''' one) and we can define its '''name''', '''type''' (only insert allowed for now) and '''table''' (against the sentences will be executed).
Every statement is a collection of '''sentences'''
==== The SENTENCE element ====
Each sentence implies one simple action to be performed against the DB and it can be defined as the "missing part of the SQL statement". In our example, we have one statement, of type "insert" on table "log_display". With this Moodle knows the initial part of the sentence, i.e:
INSERT INTO log_display
and then the text will be added to create this:
INSERT INTO log_display
  (module, action, mtable, field)
VALUES
  ('assignment', 'view', 'assignment', 'name')
There is one important trick when handling sentences, although they aren't in the assignment example. Take a look to the [http://cvs.moodle.org/moodle/lib/db/install.xml?view=co Core Tables XML Schema] (it's a huge one!). If you go near the end, to the statements section, you will see some sentences like this:
<SENTENCE TEXT="....VALUES ('user', 'view', 'user', 'CONCAT(firstname," ",lastname)')"/>
Such "CONCAT" function isn't standard at all (only MySQL supports it), but don't worry, we'll transform it to the correct concatenation operators for other RDBMS. Just be sure to use the syntax showed above.


== DTD and XML schema ==
== DTD and XML schema ==

Revision as of 01:08, 21 May 2021

XMLDB Documentation > Roadmap > Defining one XML structure


Justification

Moodle supports a number of Database Engines, including MySQL, MariaDB, Postgresql, OCI, and MS SQL Server. Each of these has a slightly different format for some of their table creation statements.

XMLDB has been created as a standardised format to describe the structure of the database in a human-readable format which the Moodle installer can turn into DDL commands to create the database structure.

The Moodle XMLDB editor must be used to correctly define the XMLDB structure for all tables within Moodle. It is also able to convert the XMLDB structure into upgrade scripts which can be copied and pasted into Moodle upgrade.php files.

The XMLDB editor

Main article

Although the XML is pretty simple to read (and to write), one of the major drawbacks was its easy and error-prone adoption by the developers. Also some problems with versioning systems getting crazy with XML files (thanks ML!) pointed us to the requirement to use one high-density format (it means, physically long lines) in our XML files.

After some intense thoughts we decided to build one specialised editor for our XML format. This editor should be easy to use and provide support for all the objects present one Moodle DB. And it's done (and will support future enhancements easily, we hope).

The XMLDB Editor makes the addition of tables/fields/keys/indexes practically a trivial task, allowing the developer to spend the time coding and improving things instead of fighting against XML files and the errors caused by manual editing (of course, the developer is free to use such extra-time as desired, beers, dance, books, music...) ;-)

All the new install.xml files, present under each db directory in Moodle can be edited (and we recommend it) with just some clicks and keystrokes. Those install.xml will contain all the info needed to generate the specific objects needed for each RDBMS supported. Obviously, such files, are the neutral replacement for all the *.sql files used until now.

Launching

Just login to your server as an administrator and, under the Development tab of the Administration Block, you'll see a new link pointing to the "XMLDB Editor".

One important note is that, to be able to handle files properly, the web server needs write access to all those "db" directories where the "install.xml" files reside (and to the files themselves, of course). ;-)

That's all!

Use

We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the install.xml files.

It's organised in a top-bottom structure, where you start loading (or creating) a new XMLDB file. Then, you can edit such file and its general structure will be showed. This structure has one type of elements, tables and the XMLDB Editor allows you to add, edit, delete, and move them easily. Additionally it is possible to turn an existing table (under MySQL and MariaDB) into an XMLDB structure, allowing you to retrofit any table from the DB to XMLDB Editor.

Note: If you can't click on the create links.... you must first create the /db folder (as shown in the list, but it may not really exist) and then make sure it is writeable by the webserver

While editing tables you will see their fields, keys and indexes and you'll be able to handle all them easily. Note that some fields can be no-editable. It uses to be because they are being used in some way (part of one key or index) and the idea is to warn you about that.

Fields can be edited and you can specify their name, type, length, decimals, null-ability, defaults and so one. Exactly the same for both keys and indexes.

One interesting feature is that all the XMLDB Editor pages allow you to enter one comment about the item being modified (table, index, key, field, etc). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.

Please, don't forget to read and understand the next section, where we talk about some important guidelines to create and handle XMLDB files.

Conventions

Apart of the Database Structures guidelines, some more conventions should be followed:

  1. About names:
    1. All lowercase names (tables, indexes, keys and fields).
    2. Table names and field names must use only a-z, 0-9 and _ chars. Table names can be at most 28 characters long; column names at most 30 characters.
    3. Key and index names under the XMLDB Files must be formed by concatenating the name of the fields present in the key/index with the '"-" (minus) character.
    4. Primary key always must be named "primary" (this is one exception to the previous convention).
    5. It's highly recommended to avoid reserved words completely. We know we have some of them now but they should be completely out for next releases.
  2. About NULLS
    1. Avoid creating all the fields as NOT NULL with the silly default value '' (empty string). The underlying code used to create tables will handle it properly but the XMLDB structure must be REAL. Read more in the Problems Page.
  3. About FOREIGN KEYS
    1. Under the tables of every XMLDB file, you must define the existing Foreign Keys (FK) properly. This will allow everybody to know a bit better the structure, allow to evolve to a better constrained system in the future and will provide the underlying code with the needed info to create the proper indexes.
    2. Note that, if you define any field combination as FK you won't have to create any index on that fields, the code will do it automatically!
    3. Respect Convention 1.3
  4. About UNIQUE KEYS
    1. Declare any fields as UNIQUE KEY (UK) only if they are going to be used as target for one FK. Create unique indexes instead.
    2. Respect Convention 1.3

One example: the assignment module

Here we are going to examine the current implementation of the XMLDB Schema for the assignment module (a simple one). It has been completely generated with the XMLDB Editor but it's nice to know a bit more about the XML internals.

As you can see the structure is pretty simple:

  • XMLDB
    • TABLES, one or more, each one with
      • FIELDS
      • KEYS
      • INDEXES
      • SENTENCES

First of all you should note that all the elements contain the PREVIOUS and NEXT attributes. They allow us to keep everything ordered although it isn't meaningful at all from the RDBMS perspective. Also the COMMENT field is present everywhere to be used as desired.

The TABLE element

We can ignore the TABLE element, as it's simply one container for the internals (FIELDS, KEYS and INDEXES). Let's go to examine them a bit more:

The FIELD element

It maps with one field in the DB (obviously). For each field you can define its name, type (from a list of neutral types), length, decimals (for some types), notnull (true/false), unsigned (true/false), sequence (if it's autonumeric or serial, true/false) and default (to assign a default value).

So, in our example, we have two tables, assignment and assignment_submissions, each one with its own fields, defining all the information related above. Please note that naming conventions are followed.

The KEY element

Here is where all the PRIMARY KEYS (PK), UNIQUE KEYS (UK) and FOREIGN KEYS (FK) will be defined. For each key we define its name, type, fields (that belongs to it) and optionally (if the key is one FK) the target reftable and reffields.

In our example, the assignment table has one (mandatory!) PK (called, "primary", rules are rules) built with the "id" field.

The other table, the "assignment_submissions" one, also has its PK (called "primary" once more) and one FK, with the field "assignment" pointing to the field "id" of the table "assignment". Note that the FK follows the name conventions and its name is, simply, the name of the fields being part of it ("assignment"). Also, the FK has as target to one PK of the same module.

Finally, note that there isn't any index created for all these keys. Moodle will generate them automatically when the table is created. All the keys will have their corresponding index. Point. ;-)

The INDEX element

Where all the indexes will be defined. For each index you can define its name, unique (true/false) and the fields (as a comma-separated string) that it comprises. Please note that naming conventions are followed.

Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).

DTD and XML schema

Not sure if this will be usable for somebody but here you can find one automatically generated DTD for the XMLDB files. Also one automatically generated XML Schema is available. Any improvement/fix to them will be welcome!

See also