How to Fine-Tune Text2SQL Models Using DB-GPT-Hub for Custom Database Schemas

Fine-tune Text2SQL models using DB-GPT-Hub by converting your schema to Spider format, running LoRA/QLoRA training on CodeLlama or similar LLMs, and deploying the adapter via the dbgpt_hub Python package.

The DB-GPT repository provides a dedicated Text2SQL fine-tuning pipeline through its companion project DB-GPT-Hub. This workflow transforms your custom database schema into a Spider-style training dataset and applies parameter-efficient fine-tuning (LoRA/QLoRA) to produce a model that generates accurate SQL for your specific schema. According to the source code in docs/docs/application/fine_tuning_manual/text_to_sql.md, this approach achieves approximately 0.789 execution accuracy on Spider benchmarks when using CodeLlama-13B-Instruct with LoRA.

Understanding the DB-GPT-Hub Fine-Tuning Pipeline

The fine-tuning process consists of three distinct stages, each handled by specific components within the DB-GPT-Hub repository.

Stage 1: Data Preparation

First, you must convert your database schema and natural language-SQL pairs into the Spider JSON format required by the trainer. The scripts/prepare_data.py script extracts table definitions, column metadata, and foreign key relationships from your schema file, producing train.json and dev.json files containing the structured training examples.

Stage 2: LoRA/QLoRA Training

The training stage uses LoRA (Low-Rank Adaptation) or QLoRA (quantized LoRA) to fine-tune only a small set of adapter parameters while keeping the base LLM frozen. This dramatically reduces memory requirements and training time. The scripts/train_lora.sh and scripts/train_qlora.sh shell scripts wrap the HuggingFace accelerate and peft libraries to handle the distributed training loop.

Stage 3: Model Deployment

After training, the adapter weights are packaged as a HuggingFace checkpoint. You can load this fine-tuned model in DB-GPT using the dbgpt_hub Python package, which provides the load_text2sql_model() API to seamlessly integrate the adapter with the base LLM.

Step-by-Step Guide to Fine-Tune Text2SQL Models

Follow these concrete steps to fine-tune a Text2SQL model for your specific database schema.

Clone the Repository and Set Up Environment

Start by cloning the DB-GPT-Hub repository and creating a dedicated Conda environment as recommended in docs/docs/application/fine_tuning_manual/text_to_sql.md.

git clone https://github.com/eosphoros-ai/DB-GPT-Hub.git
cd DB-GPT-Hub

conda create -n dbgpt-hub python=3.10
conda activate dbgpt-hub
pip install -r requirements.txt

Prepare Your Database Schema

Create a YAML or JSON file describing your database tables, columns, and relationships. Then convert this to the Spider format using the provided helper script.

python scripts/prepare_data.py \
    --schema_path ./my_schema.yaml \
    --output_dir ./data/spider/

This generates train.json and dev.json files containing entries with question, query, and db_id fields.

Run LoRA Fine-Tuning

Execute the training script, specifying your base model and training data. The example below uses CodeLlama-13B-Instruct, which the documentation notes achieves strong execution accuracy.

bash scripts/train_lora.sh \
    --model_name codellama/CodeLlama-13b-Instruct-hf \
    --train_data ./data/spider/train.json \
    --output_dir ./outputs/lora_codellama13b

For quantized training on limited GPU memory, use train_qlora.sh instead.

Push Adapter to HuggingFace

Upload your trained adapter to HuggingFace Hub for easy access from DB-GPT.

huggingface-cli login
cd ./outputs/lora_codellama13b
git init
git remote add origin https://huggingface.co/your-username/codellama13b-sql-lora
git lfs install
git add .
git commit -m "Fine-tuned Text2SQL adapter for custom schema"
git push origin main

Load Fine-Tuned Model in DB-GPT

Install the dbgpt_hub package and load your fine-tuned model within the DB-GPT framework, as documented in docs/docs/application/fine_tuning_manual/dbgpt_hub.md.

from dbgpt_hub import load_text2sql_model
from dbgpt.agent import Text2SQLAgent

# Load the adapter-augmented LLM

llm = load_text2sql_model(
    model_name="your-username/codellama13b-sql-lora",
    base_model="codellama/CodeLlama-13b-Instruct-hf"
)

# Initialize the Text2SQL agent with your schema

agent = Text2SQLAgent(llm=llm, schema_path="my_schema.yaml")

# Generate SQL from natural language

question = "Show me the top 5 customers by total order amount"
sql = agent.generate_sql(question)
print(f"Generated SQL: {sql}")

Complete End-to-End Script

For automation, combine all steps into a single bash script:

#!/usr/bin/env bash
set -e

# 1. Clone hub

git clone https://github.com/eosphoros-ai/DB-GPT-Hub.git
cd DB-GPT-Hub

# 2. Environment

conda create -n dbgpt-hub python=3.10 -y
conda activate dbgpt-hub
pip install -r requirements.txt

# 3. Prepare data (assumes my_schema.yaml exists)

python scripts/prepare_data.py \
    --schema_path ./my_schema.yaml \
    --output_dir ./data/spider/

# 4. Fine-tune with LoRA

bash scripts/train_lora.sh \
    --model_name codellama/CodeLlama-13b-Instruct-hf \
    --train_data ./data/spider/train.json \
    --output_dir ./outputs/lora_codellama13b

# 5. Push to HuggingFace

huggingface-cli login
cd ./outputs/lora_codellama13b
git init
git remote add origin https://huggingface.co/$HF_USER/codellama13b-sql-lora
git lfs install
git add . && git commit -m "Fine-tuned Text2SQL adapter"
git push origin main

Key Files and Resources

Understanding these specific files from the DB-GPT and DB-GPT-Hub repositories helps navigate the fine-tuning process:

• docs/docs/application/fine_tuning_manual/text_to_sql.md – The primary guide explaining the Text2SQL fine-tuning pipeline, environment setup, and the three-stage workflow (data preparation, training, deployment).

• docs/docs/application/fine_tuning_manual/dbgpt_hub.md – Documentation for the dbgpt_hub pip package that provides the load_text2sql_model() API for integrating fine-tuned adapters into DB-GPT.

• scripts/prepare_data.py – Converts custom database schemas into Spider JSON format required for training.

• scripts/train_lora.sh and scripts/train_qlora.sh – Shell scripts wrapping the LoRA and QLoRA training loops using HuggingFace Accelerate and PEFT.

• docs/docs/modules/benchmark.md – Describes the benchmark module for evaluating execution accuracy of fine-tuned models on held-out test sets.

Summary

Fine-tuning Text2SQL models using DB-GPT-Hub involves three core stages: preparing your schema data in Spider format, training LoRA/QLoRA adapters on a base LLM like CodeLlama-13B-Instruct, and deploying the resulting adapter through the dbgpt_hub package.

• Data preparation uses scripts/prepare_data.py to convert custom schemas into the required JSON structure.
• Training leverages train_lora.sh or train_qlora.sh for parameter-efficient fine-tuning that preserves the base model while learning schema-specific SQL generation.
• Deployment requires installing dbgpt_hub and calling load_text2sql_model() to integrate the adapter with DB-GPT's Text2SQLAgent.

Frequently Asked Questions

What base models work best for Text2SQL fine-tuning in DB-GPT-Hub?

CodeLlama-13B-Instruct is the recommended base model according to the documentation in text_to_sql.md, achieving approximately 0.789 execution accuracy on Spider benchmarks when fine-tuned with LoRA. Other code-focused LLMs like StarCoder or DeepSeek-Coder should also work, provided they are instruction-tuned variants compatible with the HuggingFace PEFT library used by the training scripts.

How much GPU memory is required for fine-tuning?

QLoRA (4-bit quantization) enables fine-tuning on consumer GPUs with as little as 16-24GB VRAM, while standard LoRA (8-bit) typically requires 24-40GB depending on the base model size. The train_qlora.sh script specifically configures bitsandbytes 4-bit quantization to reduce memory footprint during the training loop.

Can I fine-tune on a schema without existing NL-SQL pairs?

While the pipeline expects Spider-format JSON with question and query fields, you can generate synthetic training data using template-based augmentation or LLM-generated pairs from your schema. The prepare_data.py script handles the structural conversion, but you must provide the natural language questions and corresponding SQL queries, either manually curated or synthetically generated from your schema definition.

How do I evaluate the fine-tuned model's accuracy?

DB-GPT-Hub includes a benchmark module documented in docs/docs/modules/benchmark.md. Run scripts/run_benchmark.py with your model name and a held-out test set to calculate execution accuracy, which measures whether the generated SQL produces the correct result set when executed against the actual database, rather than just string matching.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}