Convert SQL to ADOC

Why Convert SQL to ADOC?

Converting SQL files to AsciiDoc format transforms raw database scripts into professional, well-structured documentation. AsciiDoc's powerful markup capabilities allow SQL code to be presented with syntax highlighting, explanatory text, table of contents, and cross-references, making it ideal for creating database documentation, migration guides, and schema reference manuals.

SQL scripts, while essential for database operations, are often difficult to navigate and understand without context. By converting to AsciiDoc, each SQL statement can be wrapped in properly formatted code blocks with language-specific syntax highlighting, accompanied by descriptions, notes, and warnings that help team members understand the purpose and impact of each database operation.

AsciiDoc is particularly well-suited for SQL documentation because it supports source code blocks with language declarations (e.g., [source,sql]), which enables automatic syntax highlighting when rendered to HTML or PDF. This makes complex queries, stored procedures, and schema definitions much easier to read and review compared to raw SQL files.

For teams maintaining database infrastructure, converting SQL to AsciiDoc creates living documentation that can be version-controlled alongside code, rendered into multiple output formats (HTML, PDF, EPUB), and integrated into existing documentation pipelines using tools like Asciidoctor, Antora, or GitHub's built-in AsciiDoc rendering.

Key Benefits of Converting SQL to ADOC:

• Syntax Highlighting: SQL code rendered with proper color coding for keywords, strings, and comments
• Structured Documentation: Organize scripts with headings, sections, and table of contents
• Multi-Format Output: Generate HTML, PDF, EPUB, and DocBook from a single source
• Admonitions: Add NOTE, TIP, WARNING, and CAUTION blocks for important SQL considerations
• Version Control: Plain text format works perfectly with Git and other VCS systems
• Cross-References: Link between related tables, procedures, and schema sections
• Professional Output: Generate publication-quality database documentation

Practical Examples

Example 1: Schema Definition Documentation

Input SQL file (schema.sql):

-- Users table for application authentication
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- User roles for access control
CREATE TABLE roles (
    id SERIAL PRIMARY KEY,
    role_name VARCHAR(30) NOT NULL
);

Output AsciiDoc file (schema.adoc):

= Database Schema Documentation

== Users Table

Users table for application authentication.

[source,sql]
----
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
----

== Roles Table

User roles for access control.

[source,sql]
----
CREATE TABLE roles (
    id SERIAL PRIMARY KEY,
    role_name VARCHAR(30) NOT NULL
);
----

Example 2: Query Documentation

Input SQL file (reports.sql):

-- Monthly sales report
SELECT p.product_name,
       SUM(o.quantity) AS total_sold,
       SUM(o.quantity * p.price) AS revenue
FROM orders o
JOIN products p ON o.product_id = p.id
WHERE o.order_date >= '2025-01-01'
GROUP BY p.product_name
ORDER BY revenue DESC;

Output AsciiDoc file (reports.adoc):

= SQL Reports

== Monthly Sales Report

[source,sql]
----
SELECT p.product_name,
       SUM(o.quantity) AS total_sold,
       SUM(o.quantity * p.price) AS revenue
FROM orders o
JOIN products p ON o.product_id = p.id
WHERE o.order_date >= '2025-01-01'
GROUP BY p.product_name
ORDER BY revenue DESC;
----

NOTE: This report aggregates all sales
from January 2025 onward.

Example 3: Migration Script Documentation

Input SQL file (migration.sql):

-- Add phone column to customers
ALTER TABLE customers
ADD COLUMN phone VARCHAR(20);

-- Create index for faster lookups
CREATE INDEX idx_customers_phone
ON customers(phone);

-- Insert default values
UPDATE customers SET phone = 'N/A'
WHERE phone IS NULL;

Output AsciiDoc file (migration.adoc):

= Migration Script

== Add Phone Column to Customers

[source,sql]
----
ALTER TABLE customers
ADD COLUMN phone VARCHAR(20);
----

== Create Index for Faster Lookups

[source,sql]
----
CREATE INDEX idx_customers_phone
ON customers(phone);
----

== Insert Default Values

[source,sql]
----
UPDATE customers SET phone = 'N/A'
WHERE phone IS NULL;
----

Frequently Asked Questions (FAQ)

Q: What is AsciiDoc?

A: AsciiDoc is a lightweight markup language for writing structured content like documentation, articles, and books. It can be processed by Asciidoctor into HTML, PDF, EPUB, and other formats. It is more feature-rich than Markdown and commonly used for technical documentation.

Q: Will my SQL syntax highlighting be preserved?

A: Yes! SQL code blocks in AsciiDoc use the [source,sql] directive, which enables automatic syntax highlighting when rendered to HTML or PDF using tools like Asciidoctor with a syntax highlighter such as Rouge or Pygments.

Q: Can I convert large SQL dump files?

A: Yes, our converter handles SQL files of various sizes. For very large database dump files, the conversion may take a bit longer but will complete successfully. The resulting AsciiDoc file will be well-structured and organized.

Q: How are SQL comments handled in the conversion?

A: SQL comments (both single-line -- and multi-line /* */) are preserved in the converted AsciiDoc output. They can be rendered as explanatory text or kept within code blocks depending on context.

Q: What is the difference between ADOC and AsciiDoc?

A: ADOC is simply the file extension (.adoc) for AsciiDoc documents. AsciiDoc is the markup language itself, while .adoc is the most common file extension used for AsciiDoc files. Other extensions include .asciidoc and .asc.

Q: Can I render the ADOC output as a website?

A: Absolutely! AsciiDoc files can be rendered to HTML using Asciidoctor. You can also use Antora to build complete documentation websites from AsciiDoc files. GitHub and GitLab also render .adoc files natively in repositories.

Q: Does the converter handle vendor-specific SQL syntax?

A: Yes, the converter processes the SQL file content as-is, preserving all vendor-specific syntax for MySQL, PostgreSQL, Oracle, SQL Server, or any other database system. The SQL code is wrapped in proper AsciiDoc code blocks.

Q: Can I edit the AsciiDoc output?

A: Yes! AsciiDoc is a plain text format that can be edited in any text editor. Popular editors with AsciiDoc support include VS Code (with AsciiDoc extension), IntelliJ IDEA, Atom, and Sublime Text. You can add additional sections, notes, and formatting after conversion.