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

> Learn to fine-tune Text2SQL models with DB-GPT-Hub. Convert your schema, train LLMs like CodeLlama using LoRA/QLoRA, and deploy adapters for custom database schemas.

- Repository: [eosphoros/DB-GPT](https://github.com/eosphoros-ai/db-gpt)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/scripts/prepare_data.py) script extracts table definitions, column metadata, and foreign key relationships from your schema file, producing [`train.json`](https://github.com/eosphoros-ai/DB-GPT/blob/main/train.json) and [`dev.json`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/scripts/train_lora.sh) and [`scripts/train_qlora.sh`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/docs/docs/application/fine_tuning_manual/text_to_sql.md).

```bash
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.

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

```

This generates [`train.json`](https://github.com/eosphoros-ai/DB-GPT/blob/main/train.json) and [`dev.json`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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
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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/train_qlora.sh) instead.

### Push Adapter to HuggingFace

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

```bash
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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/docs/docs/application/fine_tuning_manual/dbgpt_hub.md).

```python
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:

```bash
#!/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/scripts/prepare_data.py)** – Converts custom database schemas into Spider JSON format required for training.

- **[`scripts/train_lora.sh`](https://github.com/eosphoros-ai/DB-GPT/blob/main/scripts/train_lora.sh)** and **[`scripts/train_qlora.sh`](https://github.com/eosphoros-ai/DB-GPT/blob/main/scripts/train_qlora.sh)** – Shell scripts wrapping the LoRA and QLoRA training loops using HuggingFace Accelerate and PEFT.

- **[`docs/docs/modules/benchmark.md`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/scripts/prepare_data.py) to convert custom schemas into the required JSON structure.
- **Training** leverages [`train_lora.sh`](https://github.com/eosphoros-ai/DB-GPT/blob/main/train_lora.sh) or [`train_qlora.sh`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/docs/docs/modules/benchmark.md). Run [`scripts/run_benchmark.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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.