MockSQL

Couche de tests unitaires native pour les data engineers. MockSQL choisit un fichier .sql, génère automatiquement des jeux de données de test cohérents via LLM, les exécute localement sur DuckDB (0 € facturé sur BigQuery), attribue un verdict argumenté à chaque test, et suggère les cas limites non couverts.

Ce qui distingue MockSQL des bibliothèques de mocking SQL

Les bibliothèques de mocking SQL existantes vous demandent d'écrire les données de test à la main dans du code Python. MockSQL prend le contrepied :

	Bibliothèques de mocking SQL	MockSQL
Données de test	Écrites manuellement par l'ingé	Générées automatiquement par LLM
Couverture	Aucune détection — l'ingé doit y penser	6 axes (NULL, vide, ex æquo…) + suggestions
Qualité du test	Pas d'évaluation	Verdict LLM (bon / insuffisant / incorrect)
Interface	Bibliothèque Python dans du code de test	UI dédiée (GenerateView → TestsView)
Dérive	Inexistante	Roadmap : alerte si le SQL prod a changé
Moteur SQL	Un connecteur par DB	DuckDB unifié — aucun coût BigQuery

MockSQL se décline en deux modes :

CLI (mocksql) — usage standalone directement sur tes fichiers .sql locaux
Web Hub — interface complète avec historique, verdicts, couverture et collaboration

Démarrage rapide (CLI)

pip install dist/mocksql-*.whl
export PROJECT_ID=<votre-projet-gcp>

# 1. Initialiser un projet
mocksql init

# 2. Générer des tests pour un modèle SQL
mocksql generate models/my_model.sql

Voir la section CLI pour le détail.

Prérequis

Python 3.11+
Poetry (pip install poetry) — pour le développement depuis les sources
Node.js 18+ — pour builder le frontend (pas requis à l'exécution)
Google Cloud SDK

1. Authentification Google Cloud

Les modèles Gemini (VertexAI) et BigQuery utilisent les credentials applicatifs Google :

gcloud auth application-default login
gcloud config set project <PROJECT_ID>

2. Permissions IAM requises

Le compte utilisé (utilisateur ou service account) doit disposer des rôles suivants sur le projet GCP :

Rôle	Utilité
BigQuery Data Viewer (`roles/bigquery.dataViewer`)	Lecture du schéma des tables
BigQuery User (`roles/bigquery.user`)	Lancement des jobs / dry-run des requêtes
AI Platform Developer (`roles/aiplatform.user`)	Appels aux modèles Vertex AI (Gemini)

Activation des modèles Gemini (étape unique par projet) Les rôles IAM ne suffisent pas : même avec roles/aiplatform.user, les modèles Gemini retournent une erreur 404 si l'accès n'a pas été activé dans le Model Garden. Dans la console GCP, ouvrez Model Garden, cherchez un modèle Gemini (ex. Gemini 2.0 Flash Lite) et acceptez les conditions d'utilisation. Cette opération est unique par projet GCP et ne peut pas être réalisée via gcloud.

Option A — Compte utilisateur (développement local)

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member='user:<votre-email@domaine.com>' \
  --role='roles/bigquery.dataViewer'

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member='user:<votre-email@domaine.com>' \
  --role='roles/bigquery.user'

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member='user:<votre-email@domaine.com>' \
  --role='roles/aiplatform.user'

Option B — Service account (CI/CD, Cloud Run)

Créez un service account et attribuez-lui les mêmes rôles :

SA_EMAIL="mocksql-sa@<PROJECT_ID>.iam.gserviceaccount.com"

gcloud iam service-accounts create mocksql-sa \
  --project=<PROJECT_ID> \
  --display-name="MockSQL service account"

for ROLE in roles/bigquery.dataViewer roles/bigquery.user roles/aiplatform.user; do
  gcloud projects add-iam-policy-binding <PROJECT_ID> \
    --member="serviceAccount:${SA_EMAIL}" \
    --role="${ROLE}"
done

Générez une clé JSON et pointez-y via GOOGLE_APPLICATION_CREDENTIALS :

gcloud iam service-accounts keys create ~/keys/mocksql-sa.json \
  --iam-account="${SA_EMAIL}"

# back/.env
GOOGLE_APPLICATION_CREDENTIALS=/chemin/vers/mocksql-sa.json

Erreur fréquente : Forbidden: Access Denied: bigquery.jobs.create permission → Le rôle BigQuery User est manquant sur le projet.

3. Configuration du backend

3.1 Créer le fichier `.env`

cp back/.env.example back/.env

Variables essentielles :

# Google Cloud
PROJECT_ID=<votre-projet-gcp>
GOOGLE_CLOUD_PROJECT=<votre-projet-gcp>
GOOGLE_CLOUD_LOCATION=us-central1

# BigQuery (import de schémas)
BQ_SCHEMA_BILLING_PROJECT=<votre-projet-gcp>
BQ_REGION=US

# LLM (peut être overridé dans mocksql.yml via llm.model)
DEFAULT_MODEL_NAME=gemini-2.0-flash-lite

# Base de données locale
DUCKDB_PATH=data/mocksql.duckdb

# Sécurité
SECRET_KEY=<clé-secrète>
API_SECRET_KEY=<clé-api>

# CORS
FRONT_URL=http://127.0.0.1:3000

3.2 Installer les dépendances

cd back
python -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows
.\.venv\Scripts\activate

pip install poetry && poetry install

3.3 Lancer le serveur

uvicorn server:app --port 8080 --reload

Le backend est accessible sur http://localhost:8080.

4. CLI

Variables d'environnement requises

Pour l'usage CLI standalone (sans back/.env), définir les variables suivantes dans votre shell ou un fichier .env à la racine de votre projet :

PROJECT_ID=<votre-projet-gcp>
GOOGLE_CLOUD_PROJECT=<votre-projet-gcp>
GOOGLE_CLOUD_LOCATION=us-central1
DUCKDB_PATH=data/mocksql.duckdb

GOOGLE_CLOUD_LOCATION est obligatoire pour les appels Vertex AI — sans elle, les modèles Gemini ne sont pas accessibles.

`mocksql init`

Initialise un projet MockSQL et génère mocksql.yml :

mocksql init
# ou dans un sous-dossier
mocksql init --path ./mon_projet

Exemple de mocksql.yml généré :

version: "2"
dialect: bigquery          # bigquery | postgres
models_path: ./models
llm:
  provider: vertexai       # vertexai | openai
  model: gemini-2.0-flash  # override du modèle par défaut (optionnel)
  streaming: false         # désactive le streaming LLM (optionnel)
schema_cache: .mocksql/schema_cache.json

Clés de la section llm :

Clé	Défaut	Description
`provider`	`vertexai`	Backend LLM (`vertexai` ou `openai`)
`model`	`gemini-2.0-flash-lite`	Nom du modèle — prioritaire sur `DEFAULT_MODEL_NAME`
`streaming`	`false`	Active ou désactive le streaming token par token

`mocksql generate`

Parse un modèle SQL, résout les schémas des tables sources et génère des données de test :

mocksql generate models/orders.sql
# options
mocksql generate models/orders.sql --config mocksql.yml --output .mocksql/tests

Les schémas récupérés sont mis en cache dans .mocksql/schema_cache.json — les runs suivants n'interrogent plus BigQuery.

Outputs dans .mocksql/tests/ :

<model>_data.json — données de test (tables d'entrée)
<model>_results.json — résultats d'exécution DuckDB

Préprocesseur SQL — variables et templates

Si tes fichiers .sql contiennent des variables non-parsables (@start_date, {{ ds }}, macros dbt…), déclare une fonction Python dans mocksql.yml pour les remplacer avant analyse :

# mocksql.yml
preprocessor_fn: "preprocessors:replace_vars"   # module:fonction, relatif au mocksql.yml

Crée preprocessors.py à côté de mocksql.yml :

import re

def replace_vars(sql: str) -> str:
    defaults = {"start_date": "'2024-01-01'", "end_date": "'2024-12-31'"}
    return re.sub(r"@(\w+)", lambda m: defaults.get(m.group(1), "NULL"), sql)

La fonction reçoit le SQL brut et retourne le SQL transformé. Elle est appelée aussi bien par mocksql generate que par l'UI lors de la lecture des modèles.

Exemple

Un exemple complet est disponible dans examples/jaffle_shop/ :

mocksql generate examples/jaffle_shop/models/orders.sql \
  --config examples/jaffle_shop/mocksql.yml

5. Web UI

MockSQL distribue deux wheels distincts :

Package	Contenu	Usage
`mocksql`	CLI (`mocksql init`, `mocksql generate`)	CI/CD, sans UI
`mocksql-ui`	CLI + serveur web + assets React	Installation complète

Installer depuis les wheels

# CLI uniquement
pip install dist/mocksql-*.whl

# CLI + UI
pip install dist/mocksql-*.whl dist/mocksql_ui-*.whl

Builder les wheels

cd back

# CLI uniquement
make build-cli

# CLI + UI (build React inclus, Node.js requis)
make build-ui   # produit dist/mocksql-*.whl et dist/mocksql_ui-*.whl

Lancer l'interface

mocksql ui                  # http://localhost:8080/static/
mocksql ui --port 4000      # port personnalisé
mocksql ui --no-browser     # sans ouverture automatique du navigateur

Node.js n'est pas requis à l'exécution — uniquement pour le build.

Développement frontend (hot-reload)

cd front
npm ci
npm start      # http://localhost:3000 (proxy vers le backend sur :8080)

Structure du projet

back/       # FastAPI + LangGraph + CLI
  cli/      # mocksql CLI (main.py, generate.py)
  ui/       # package mocksql-ui (serveur + assets React)
front/      # React 18 + TypeScript + Redux (Web Hub)
examples/   # Exemples de projets MockSQL
docs/       # Documentation du workflow

How to contribute

Commandes backend (depuis `back/`)

Commande	Description
`make style`	Lint (ruff) + format check + code mort (vulture)
`make format`	Auto-format et auto-fix ruff
`make test`	Tests pytest
`make check`	`style` + `test`

Hook pre-commit (recommandé)

pip install pre-commit
pre-commit install

make style sera exécuté automatiquement à chaque git commit sur les fichiers Python modifiés.

Name		Name	Last commit message	Last commit date
Latest commit History 65 Commits
.github		.github
back		back
docs		docs
front		front
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MockSQL

Ce qui distingue MockSQL des bibliothèques de mocking SQL

Démarrage rapide (CLI)

Prérequis

1. Authentification Google Cloud

2. Permissions IAM requises

Option A — Compte utilisateur (développement local)

Option B — Service account (CI/CD, Cloud Run)

3. Configuration du backend

3.1 Créer le fichier `.env`

3.2 Installer les dépendances

3.3 Lancer le serveur

4. CLI

Variables d'environnement requises

`mocksql init`

`mocksql generate`

Préprocesseur SQL — variables et templates

Exemple

5. Web UI

Installer depuis les wheels

Builder les wheels

Lancer l'interface

Développement frontend (hot-reload)

Structure du projet

How to contribute

Commandes backend (depuis `back/`)

Hook pre-commit (recommandé)

About

Uh oh!

Releases 6

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

MockSQL

Ce qui distingue MockSQL des bibliothèques de mocking SQL

Démarrage rapide (CLI)

Prérequis

1. Authentification Google Cloud

2. Permissions IAM requises

Option A — Compte utilisateur (développement local)

Option B — Service account (CI/CD, Cloud Run)

3. Configuration du backend

3.1 Créer le fichier .env

3.2 Installer les dépendances

3.3 Lancer le serveur

4. CLI

Variables d'environnement requises

mocksql init

mocksql generate

Préprocesseur SQL — variables et templates

Exemple

5. Web UI

Installer depuis les wheels

Builder les wheels

Lancer l'interface

Développement frontend (hot-reload)

Structure du projet

How to contribute

Commandes backend (depuis back/)

Hook pre-commit (recommandé)

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

3.1 Créer le fichier `.env`

`mocksql init`

`mocksql generate`

Commandes backend (depuis `back/`)

Packages