[[PageOutline(2-5,Contents,pullout)]]

= Execute an SQL query from within Trac

== Description

This plugin allows you to execute an SQL Query against a configured database displaying a formatted table of results from within Trac. The macro uses [http://www.sqlalchemy.org/ SQLAlchemy], the Python SQL toolkit and Object Relational Mapper that gives application developers the full power and flexibility of SQL.

This macro can be used in one of two ways:
{{{
{{{
#!SQL
SELECT * FROM foo
}}}
}}}

or:

{{{
[[SQL(SELECT * FROM foo)]]
}}}

A previous version of this module is known as SqlQueryMacro.

See also: TracSqlAlchemyBridgeIntegration

== !Bugs/Feature Requests

Existing bugs and feature requests for SqlAlchemyQueryMacro are 
[report:9?COMPONENT=SqlAlchemyQueryMacro here].

If you have any issues, create a 
[/newticket?component=SqlAlchemyQueryMacro new ticket].

[[TicketQuery(component=SqlAlchemyQueryMacro,group=type,format=progress)]]

== Download

Download the zipped source from [export:sqlalchemyquerymacro here].

== Source

You can check out SqlAlchemyQueryMacro from [/svn/sqlalchemyquerymacro here] using Subversion, or [source:sqlalchemyquerymacro browse the source] with Trac.

SqlAlchemyQueryMacro comes with sortable tables using the [http://www.kryogenix.org/code/browser/sorttable/ sorttable] library, written in Javascript.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

This macro requires the pypi:sqlalchemy ​library and makes use of its database and table modules. Please install python-sqlalchemy first.
After getting the source you will have to edit {{{ install_sqlalchemyquery.bash }}} to your needs, you can change:
{{{#!ini
TRAC_PATH_REPLACE = "/path/to/your-trac-environment" # absolute path to your trac environment
TRAC_REPLACE = "your_trac_environment"               # name of your trac environment (relative path without slashes)
MAX_ROW_COUNT_REPLACE = "1000"                       # maximum numbers of rows for the query result to display
TABLE_BORDER_REPLACE = "border=\"1\""                # set the border with of the table 
}}}

To install the macro:
{{{#!sh
tar -zxvf SqlAlchemyQuery.tar.gz
cd SqlAlchemyQuery
--- edit install_sqlalchemyquery.bash ---
./install_sqlalchemyquery.bash
}}}

or with svn:

{{{#!sh
svn checkout https://trac-hacks.org/svn/sqlalchemyquerymacro
cd sqlalchemyquerymacro/1.0/
--- edit install_sqlalchemyquery.bash ---
./install_sqlalchemyquery.bash
}}}

To enable this plugin add the following to your `trac.ini` file:
{{{#!ini
[components]
sqlalchemyquery.* = enabled
}}}

== Configuration

To configure this plugin, you must tell SqlAlchemy what database to connect to.

In `trac.ini`:

{{{#!ini
[sqlalchemyquery]
uri = mysql://user:password@hostname/database
}}}

You can also use Oracle or SQLite:

{{{#!ini
[sqlalchemyquery]
uri = oracle://user:password@tns
}}}

or:

{{{#!ini
[sqlalchemyquery]
uri = sqlite:///path/to/database
}}}

Restart tracd after making these changes.

== Recent Changes

[[ChangeLog(sqlalchemyquerymacro, 3)]]

== !Author/Contributors

**Author:** [wiki:fvdberg] [[BR]]
**Maintainer:** [[Maintainer]] [[BR]]
**Contributors:**