MaskSQL is a privacy-preserving framework for LLM-based text-to-SQL that uses schema masking and progressive unmasking to protect sensitive database information while maintaining high query accuracy.

• Installation
• Running MaskSQL
• Documentation
• Citation

Setup the env variables:

cp .env.example .env

Fill in the required variables

Run the MaskSQL using the published Docker image:

docker compose run --rm masksql python main.py

Build the Docker image locally:

docker compose -f docker-compose.local.yaml build

You can run the MaskSQL container and then have a shell access to the container:

docker compose up -d
# Or
docker compose -f docker-compose.local.yaml up -d

After the container started successfully you can have a shell access:

docker compose exec -it masksql bash
# Or
docker compose -f docker-compose.local.yaml exec -it masksql bash

• Python 3.11
• uv package manager

Install dependencies and activate the virtual environment:

uv sync --dev
source .venv/bin/activate

Download and extract the dataset:

wget -O data.zip "https://www.dropbox.com/scl/fi/vtraf79vfi1x105veaflk/data.zip?rlkey=7yq6d46aer6h45pdihrc9rht1&st=zdac3rqx&dl=0"
unzip data.zip

Expected directory structure:

data/
├── databases/
├── 1_input.json
└── ...

Create a .env file from the template:

cp .env.example .env

Required:

• OPENAI_API_KEY: Your OpenRouter API key

Optional:

• LIMIT: Number of dataset entries to process (e.g., LIMIT=10)
• START: Starting index in the dataset (default: 0)

To configure the MaskSQL, uses the configs/conf.yaml file by default. You can pass in arbitrary config files using the --config option of the CLI interface.

MaskSQL requires RESDSQL for initial schema filtering. Follow the RESDSQL setup instructions to generate the required files.

Execute the MaskSQL pipeline:

python3 main.py

or to clean previous outputs and rerun:

python3 main.py --clean

• MaskSQL Framework - Overview of the framework architecture
• Pipeline Stages - Detailed explanation of each pipeline stage

If you use MaskSQL in your research, please cite our paper:

@article{abedini2025masksql,
  title={MaskSQL: Safeguarding Privacy for LLM-Based Text-to-SQL via Abstraction},
  author={Abedini, Sepideh and Mohapatra, Shubhankar and Emerson, DB and Shafieinejad, Masoumeh and Cresswell, Jesse C and He, Xi},
  journal={arXiv preprint arXiv:2509.23459},
  year={2025}
}

Paper: https://arxiv.org/abs/2509.23459