querycraft 0.0.56

Provide usefully SQL classes and functions to execute SQL queries step by step

QueryCraft

[TOC]

Le nom ?

Un nom en anglais qui évoque l'idée de "façonner" ou "construire" des requêtes SQL de manière intuitive, parfait pour une approche pédagogique. (GPT 4o ;-) )

Objectifs

L'objectif de cette bibliothèque est de proposer des classes Python permettant de manipuler des requêtes SQL. Elle propose aussi des applications pour décomposer l'exécution d'une requête SQL sur une base de données PostgreSQL, MySQL ou SQLite.

Fonctionnalités

• Analyse de requêtes SQL : Analysez et comprenez la structure de vos requêtes SQL.
• Décomposition de requêtes : Décomposez vos requêtes SQL en étapes simples pour une meilleure compréhension.
• Support multi-SGBD : Compatible avec PostgreSQL, MySQL et SQLite.
• Interface en ligne de commande : Utilisez l'application en ligne de commande pour analyser et décomposer vos requêtes SQL.
• Aide de l'IA : Comprenez vos erreurs SQL grâce à l'aide de l'IA.

Limitations

Limitations liées à SQL et aux SGBD

• Opérateurs SQL non couverts : Certains opérateurs SQL avancés peuvent ne pas être entièrement pris en charge, en particulier les opérateurs ensemblistes. Par exemple, les opérateurs INTERSECT, EXCEPT et UNION ne sont pas pris en charge. Les sous-requêtes dans le 'From' sont prises en charges, mais pas les sous-requêtes dans le 'Where' et le 'Having' (pas de pas à pas possible).
• Support limité des fonctions SQL : Certaines fonctions SQL avancées peuvent ne pas être entièrement prises en charge.
• Compatibilité avec les versions de SGBD : La compatibilité avec les versions spécifiques de PostgreSQL, MySQL et SQLite peut varier.

Problème avec la version de Python

QueryCraft fonctionne avec Python 3.11. A ce jour (13/03/2025), une bibliothèque (psycopg2) pose des problèmes avec Python 3.12. Il est donc préférable de rester pour l'instant sur la version 3.11.

Installation

Après téléchargement depuis Gitlab :

git clone https://gitlab.univ-nantes.fr/ls2n-didactique/querycraft.git
cd querycraft
pip install -e .

Sans téléchargement depuis Gitlab :

pip install querycraft

Mise à jour

pip install --upgrade querycraft  

Usage

Pour voir les commandes et comprendre l'utilisation avec exemples voir : HOW_TO_USE La requête devra être écrite entre double quotes " ".

PostgreSQL

usage: pgsql-sbs [-h] -d DB [-u USER] [-p PASSWORD] [--host HOST] [--port PORT] [-v] (-b | -f FILE | -s SQL)

Effectue l'exécution pas à pas d'une requête sur PostgreSQL (c) E. Desmontils, Nantes Université, 2024

options:
  -h, --help            show this help message and exit
  -d DB, --db DB        database name
  -u USER, --user USER  database user (by default desmontils-e)
  -p PASSWORD, --password PASSWORD
                        database password
  --host HOST           database host (by default localhost)
  --port PORT           database port (by default 5432)
  -v, --verbose         verbose mode
  -f FILE, --file FILE  sql file
  -s SQL, --sql SQL     sql string
  -b --describe         DB Schema
  -nsbs                 don't show step by step.

SQLite

usage: sqlite-sbs [-h] -d DB [-v] (-b | -f FILE | -s SQL)

Effectue l'exécution pas à pas d'une requête sur SQLite (c) E. Desmontils, Nantes Université, 2024

options:
  -h, --help            show this help message and exit
  -d DB, --db DB        database name
  -v, --verbose         verbose mode
  -f FILE, --file FILE  sql file
  -s SQL, --sql SQL     sql string
  -b, --describe        DB Schema
  -nsbs                 don't show step by step.

MySQL

usage: mysql-sbs [-h] -d DB [-u USER] [-p PASSWORD] [--host HOST] [--port PORT] [-v] (-b | -f FILE | -s SQL) 

Effectue l'exécution pas à pas d'une requête sur MySQL (c) E. Desmontils, Nantes Université, 2024

options:
  -h, --help            show this help message and exit
  -d DB, --db DB        database name
  -u USER, --user USER  database user (by default desmontils-e)
  -p PASSWORD, --password PASSWORD
                        database password
  --host HOST           database host (by default localhost)
  --port PORT           database port (by default 3306)
  -v, --verbose         verbose mode
  -f FILE, --file FILE  sql file
  -s SQL, --sql SQL     sql string
  -b, --describe        DB Schema
  -nsbs                 don't show step by step.

LRS

L'outil peut être interfacé avec un LRS compatible XAPI (testé avec Veracity ; https://lrs.io/home ; https://lrs.io/home/download).
Il suffit de spécifier les paramètres de connection à travers les paramètres "--lrs-*". L'activation elle-même est donnée par le paramètre "--lrs".

Aide de l'IA

Pour bénéficier de l'aide de l'IA, il faut installer Ollama (https://ollama.com/), récupérer le modèle de langage "codellama:7b" (modèle par défaut) puis lancer le serveur Ollama. Soit :

ollama pull codellama:7b
ollama serve

NB : pour l'instant, le modèle n'est pas facilement modifiable. Il est possible de le changer dans le code source. Il suffit pour cela d'aller dans le fichier "querycraft/config/config-sbs.cfg", de trouver la section "IA" puis de modifier la valeur de la clé "model".

Article de recherche et conférences

• Emmanuel Desmontils, Laura Monceaux. Enseigner SQL en NSI. Atelier « Apprendre la Pensée Informatique de la Maternelle à l'Université », dans le cadre de la conférence Environnements Informatiques pour l'Apprentissage Humain (EIAH), Jun 2023, Brest, France. pp.17-24. https://hal.science/hal-04144210 https://apimu.gitlabpages.inria.fr/site/ateliers/pdf-apimu23/APIMUEIAH_2023_paper_3.pdf

• Emmanuel Desmontils. Enseigner SQL en NSI : typologie et cas de la jointure. Journée des enseignants de SNT et de NSI 2024, Académie de la Réunion et IREMI de La Réunion, Dec 2024, Saint-Denis (La Réunion), France. https://hal.science/hal-05030037v1

Génération de la documentation

pdoc3 --html --force -o doc querycraft

Remerciements

• Wiktoria SLIWINSKA, étudiante ERASMUS en licence Informatique à l'Université de Nantes en 2023-2024, pour son aide à la conception du POC initial.
• Baptiste GIRARD, étudiant en licence Informatique à l'Université de Nantes en 2024-2025, pour son aide à la fiabilisation de l'outil.

Autres sites

Sur PyPi : https://pypi.org/project/querycraft/

HAL (pour citer dans une publication) : https://hal.science/hal-04964895

Licence

(C) E. Desmontils, Nantes Université, 2024, 2025

Ce logiciel est distribué sous licence GPLv3.