Difference between revisions of "WikiDB/Installation"

From TestWiki
Jump to: navigation, search
m (Create temporary table privileges)
(Updated installation instructions for v3)
Line 1: Line 1:
−
Aside from installing the extension in the usual way (files available [[WikiDB/Files|here]]), you need to do the following to get the extension up and running:
+
This page describes how to install WikiDB.  If you already have WikiDB installed and need to upgrade to a later version, see [[WikiDB/Upgrading]] instead. 
  
−
# Create the [[../Tables/|required tables]] in your database.  In the finished version there will be an install script to do this for you.
+
== Requirements ==
−
# Ensure that the database user that MediaWiki uses to connect to the DB has <tt>Create Temporary Table</tt> privileges.
+
−
# Create the appropriate extra namespace(s), using [[mw:Manual:$wgExtraNamespaces|$wgExtraNamespaces]].  Remember to create the 'talk' namespace(s) as well!
+
−
# Add the namespace(s) that you want to use to hold table definitions to the $wgWikiDBNamespaces array.
+
  
−
For example, the setup file for this wiki contains the following extra lines:
+
* MediaWiki (obviously).  Currently WikiDB requires v1.6 or above.  These instructions assume that you have already got MediaWiki up and running.
 +
* Shell access is required for the command-line setup scripts.  You can avoid this for a while by [[../Tables|manually creating the DB tables]] but it will probably not possible to upgrade to later versions without being able to run these scripts.
 +
* Currently WikiDB requires that the database user which MediaWiki uses to connect to the DB has <code>Create Temporary Table</code> privileges.  I plan to remove this restriction in a future version.
  
−
<php>include("extensions/WikiDB.php");
+
== Step 1: Download and install the code ==
  
 +
You can download the latest version of WikiDB as a zipped archive. 
 +
 +
: <span style="font-size: 1.2em;">'''[[Media:WikiDB.zip|Download WikiDB Here!]]'''<br>or visit the [[:Image:WikiDB.zip|file description page]] for a bit more information (e.g. version details, etc).</span>
 +
 +
You need to extract the file into your extensions directory, which should create a <code>WikiDB</code> folder containing some sub-folders and the main startup script.  The path to this folder should be '''<code><span style="color: #999999;">/path/to/mediawiki</span>/extensions/WikiDB/</code>'''.
 +
 +
If you need to install it to a different location, you will need to adjust the path in the <code>require_once()</code> line, below, and you will probably need to set the <code>MW_INSTALL_PATH</code> environment variable in order to run the command-line maintenance scripts, but otherwise this should not cause any problems.
 +
 +
== Step 2: Modify LocalSettings.php ==
 +
 +
Once the files are in place, you need to modify <code>[[mw:Manual:LocalSettings.php|LocalSettings.php]]</code> (which is where all wiki configuration settings are stored) in order to load and configure the extension.
 +
 +
=== Load the extension ===
 +
 +
To use the extension, you first need to load it.  To do this, you simply need to add the following line to <code>LocalSettings.php</code>:
 +
 +
<php>require_once("extensions/WikiDB/WikiDB.php");</php>
 +
 +
You can check that the extension is loaded properly by visiting the <code>Special:Version</code> page on your wiki, where it should be listed along with the correct version number.
 +
 +
=== Define table namespaces ===
 +
 +
In order for the extension to have any worthwhile effect, you need to define one or more table namespaces.  Table namespaces are where your table definitions are stored, and have special properties which are different to other namespaces within the wiki (for more about the concept of namespaces see [[mw:Manual:Namespaces|this article at MediaWiki.org]]).  In most situations only a single table namespace is required, though it is possible to define several.
 +
 +
To set up a table namespace, you need to first create the namespaces by adding it to <code>$wgExtraNamespaces</code>, so that MediaWiki knows about it (including its associated 'talk' namespace) and then you need to add it to the <code>$wgWikiDBNamespaces</code> array so that WikiDB knows to treat it as special.
 +
 +
For example, here's what you need to add to <code>LocalSettings.php</code> in order to create a single table namespace called <code>Table</code>:
 +
 +
<php>
 
$wgExtraNamespaces = array(
 
$wgExtraNamespaces = array(
 
100 => "Table",  
 
100 => "Table",  
Line 20: Line 48:
 
</php>
 
</php>
  
−
Note that you may define as many DB namespaces as you like.  This could be useful if your wiki is used for several different projects that you want to keep separate, or if you want to grant users different rights for different namespaces. However, in most situations a single DB namespace will be enough. 
+
For more information, including how to set up multiple table namespaces, see the documentation for [[WikiDB/Configuration#$wgWikiDBNamespaces|$wgWikiDBNamespaces]] on the Configuration page.
 +
 
 +
=== Further configuration ===
 +
 
 +
See [[WikiDB/Configuration]] for further (optional) configuration options.
 +
 
 +
== Step 3: Set up the database ==
 +
 
 +
WikiDB has an automated script to set up the database ready for use.  The requirements for running the WikiDB maintenance scripts is the same as those for the standard MediaWiki maintenance scripts, i.e. you need command-line access and appropriate permissions to modify the DB schema.  For more details about this see [[mw:Manual:Maintenance scripts]].
 +
 
 +
To setup the database tables, you need to run the SetupTables script:
 +
 
 +
  $ cd /path/to/mediawiki/extensions/WikiDB/maintenance
 +
$ php SetupTables.php
 +
 
 +
You should not need to run any other maintenance scripts the first time you run WikiDB, but if there is a chance that your wiki already contains any of the special markup used by WikiDB then you should also run the RebuildWikiDB script, however this can be very slow on a large wiki, as it involves re-parsing all pages!
  
−
If you are using more than one DB namespace, the first one in the $wgWikiDBNamespaces array is used as the default table namespace in table attributes where no namespace is supplied.  For example, say you have two table namespaces 'Foo' and 'Bar', with 'Foo' being defined first in the array.  If you add some data as follows: <code>&lt;data table="Humbug"></code> it will be added to the table "Foo:Humbug", because "Foo" is the default DB namespace.  To add it to "Bar:Humbug" as intended, you would need to use the full name: <code>&lt;data table="Bar:Humbug"></code>.
+
$ php RebuildWikiDB.php

Revision as of 23:08, 29 August 2010

This page describes how to install WikiDB. If you already have WikiDB installed and need to upgrade to a later version, see WikiDB/Upgrading instead.

Requirements

  • MediaWiki (obviously). Currently WikiDB requires v1.6 or above. These instructions assume that you have already got MediaWiki up and running.
  • Shell access is required for the command-line setup scripts. You can avoid this for a while by manually creating the DB tables but it will probably not possible to upgrade to later versions without being able to run these scripts.
  • Currently WikiDB requires that the database user which MediaWiki uses to connect to the DB has Create Temporary Table privileges. I plan to remove this restriction in a future version.

Step 1: Download and install the code

You can download the latest version of WikiDB as a zipped archive.

Download WikiDB Here!
or visit the file description page for a bit more information (e.g. version details, etc).

You need to extract the file into your extensions directory, which should create a WikiDB folder containing some sub-folders and the main startup script. The path to this folder should be /path/to/mediawiki/extensions/WikiDB/.

If you need to install it to a different location, you will need to adjust the path in the require_once() line, below, and you will probably need to set the MW_INSTALL_PATH environment variable in order to run the command-line maintenance scripts, but otherwise this should not cause any problems.

Step 2: Modify LocalSettings.php

Once the files are in place, you need to modify LocalSettings.php (which is where all wiki configuration settings are stored) in order to load and configure the extension.

Load the extension

To use the extension, you first need to load it. To do this, you simply need to add the following line to LocalSettings.php: 

require_once("extensions/WikiDB/WikiDB.php");

You can check that the extension is loaded properly by visiting the Special:Version page on your wiki, where it should be listed along with the correct version number.

Define table namespaces

In order for the extension to have any worthwhile effect, you need to define one or more table namespaces. Table namespaces are where your table definitions are stored, and have special properties which are different to other namespaces within the wiki (for more about the concept of namespaces see this article at MediaWiki.org). In most situations only a single table namespace is required, though it is possible to define several.

To set up a table namespace, you need to first create the namespaces by adding it to $wgExtraNamespaces, so that MediaWiki knows about it (including its associated 'talk' namespace) and then you need to add it to the $wgWikiDBNamespaces array so that WikiDB knows to treat it as special.

For example, here's what you need to add to LocalSettings.php in order to create a single table namespace called Table: 

$wgExtraNamespaces = array(
	100 => "Table", 
	101 => "Table_Talk"
);
 
$wgWikiDBNamespaces = array(
	100 => true
);

For more information, including how to set up multiple table namespaces, see the documentation for $wgWikiDBNamespaces on the Configuration page.

Further configuration

See WikiDB/Configuration for further (optional) configuration options.

Step 3: Set up the database

WikiDB has an automated script to set up the database ready for use. The requirements for running the WikiDB maintenance scripts is the same as those for the standard MediaWiki maintenance scripts, i.e. you need command-line access and appropriate permissions to modify the DB schema. For more details about this see mw:Manual:Maintenance scripts.

To setup the database tables, you need to run the SetupTables script: 

$ cd /path/to/mediawiki/extensions/WikiDB/maintenance
$ php SetupTables.php

You should not need to run any other maintenance scripts the first time you run WikiDB, but if there is a chance that your wiki already contains any of the special markup used by WikiDB then you should also run the RebuildWikiDB script, however this can be very slow on a large wiki, as it involves re-parsing all pages! 

$ php RebuildWikiDB.php
Retrieved from ‘https://www.kennel17.co.uk/testwiki/index.php?title=WikiDB/Installation&oldid=2364’