Database Plugin

Provide secure access (read and write) to data in an SQL database, with flexible results formatting.

Any database that has a DBI interface can be used.

This version is for TWiki-4 only.

Usage

%DATABASE_SQL{description="table_description" sql="sql"}%

• description - identifies the database configuration to use (required)
• sql - The SQL to execute (required)
• format - (optional) Format to display results in. if you don't give this parameter results will be ignored.
• header - (optional) The header to display on the results table.
• separator - string that separates results. Default newline.

%DATABASE_SQL_TABLE{description="db1" headers="hdr1,hdr2,hdr3" command="sql command"}%

• description - identifies the database configuration to use
• headers - Table headers.
• command - Any SQL command that returns rows
• This syntax is maintained for compatibility. You are recommended to use DATABASE_SQL instead.

%DATABASE_SQL_REPEAT{description="description" command="..SQL COMMAND.." columns="col1,col2,col3"}% .... user formatting .... %DATABASE_SQL_REPEAT%

• description - identifies the database configuration to use
• columns - The columns in the table to return. Default "*"
• command - Any SQL command that returns values
• This syntax is maintained for compatibility. You are recommended to use DATABASE_SQL instead.

%DATABASE_TABLE{description="table_description" headers="hdr1,hdr2,hdr3" columns="col1,col2,col3"}%

• description - identifies the database+table configuration to use (required)
• columns - The columns in the table to return. Default "*"
• headers - Table headers
• This command requires a table to be specified in the configuration.
• This syntax is maintained for compatibility. You are recommended to use DATABASE_SQL instead.

%DATABASE_REPEAT{description="table_description" table="mytable" columns="col1,col2,col3"}% .... user formatting .... %DATABASE_REPEAT%

• description - identifies the database+table configuration to use
• columns - The columns in the table to return. Default "*"
• This command requires a table to be specified in the configuration.
• This syntax is maintained for compatibility. You are recommended to use DATABASE_SQL instead.

%DATABASE_EDIT{description="table_description" display_text="HTML link text"}%

• description - identifies the database configuration to use
• display_text - (optional) The columns in the table to return

Examples

%DATABASE_SQL{description="mysql_user_info" format="| $User | $Select_priv |" header="| *User Name* | *Select Privs* |"}%

You will get back a table with one row for each matching database entry.

Using the format functionality, you can define how the database data is displayed wrapping it in any formatting you choose. For example, if you wanted to create a single table cell containing the information for 3 fields of the Kalendus calendar, you could use the following:

%DATABASE_SQL{description="calendar_events" sql="SELECT * from calendar" format="| $startdate $subject $body |"}%

Or let's say you wanted to display the next two upcoming scheduled events in the Kalendus calendar.

%DATABASE_SQL{description="calendar_events" command="SELECT subject,body,startdate FROM kalendus_event WHERE to_days(startdate) > to_days(now()) order by startdate limit 2" format="$startdate<br />$subject<br />$body"}%

<-- 

 Set SHORTDESCRIPTION = Provide access to data in a SQL database
 
-->

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.

Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.

• If you have TWiki 4.2 or later, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • See the installation supplement on TWiki.org for more information.
• If you have any problems, then you can still install manually from the command-line:
  1. Download one of the .zip or .tgz archives
  2. Unpack the archive in the root directory of your TWiki installation.
  3. Run the installer script ( perl <module>_installer )
  4. Run configure and enable the module, if it is a plugin.
  5. Repeat for any missing dependencies.
• If you are still having problems, then instead of running the installer script:
  1. Make sure that the file permissions allow the webserver user to access all files.
  2. Check in any installed files that have existing ,v files in your existing install (take care not to lock the files when you check in)
  3. Manually edit LocalSite.cfg to set any configuration variables.

• If you are using TWiki-4.1 or later, use configure to set up the plugin. Otherwise copy and paste the contents of lib/TWiki/Plugins/DatabasePlugin/Config.spec into LocalSite.cfg and enter your settings manually.

Plugin Info

Related Topics: TWikiPreferences, TWikiPlugins