Convert SQL to Textile

Why Convert SQL to Textile?

Converting SQL files to Textile markup is essential for teams using Redmine or Textile-based content management systems for their project documentation. Textile's clean table syntax and code block support make it well-suited for documenting database schemas and queries in wiki-style project pages that render as formatted HTML.

Redmine, one of the most popular open-source project management tools, uses Textile as its default markup language for wiki pages, issue descriptions, and project documentation. By converting SQL schemas to Textile, database documentation integrates seamlessly into Redmine projects, allowing teams to maintain schema references alongside their project plans, issues, and milestones.

Textile's table syntax is particularly well-suited for database schema documentation. The |_. header syntax creates visually distinct header rows, and the pipe-delimited format clearly presents column names, data types, and constraints. Code blocks using the bc. (block code) prefix preserve SQL syntax formatting while integrating naturally into the surrounding documentation text.

Beyond Redmine, Textile is supported by Textpattern CMS, various Ruby on Rails applications, and can be processed by libraries in Ruby (RedCloth), PHP, Python, and JavaScript. Converting SQL to Textile creates portable documentation that can be published across multiple Textile-aware platforms, providing consistent rendering of database documentation wherever it's needed.

Key Benefits of Converting SQL to Textile:

• Redmine Integration: Native format for Redmine wiki pages and issue descriptions
• Clean Table Syntax: Readable table markup for schema documentation
• Code Blocks: Preserve SQL syntax in formatted code sections
• HTML Output: Textile converts directly to clean, semantic HTML
• Wiki Ready: Perfect for wiki-based project documentation
• Lightweight: Simple text-based format with minimal markup overhead
• CSS Styling: Apply custom styles and classes to elements

Practical Examples

Example 1: Schema Wiki Page

Input SQL file (schema.sql):

CREATE TABLE tickets (
    id INT PRIMARY KEY AUTO_INCREMENT,
    subject VARCHAR(255) NOT NULL,
    description TEXT,
    tracker_id INT NOT NULL,
    status_id INT NOT NULL DEFAULT 1,
    priority_id INT NOT NULL DEFAULT 2,
    assigned_to INT REFERENCES users(id),
    created_on TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Output Textile file (schema.textile):

h1. Tickets Table

p. Issue tracking table for project management.

|_. Column |_. Type |_. Constraints |
| id | INT | Primary Key, Auto Increment |
| subject | VARCHAR(255) | Not Null |
| description | TEXT | Optional |
| tracker_id | INT | Not Null |
| status_id | INT | Not Null, Default: 1 |
| priority_id | INT | Not Null, Default: 2 |
| assigned_to | INT | FK -> users(id) |
| created_on | TIMESTAMP | Default: Current Time |

h2. Notes

* Primary key: @id@ (auto-incrementing)
* Foreign key: @assigned_to@ references @users(id)@
* Default status: 1 (New)
* Default priority: 2 (Normal)

Example 2: Query Documentation

Input SQL file (reports.sql):

-- Active tickets by assignee
SELECT
    u.login AS assignee,
    COUNT(t.id) AS open_tickets,
    AVG(DATEDIFF(NOW(), t.created_on)) AS avg_age_days
FROM tickets t
JOIN users u ON t.assigned_to = u.id
WHERE t.status_id IN (1, 2, 3)
GROUP BY u.login
ORDER BY open_tickets DESC;

Output Textile file (reports.textile):

h2. Active Tickets by Assignee

p. This report shows the number of open tickets
per team member, along with the average age of
their assigned tickets.

bc. SELECT
    u.login AS assignee,
    COUNT(t.id) AS open_tickets,
    AVG(DATEDIFF(NOW(), t.created_on)) AS avg_age_days
FROM tickets t
JOIN users u ON t.assigned_to = u.id
WHERE t.status_id IN (1, 2, 3)
GROUP BY u.login
ORDER BY open_tickets DESC;

h3. Output Columns

|_. Column |_. Description |
| assignee | User login name |
| open_tickets | Count of open tickets |
| avg_age_days | Average ticket age in days |

p. *Statuses included:* New (1), In Progress (2),
Feedback (3)

Example 3: Migration Changelog

Input SQL file (migration.sql):

-- Migration: Add time tracking
CREATE TABLE time_entries (
    id INT PRIMARY KEY AUTO_INCREMENT,
    project_id INT REFERENCES projects(id),
    user_id INT REFERENCES users(id),
    hours DECIMAL(5,2) NOT NULL,
    activity VARCHAR(100),
    spent_on DATE NOT NULL,
    comments TEXT
);

CREATE INDEX idx_time_project
    ON time_entries(project_id, spent_on);

Output Textile file (migration.textile):

h1. Migration: Add Time Tracking

p(. _Applied: 2026-03-06_

h2. New Table: time_entries

|_. Column |_. Type |_. Constraints |
| id | INT | PK, Auto Increment |
| project_id | INT | FK -> projects(id) |
| user_id | INT | FK -> users(id) |
| hours | DECIMAL(5,2) | Not Null |
| activity | VARCHAR(100) | Optional |
| spent_on | DATE | Not Null |
| comments | TEXT | Optional |

h2. New Indexes

* @idx_time_project@ on @time_entries(project_id, spent_on)@

h2. Relationships

* @project_id@ -> *projects* table
* @user_id@ -> *users* table

Frequently Asked Questions (FAQ)

Q: What is Textile markup?

A: Textile is a lightweight markup language created by Dean Allen in 2002. It uses simple text notation to produce HTML output. Textile is the default formatting language in Redmine and Textpattern CMS. Key syntax includes h1. for headings, *bold*, _italic_, |pipes| for tables, and bc. for code blocks.

Q: How are SQL tables formatted in Textile?

A: SQL table schemas are converted to Textile pipe-delimited tables. Header rows use |_. prefix for each cell, making them render as <th> elements in HTML. Each column definition becomes a table row with fields for column name, data type, and constraints. The result renders as a clean, styled table in Redmine or any Textile processor.

Q: Can I use the output directly in Redmine?

A: Yes! The generated Textile is fully compatible with Redmine's wiki formatting engine. You can paste it directly into Redmine wiki pages, issue descriptions, or comments. The tables, headings, code blocks, and lists will all render correctly in Redmine's web interface.

Q: How is SQL code preserved in Textile?

A: SQL queries and code snippets are wrapped in Textile's block code syntax (bc. prefix), which preserves formatting and renders as <pre><code> in HTML. For inline SQL references like table or column names, the @code@ inline syntax is used. This ensures SQL syntax is displayed in monospace font.

Q: How does Textile compare to Markdown?

A: Textile and Markdown are both lightweight markup languages, but they use different syntax. Textile uses h1. for headings (vs # in Markdown), |_. for table headers, and *bold* for bold text. Textile has better built-in table support with column alignment and spanning. Markdown is more widely adopted, but Textile remains the standard in Redmine.

Q: Can Textile handle large database schemas?

A: Yes! Large schemas are organized with h1/h2/h3 headings for each table, making the document navigable. Textile supports tables of any size, and Redmine can generate a table of contents from Textile headings using the macro, making it easy to navigate extensive schema documentation.

Q: What platforms support Textile besides Redmine?

A: Textile is supported by Textpattern CMS, various Ruby on Rails applications, Movable Type, and several wiki engines. Libraries exist for Ruby (RedCloth), PHP (php-textile), Python (textile), Java, and JavaScript (textile-js), allowing Textile processing in many development environments.

Q: Are foreign key relationships documented?

A: Yes! Foreign key relationships are documented both in the table's constraints column and as a separate relationships section. In Redmine, you can create wiki links to related table documentation pages, making the relationship references clickable for easy navigation between table definitions.