Développé par gopu.inc | Statut : Bêta Active - En développement

GSQL est un projet en développement actif (version bêta). Il n'est pas encore prêt pour une utilisation en production critique.

Ce que GSQL est VRAIMENT : - ✅ Une surcouche Python puissante pour SQLite avec un shell interactif, un cache et des outils de productivité. - ✅ Un projet open-source qui évolue rapidement grâce à la communauté.

Bugs & Limitations Actuelles (à connaître avant d'utiliser) : - 🔸 Transactions : L'API transactionnelle native (db.begin_transaction()) a des bugs. Il faut utiliser les commandes SQL brutes BEGIN/COMMIT (un workaround est fourni ci-dessous). - 🔸 Guillemets : Certains caractères dans les chaînes peuvent causer des problèmes de parsing dans le shell interactif. - 🔸 Fonctionnalités expérimentales : Les modules NLP (gsql.nlp) et les backends de stockage alternatifs (YAML, mémoire) sont en prototype et non stabilisés.

Notre philosophie : Apporter la productivité du Python et la clarté d'une interface moderne à la robustesse de SQLite.

pip install gsql

Via Conda (à partir du canal gopu-inc)

conda install -c gopu-inc gsql

Depuis les sources (pour les contributeurs)

git clone https://github.com/gopu-inc/gsql.git
cd gsql
pip install -e .

Avec Docker

docker pull ceoseshell/gsql:latest
docker run -it ceoseshell/gsql --help

🚀 Utilisation en 30 secondes

1. Lancer le Shell Interactif (CLI)

C'est le moyen le plus simple de découvrir GSQL.

gsql

2. Utilisation dans un Script Python

Voici comment intégrer GSQL correctement dans votre code aujourd'hui.

from gsql.database import Database

db = Database(db_path=":memory:", enable_wal=True, auto_recovery=True)

db.execute("""
    CREATE IF NOT EXISTS EXISTS users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        username TEXT UNIQUE NOT NULL,
        email TEXT
    )
""")

db.execute(
    "INSERT INTO users (username, email) VALUES (?, ?)",

)

result = db.execute("SELECT * FROM users", use_cache=True)
print(f"Trouvé {result['count']} utilisateur(s).")
for row in result['rows']:
    print(f"- {row['id']}: {row['username']}")

try:
    db.execute("BEGIN IMMEDIATE TRANSACTION")

    db.execute("UPDATE accounts SET balance = balance - 100 WHERE id = 1")
    db.execute("UPDATE accounts SET balance = balance + 100 WHERE id = 2")

    db.execute("COMMIT")
    print("Virement effectué avec succès.")

except Exception as e:
    db.execute("ROLLBACK")
    print(f"Échec du virement : {e}")

stats = db.execute("STATS")  # Récupère des statistiques d'utilisation
print(stats.get('message'))

db.close()

🛠️ Fonctionnalités Stables et Prêtes à l'Emploi

✅ Fonctionnalités Principales Totalement Opérationnelles

· Shell Interactif : Auto-complétion, historique, coloration syntaxique, affichage tabulaire. · Cache Intelligent (LRU) : Accélère les requêtes SELECT répétitives jusqu'à 20x. · Commande Spéciales Intégrées :

.tables                 -- Liste les tables
  .schema <table>         -- Montre la structure d'une table
  STATS;                  -- Affiche les stats de performance et de cache
  VACUUM;                 -- Optimise la base de données
  HELP;                   -- Affiche l'aide
  

· Support SQL Complet : Tout ce que SQLite supporte (SELECT, INSERT, JOIN, etc.) passe par GSQL. · Gestion des Erreurs : Messages d'erreur détaillés avec suivi de pile.

🔧 Fonctionnalités en Développement/Expérimentales

· Module NLP (gsql.nlp) : Traduction du langage naturel en SQL. Instable. · Autres Backends : Stockage YAML ou en mémoire. Non recommandé pour les données importantes.

📁 Structure du Projet (Pour Contributeurs)

gsql/
├── gsql/
│   ├── __init__.py              # Point d'entrée principal
│   ├── database.py              # CLASSE PRINCIPALE `Database`
│   ├── storage.py               # Abstraction du stockage (SQLite)
│   ├── executor.py              # Exécuteur et cache des requêtes
│   ├── cli.py                   # Interface du Shell Interactif
│   └── exceptions.py            # Exceptions personnalisées
├── tests/                       # Suite de tests
├── meta.yaml                    # Recette de construction Conda
├── setup.py                     # Configuration pour pip
├── Dockerfile                   # Configuration pour le conteneur
└── README.md                    # Ce fichier

Classe Principale : gsql.database.Database Point d'Entrée CLI : gsql.cli.main() (accessible via la commande gsql)

🧪 Exécuter les Tests et Contribuer

Nous avons besoin de votre aide pour stabiliser le projet !

git clone https://github.com/gopu-inc/gsql.git
cd gsql
pip install -e .[dev]  # Installe les dépendances de test

pytest tests/ -v

coverage run -m pytest tests/
coverage report
flake8 gsql/  # Vérification du style PEP8

Comment contribuer ?

1. Signaler un bug : Ouvrez une issue sur GitHub en décrivant précisément le problème, la version de GSQL, et un exemple de code minimal pour le reproduire.
2. Proposer une amélioration : Discutez-en d'abord dans une issue.
3. Soumettre une correction (PR) : Fork, branche, code, tests, pull request.

❓ FAQ & Dépannage

Q : db.begin_transaction() ne marche pas, que faire ? R : C'est un bug connu. Utilisez toujours db.execute("BEGIN TRANSACTION") et db.execute("COMMIT") ou db.execute("ROLLBACK"). Voir l'exemple de code plus haut.

Q : Le shell plante avec une erreur de parsing ? R : Évitez les guillemets complexes ou les caractères spéciaux dans les chaînes en mode interactif pour l'instant. Utilisez un script Python pour les requêtes complexes.

Q : Comment migrer de SQLite brut vers GSQL ? R : Pointez simplement le paramètre db_path vers votre fichier .db SQLite existant. GSQL le lira directement.

📄 Licence

Ce projet est publié sous la licence MIT. Voir le fichier LICENSE pour plus de détails.

GSQL © 2025 Gopu Inc. | Apportons une interface moderne à SQLite.