The Administrative GUI
We will provide a quick tour of the administrative GUI:
- add two documents to a collection
- list all documents
- backup the entire database
- delete our collections
- restore the backup
If you have MonetDB/XQuery running on your local machine, just point your browser to http://127.0.0.1:50001/admin. If it runs on a different machine, then point it to http://machine:50001/admin. However, the Administrative GUI usually only allows clients from the local machine (for security reasons). By typing delete(xrpc_admin); in the MonetDB console, you can bluntly disable those XRPC security settings. More information can be found in the Reference Manual.
On an empty database: your browser would show something like:
Add two documents to a collection
When you add a document to the database, you specify its current location (a URL; you can click the "Browse" button if it is a local file), a new logical name that you can later use as a parameter to fn:doc(logicalname) in your queries, and a collection name. Every document in MonetDB/XQuery belongs to some collection. In the simplest case you will have a separate collection for each document, but in this example, we will make a collection of two documents.
Here, we add the book.xml document from the Books tutorial. If the percentage you are also asked to specify is non-zero, you will get an updatable collection; by default the value is 0 which makes the data stored in MonetDB/XQuery read-only.
By clicking "Add", the document will be shredded under the logical name "book.xml" into a new collection "my-collection".
Please repeat this procedure for the bib.xml document (i.e. add it with logical name "bib.xml" to the collection "my-collection").
Note that in the administrative GUI you can only add one document at a time. The Tips section explains how you can easily add many documents to MonetDB/XQuery.
List all documents in the database
The database now contains a single collection "my-collection", that contains two documents: "book.xml" and "bib.xml".
You can view the documents in the browser as well.
WARNING: the view option gives the entire XML document to the internet browser. Browsers usually do not handle large XML files well (e.g. larger than a few MBs).
Backup the entire database
You can back-up the entire database under a logical name, here "my-backup":
The backup will be created in as a new DBFARM/DBNAME/backup/my-backup sub-directory. If you wish you may copy this entire sub-directory into a (compressed) archive; it contains all data needed to restore your entire database.
The DBFARM directory you use is specified by the gdk_dbfarm variable in the MonetDB.conf file. The DBNAME by default is demo and it is set using the --dbname DBNAME command-line switch given to the Mserver when started.
Delete our collection
You may delete all data in the database, by deleting all collections one-by-one. In this case, we have only one collection "my-collection":
Restore the backup
The entire database can be restored from a backup, by specifying the logical backup name. The restore adds all documents in the backup to the database. Therefore, it will generate an error if a document with the same name is already in it. This is the reason why we deleted all collections first in this tutorial.
The Default free percentage will be used as the new fill degree for all updatable collections (remark: this is inflexible and this feature should be changed!). The free percentage is irrelevant for read-only collections.
NOTE: you can actually use the backup/restore procedure to change the updatable/read-only characteristic of your collections using the following trick. Inside the backup directory (here DBFARM/DBNAME/backup/my-backup) you find a file collections.xml that lists all collections. By setting the updatable attribute to either true or false (using a text editor), you can change under what mode the collection will be restored.
WARNING: the backup/restore procedure may lead to a database that is slightly different from the you had before the backup, in two ways:
- the URL location of the document is now a file path inside the backup directory (that is, the original URI is not preserved). See the picture above.
- if you restored an updatable collection, which had been updated (hence may have had some fragmentation on the physical storage level because of that), or if you restore it with a different free percentage, then the node-identifiers (NIDs) exposed by the extension function pf:nid() will change. This is because NIDs refer to physical disk locations. If you store NID values as references in XML, these will now be incorrect!
The backup/restore procedure is a good way to reduce physical fragmentation in an intensively updated document.