Partage de technologie

sqlite3 — Interface DB-API 2.0 pour bases de données SQLite

2024-07-12

한어Русский языкEnglishFrançaisIndonesianSanskrit日本語DeutschPortuguêsΕλληνικάespañolItalianoSuomalainenLatina

sqlite3 — Interface DB-API 2.0 pour bases de données SQLite — Documentation Python 3.12.4

sqlite3— Interface DB-API 2.0 pour bases de données SQLite
sqlite3 — Interface DB-API 2.0 pour les bases de données SQLite

Code source: Bibliothèque/sqlite3/    Emplacement du code source:Lib/sqlite3/

SQLite est une bibliothèque C qui fournit une base de données légère sur disque qui ne nécessite pas de processus serveur distinct et permet d'accéder à la base de données à l'aide d'une variante non standard du langage de requête SQL. Certaines applications peuvent utiliser SQLite pour le stockage de données internes. Il est également possible de prototyper une application à l'aide de SQLite, puis de porter le code vers une base de données plus importante telle que PostgreSQL ou Oracle.
SQLite est une bibliothèque de langage C qui fournit une base de données légère sur disque qui ne nécessite pas de processus serveur distinct et permet d'accéder à la base de données à l'aide d'une variante non standard du langage de requête SQL. Certaines applications peuvent utiliser SQLite pour le stockage de données interne. De plus, vous pouvez utiliser SQLite pour prototyper une application puis migrer le code vers une grande base de données telle que PostgreSQL ou Oracle.

Lesqlite3Le module a été écrit par Gerhard Häring. Il fournit une interface SQL conforme à la spécification DB-API 2.0 décrite parPEP 249, et nécessite SQLite 3.7.15 ou une version plus récente.
module sqlite3 Écrit par Gerhard Häring. Il fournit une interface SQL conforme à la spécification DB-API 2.0 décrite par PEP 249 et nécessite SQLite version 3.7.15 ou supérieure.

Ce document comprend quatre sections principales : Ce document comprend principalement les quatre sections principales suivantes

  • Didacticielenseigne comment utiliser lesqlite3module.DidacticielLa partie explique comment utiliser le module sqlite3.

  • Référencedécrit les classes et les fonctions que ce module définit.
    faire référence àLa section décrit les classes et fonctions définies par ce module.

  • Guides pratiquesdétaille comment gérer des tâches spécifiques.
    Guide d'opérationLes sections détaillent comment gérer des tâches spécifiques.

  • Explicationfournit des informations détaillées sur le contrôle des transactions.
    expliquerCette section fournit une introduction approfondie aux connaissances de base du contrôle des transactions.

Voir également

https://www.sqlite.org

La page Web SQLite ; la documentation décrit la syntaxe et les types de données disponibles pour le dialecte SQL pris en charge.
La page Web de SQLite ; sa documentation décrit la syntaxe des dialectes SQL pris en charge et les types de données disponibles.

Tutoriel SQLTutoriel SQL

Tutoriel, référence et exemples pour apprendre la syntaxe SQL.
Tutoriels, références et exemples pour apprendre la syntaxe SQL.

PEP 249- Spécification API de base de données 2.0 PEP 249 - Spécification API de base de données 2.0

PEP écrit par Marc-André Lemburg PEP écrit par Marc-André Lemburg.

DidacticielDidacticiel

Dans ce tutoriel, vous allez créer une base de données de Films de Monty Python en utilisant les basessqlite3fonctionnalité. Il suppose une compréhension fondamentale des concepts de base de données, y compriscurseursettransactions.
Dans ce didacticiel, vous utiliserez les fonctionnalités de base de SQLite3 pour créer une base de données sur les films Monty Python. Ce didacticiel suppose que vous possédez des connaissances de base sur les concepts de bases de données, notamment les curseurs et les transactions.

Tout d’abord, nous devons créer une nouvelle base de données et ouvrir une connexion à la base de données pour permettresqlite3pour travailler avec. Appelezsqlite3.connect()pour créer une connexion à la base de donnéestutorial.dbdans le répertoire de travail courant, le créer implicitement s'il n'existe pas:
Tout d’abord, nous devons créer une nouvelle base de données et ouvrir une connexion à la base de données afin que sqlite3 puisse interagir avec elle. Appelez sqlite3.connect() pour créer une connexion à la base de données tutoriel.db dans le répertoire de travail actuel, en la créant implicitement et automatiquement si la base de données n'existe pas :

  1. import sqlite3
  2. con = sqlite3.connect("tutorial.db")

Le retourConnexionobjetconreprésente la connexion à la base de données sur disque.
L'objet Connection renvoyé (nommé con dans ce cas) représente la connexion à la base de données sur le disque.

Pour exécuter des instructions SQL etrécupérer les résultats des requêtes SQL, nous devrons utiliser un curseur de base de données. Appelavec.curseur()pour créer leLe curseur:
Afin d'exécuter des instructions SQL et d'obtenir les résultats des requêtes SQL, nous devons utiliser des curseurs de base de données. Appelez con.cursor() pour créer un curseur :

cur = con.cursor()

Maintenant que nous avons une connexion à la base de données et un curseur, nous pouvons créer une table de base de donnéesmovieavec des colonnes pour le titre, l'année de sortie et la note d'évaluation. Pour plus de simplicité, nous pouvons simplement utiliser les noms de colonnes dans la déclaration de table - grâce àsaisie flexiblefonctionnalité de SQLite, la spécification des types de données est facultative. Exécutez laCREATE TABLEdéclaration en appelantcur.execute(...):
Maintenant que nous disposons de la connexion à la base de données et du curseur, nous pouvons créer une table de base de données nommée film avec des colonnes telles que le titre, l'année de sortie et la note de la critique. Pour simplifier les choses, nous pouvons utiliser les noms de colonnes directement dans la déclaration de table – la spécification du type de données est facultative en raison de la fonctionnalité de saisie flexible de SQLite. Exécutez l'instruction CREATE TABLE en appelant cur.execute(...) :

cur.execute("CREATE TABLE movie(title, year, score)")

Nous pouvons vérifier que la nouvelle table a été créée en interrogeant lesqlite_mastertable intégrée à SQLite, qui devrait maintenant contenir une entrée pour lemoviedéfinition de la table (voirLa table de schémapour plus de détails). Exécutez cette requête en appelantcur.execute(...), attribuez le résultat àres, et appelleres.fetchone()pour récupérer la ligne résultante :
Nous pouvons vérifier que la nouvelle table a été créée en interrogeant la table sqlite_master intégrée de SQLite, qui devrait maintenant contenir des entrées pour la définition de la table movie (voir la table schéma pour plus de détails). Exécutez la requête en appelant cur.execute(...), attribuez les résultats à res et appelez res.fetchone() pour obtenir les lignes de résultats :

>>>

  1. >>> res = cur.execute("SELECT name FROM sqlite_master")
  2. >>> res.fetchone()
  3. ('movie',)

Nous pouvons voir que la table a été créée, car la requête renvoie unetuplecontenant le nom de la table. Si nous interrogeonssqlite_masterpour une table inexistantespamres.fetchone()reviendraNone:
Nous pouvons voir que la table a été créée avec succès car la requête a renvoyé un tuple contenant le nom de la table. Si nous interrogeons sqlite_master pour une table inexistante (comme du spam), res.fetchone() renverra None.

>>>

  1. >>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
  2. >>> res.fetchone() is None
  3. True

Maintenant, ajoutez deux lignes de données fournies sous forme de littéraux SQL en exécutant uneINSERTdéclaration, encore une fois en appelantcur.execute(...):
Maintenant, ajoutez deux lignes de données, fournies sous forme de littéraux SQL, en exécutant une instruction INSERT (en appelant à nouveau cur.execute(...)) :

  1. cur.execute("""
  2. INSERT INTO movie VALUES
  3. ('Monty Python and the Holy Grail', 1975, 8.2),
  4. ('And Now for Something Completely Different', 1971, 7.5)
  5. """)

LeINSERTL'instruction ouvre implicitement une transaction, qui doit être validée avant que les modifications ne soient enregistrées dans la base de données (voirContrôle des transactions(pour plus de détails). Appelavec.commit()sur l'objet de connexion pour valider la transaction:
L'instruction INSERT démarre implicitement et automatiquement une transaction qui doit être validée avant que les modifications ne soient enregistrées dans la base de données (voir Transaction Control pour plus de détails). Appelez con.commit() sur l'objet de connexion pour valider la transaction :

con.commit()

Nous pouvons vérifier que les données ont été insérées correctement en exécutant uneSELECTrequête. Utilisez le désormais familiercur.execute(...)pour attribuer le résultat àres, et appelleres.fetchall()pour renvoyer toutes les lignes résultantes :
Nous pouvons vérifier que les données ont été correctement insérées en exécutant une requête SELECT. Attribuez les résultats à res en utilisant le désormais familier cur.execute(...) et appelez res.fetchall() pour renvoyer toutes les lignes de résultats :

>>>

  1. >>> res = cur.execute("SELECT score FROM movie")
  2. >>> res.fetchall()
  3. [(8.2,), (7.5,)]

Le résultat est unlisteeeeeeeede deuxtuples, un par ligne, chacun contenant lesscorevaleur.
Le résultat est une liste de deux tuples, un pour chaque ligne, et chaque tuple contenant la valeur de score de cette ligne.

Maintenant, insérez trois lignes supplémentaires en appelantcur.executemany(...):
Maintenant, insérez trois lignes de données supplémentaires en appelant cur.executemany(...) :

  1. data = [
  2. ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
  3. ("Monty Python's The Meaning of Life", 1983, 7.5),
  4. ("Monty Python's Life of Brian", 1979, 8.0),
  5. ]
  6. cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
  7. con.commit() # Remember to commit the transaction after executing INSERT.

Remarquerez que?les espaces réservés sont utilisés pour lierdataà la requête. Utilisez toujours des espaces réservés au lieu deformatage de chaînepour lier des valeurs Python à des instructions SQL, pour éviterAttaques par injection SQL(voirComment utiliser des espaces réservés pour lier des valeurs dans des requêtes SQLpour plus de détails).
Notez que l'espace réservé ? est utilisé pour lier les données dans la requête. Utilisez toujours des espaces réservés au lieu du formatage de chaîne pour lier les valeurs Python dans les instructions SQL afin d'éviter les attaques par injection SQL (voir "Comment lier des valeurs à l'aide d'espaces réservés dans les requêtes SQL" pour plus de détails).

Nous pouvons vérifier que les nouvelles lignes ont été insérées en exécutant uneSELECTrequête, cette fois en itérant sur les résultats de la requête :
Nous pouvons vérifier que la nouvelle ligne a été insérée en exécutant une requête SELECT, cette fois nous allons parcourir les résultats de la requête :

>>>

  1. >>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
  2. ... print(row)
  3. (1971, 'And Now for Something Completely Different')
  4. (1975, 'Monty Python and the Holy Grail')
  5. (1979, "Monty Python's Life of Brian")
  6. (1982, 'Monty Python Live at the Hollywood Bowl')
  7. (1983, "Monty Python's The Meaning of Life")

Chaque ligne contient deux élémentstuplede(year, title), correspondant aux colonnes sélectionnées dans la requête.
Chaque ligne est un tuple contenant deux éléments (année, titre), qui correspondent à la colonne sélectionnée dans la requête.

Enfin, vérifiez que la base de données a été écrite sur le disque en appelantcon.close()pour fermer la connexion existante, en ouvrir une nouvelle, en créant un nouveau curseur, puis en interrogeant la base de données :
Enfin, en appelantcon.close() pour fermer la connexion à la base de données existante et vous assurer que la base de données a été écrite sur le disque. Ensuite, ouvrez une nouvelle connexion, créez un nouveau curseur et interrogez la base de données pour vérifier que les données ont été écrites avec succès.

>>>

  1. >>> con.close()
  2. >>> new_con = sqlite3.connect("tutorial.db")
  3. >>> new_cur = new_con.cursor()
  4. >>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
  5. >>> title, year = res.fetchone()
  6. >>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
  7. The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975
  8. >>> new_con.close()

Vous avez maintenant créé une base de données SQLite en utilisant lesqlite3module, données insérées et valeurs récupérées de celui-ci de plusieurs manières.
tu as maintenant utilisésqlite3 Le module crée une base de données SQLite et y insère et récupère des données de différentes manières [Récupérer ? 】La valeur.

Voir égalementVoir également

RéférenceDescription du paramètre

Fonctions du module

sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)

Ouvrir une connexion à une base de données SQLite. Cette fonction permet d'ouvrir une connexion à une base de données SQLite.

Paramètres:
  • base de données (objet de type chemin) – Le chemin d’accès au fichier de base de données à ouvrir. Vous pouvez passer":memory:"pour créer unBase de données SQLite existant uniquement en mémoire, et ouvrez une connexion avec celui-ci.database (path-like object) 
    base de données (objet de type chemin) — Il s'agit du chemin d'accès au fichier de base de données à ouvrir.Tu peux passer":memory:"pour créer une base de données SQLite en mémoire et ouvrir une base de données .database (objet semblable à un chemin) qui y est connectée.

  • temps mort (flotter) – Combien de secondes la connexion doit attendre avant de déclencher uneErreur opérationnellelorsqu'une table est verrouillée. Si une autre connexion ouvre une transaction pour modifier une table, cette table sera verrouillée jusqu'à ce que la transaction soit validée. Par défaut, cinq secondes.timeout (float) — La connexion est lancée lorsque la table est verrouilléeOperationalError Combien de secondes faut-il attendre avant. Si une autre connexion ouvre une transaction pour modifier la table, la table sera verrouillée jusqu'à ce que la transaction soit validée. La valeur par défaut est de cinq secondes.

  • détecter_types (int) – Contrôler si et comment Types de données passupporté nativement par SQLitesont recherchés pour être convertis en types Python, à l'aide des convertisseurs enregistrés avecconvertisseur_registre(). Réglez-le sur n'importe quelle combinaison (en utilisant|, au niveau du bit ou) dePARSE_DECLTYPESetANALYSER_LES_NOMS_DES_COLONNESpour permettre cela. Noms des colonnes a priorité surtypes déclarés si les deux indicateurs sont définis. Les types ne peuvent pas être détectés pour les champs générés (par exemplemax(data)), même lorsque ledétecter_typesle paramètre est défini ;strsera renvoyé à la place. Par défaut (0), la détection de type est désactivée.
    detect_types (int)— Contrôle si et comment les types de données que SQLite ne prend pas en charge de manière native sont trouvés pour être utilisés.register_converter() Les convertisseurs enregistrés les convertissent en types Python.réglez-le surPARSE_DECLTYPESetPARSE_COLNAMEStoute combinaison de (en utilisant au niveau du bit ou| ) pour activer cette fonctionnalité.Si les deux drapeaux sont définis, alorsListe aura la priorité surdéclaration taper.Pour les régions générées, ces types ne peuvent pas être détectés (par ex.max(data)), même s'il est définidetect_typesparamètres ; à la place, il renverrastr taper. Par défaut (0), la détection de type est désactivée.


Insérez-le ici
Dans ce paragraphe anglais, qui est le sujet de « sont regardés » ?
Dans ce paragraphe anglais, le sujet de « sont recherchés » concerne les « types de données non pris en charge nativement par SQLite (types de données non pris en charge nativement par SQLite) ».Cette phrase signifie qu'en utilisantregister_converter() Convertisseurs enregistrés pour rechercher et convertir des types de données non pris en charge nativement par SQLite en types Python. Ainsi, les sujets sont ces types de données spécifiques qui doivent être trouvés et convertis.

  • niveau_d'isolation (str | Aucun) – Contrôler le comportement de gestion des transactions héritées. VoirConnexion.niveau_isolationetContrôle des transactions via l'attribut isolation_levelpour plus d'informations. Peut être"DEFERRED"(défaut),"EXCLUSIVE"ou"IMMEDIATE"; ouNonepour désactiver implicitement l'ouverture des transactions. N'a aucun effet à moins queConnexion.autocommitest réglé surCONTRÔLE DES TRANSACTIONS HÉRITÉES(le défaut).
    isolation_level(Chaîne | Aucun) – Contrôler le comportement de traitement des transactions héritées.Pour plus d'informations, voirConnection.isolation_levelet "passerisolation_levelTransaction de contrôle de propriété". Peut être"DEFERRED"(valeur par défaut),"EXCLUSIVE"ou"IMMEDIATE";ou réglé surNone pour désactiver l'ouverture implicite des transactions implicitement.Sauf siConnection.autocommitDéfinir commeLEGACY_TRANSACTION_CONTROL(par défaut), sinon ce paramètre n'a aucun effet.

  • vérifier_même_fil (booléenéenéenéenéenéenéenéenéenéenéenéenéenéen) - SiTrue(défaut),Erreur de programmationsera déclenché si la connexion à la base de données est utilisée par un thread autre que celui qui l'a créée. SiFalse, la connexion peut être accessible dans plusieurs threads ; les opérations d'écriture peuvent devoir être sérialisées par l'utilisateur pour éviter la corruption des données. Voirsécurité des threadspour plus d'informations.
    check_same_thread(valeur booléenne) – Si réglé surTrue(par défaut), sera déclenché lorsque la connexion à la base de données est utilisée par un thread autre que celui qui l'a créée.ProgrammingError anormal.Si réglé surFalse , plusieurs threads sont autorisés à accéder à la connexion ; mais les utilisateurs peuvent avoir besoin de sérialiser (en continu) eux-mêmes les opérations d'écriture pour éviter la corruption des données.Pour plus d'informations, voirthreadsafetyinstruction de.

  • usine (Connexion) – Une sous-classe personnalisée deConnexionpour créer la connexion avec, si ce n'est pas la valeur par défautConnexionclasse.
    factory(Connexion) – Si vous n'utilisez pas la valeur par défautConnectionclasse, spécifiez une coutumeConnection Sous-classe pour créer la connexion. Ce paramètre permet de personnaliser le comportement de la connexion à la base de données en fonction de besoins ou d'extensions spécifiques.

  • déclarations mises en cache (int) – Le nombre d’énoncés quisqlite3doit mettre en cache en interne cette connexion, pour éviter une surcharge d'analyse. Par défaut, 128 instructions.
    cached_statements(int) – sqlite3 Nombre d'instructions qui doivent être mises en cache en interne pour cette connexion afin d'éviter la surcharge d'analyse. Par défaut, 128 instructions sont mises en cache. Ce paramètre vous permet d'ajuster la taille du cache pour optimiser les performances ou l'utilisation de la mémoire.

  • uri (booléenéenéenéenéenéenéenéenéenéenéenéenéenéen) – Si défini surTruebase de donnéesest interprété comme un URI avec un chemin de fichier et une chaîne de requête facultative. La partie schémadoitêtre"file:", et le chemin peut être relatif ou absolu. La chaîne de requête permet de transmettre des paramètres à SQLite, ce qui permet diversesComment travailler avec les URI SQLite.
    uri(booléen) – Si réglé surTrue,maisdatabase Interprété comme un identifiant de ressource uniforme (URI) avec un chemin de fichier et une chaîne de requête facultative. La partie schéma de l'URIdoit est "file:", le chemin peut être relatif ou absolu. Les chaînes de requête permettent de transmettre des paramètres à SQLite, permettant ainsi différentes manières de travailler avec les URI SQLite. Cela permet des options de connexion à la base de données plus complexes, telles que la définition du mode lecture seule, la spécification de la taille du cache, etc.

  • validation automatique (booléenéenéenéenéenéenéenéenéenéenéenéenéenéen) - ContrôlePEP 249comportement de gestion des transactions. VoirConnexion.autocommitetContrôle des transactions via l'attribut autocommitpour plus d'informations.validation automatiqueactuellement par défautCONTRÔLE DES TRANSACTIONS HÉRITÉES. La valeur par défaut sera modifiée enFalsedans une future version de Python.
    autocommit(booléen) – Contrôler le comportement de traitement des transactions conformément à la PEP 249.Pour plus d'informations, voirConnection.autocommit et "Contrôle des transactions via l'attribut autocommit." maintenant,autocommitLa valeur par défaut est définie surLEGACY_TRANSACTION_CONTROL , ce qui signifie qu'il suit le comportement de contrôle de transaction hérité de la spécification Python Database API (PEP 249).Cependant, dans une future version de Python, la valeur par défaut deviendraFalse, ce qui signifie que les transactions ne sont pas automatiquement validées par défaut et nécessitent que l'utilisateur contrôle explicitement le début et la fin de la transaction.

Veuillez noter,*Les paramètres sont utilisés dans les définitions de fonctions comme séparateurs entre les arguments de position et les arguments de mots-clés, ce qui signifieautocommitTous les paramètres suivants doivent être des paramètres de mots-clés.

Type de retour :Type de retour: 

Connexion

Soulève unévénement d'audit sqlite3.connectavec argumentdatabase.
sqlite3.connect: Lors de l'utilisationdatabaseParamètres renvoyés lors de la connexion à la base de données.

Soulève unévénement d'audit sqlite3.connect/handleavec argumentconnection_handle.
sqlite3.connect/handle: Lorsque la poignée de connexion (connection_handle) est lancé lors de sa création.

Modifié dans la version 3.4 : Ajout duuriparamètre.
Dans la version 3.4 : ajoutéuriParamètre qui permet de spécifier le fichier de base de données au format URI.

Modifié dans la version 3.7 :base de donnéespeut désormais aussi être unobjet de type chemin, pas seulement une chaîne.
Dans la version 3.7 :databaseLes paramètres peuvent désormais être un objet semblable à un chemin au lieu de simplement des chaînes.

Modifié dans la version 3.10 : Ajout dusqlite3.connect/handleévénement d'audit.
Dans la version 3.10 : ajoutésqlite3.connect/handleÉvénement d’audit, qui est déclenché lorsque le handle de connexion est créé.

Modifié dans la version 3.12 : Ajout duvalidation automatiqueparamètre.
Dans la version 3.12 : ajoutéautocommitParamètres qui permettent un contrôle plus précis du comportement de validation automatique des transactions.

sqlite3.complete_statement(déclaration)

RetourTruesi la chaînedéclarationsemble contenir une ou plusieurs instructions SQL complètes. Aucune vérification syntaxique ou analyse d'aucune sorte n'est effectuée, à part la vérification qu'il n'y a pas de littéraux de chaîne non fermés et que l'instruction est terminée par un point-virgule.
si chaînestatementsemble contenir une ou plusieurs instructions SQL complètes, puis renvoieTrue . Aucune validation ou analyse syntaxique n'est effectuée autre que la vérification qu'il n'y a pas de littéraux de chaîne non fermés et que l'instruction se termine par un point-virgule.

Par exemple:Exemple

>>>

  1. >>> sqlite3.complete_statement("SELECT foo FROM bar;")
  2. True
  3. >>> sqlite3.complete_statement("SELECT foo")
  4. False

Cette fonction peut être utile lors de la saisie en ligne de commande pour déterminer si le texte saisi semble former une instruction SQL complète ou si une saisie supplémentaire est nécessaire avant d'appelerexécuter().
Cette fonction peut être utile lors de la saisie sur la ligne de commande, pour déterminer si le texte saisi ressemble à une instruction SQL complète, ou lors de l'appelexecute()Si une entrée supplémentaire est requise auparavant.

Voirrunsource()dansLib/sqlite3/__main__.pypour une utilisation dans le monde réel.
Dans les applications pratiques, vous pouvez vous référer àLib/sqlite3/__main__.pymilieurunsource()fonction pour comprendre son utilisation.

sqlite3.enable_callback_tracebacks(drapeau/)

Activer ou désactiver les traces de rappel. Par défaut, vous n'obtiendrez aucune trace dans les fonctions définies par l'utilisateur, les agrégats, les convertisseurs, les rappels d'autorisation, etc. Si vous souhaitez les déboguer, vous pouvez appeler cette fonction avecdrapeaumis àTrue. Ensuite, vous obtiendrez des tracebacks à partir des rappels sursys.stderr. UtiliserFalsepour désactiver à nouveau la fonctionnalité.
Activez ou désactivez le suivi des rappels. Par défaut, vous n'obtiendrez aucun traçage dans les fonctions définies par l'utilisateur, les fonctions d'agrégation, les convertisseurs, les rappels d'autorisation, etc.Si vous souhaitez les déboguer, vous pouvez appeler cette fonction et remplacerflagDéfinir commeTrue .Par la suite, vous pourrezsys.stderr Obtenez des informations de trace à partir du rappel.utiliserFalsepour désactiver à nouveau cette fonctionnalité.

Note

Les erreurs dans les rappels de fonctions définies par l'utilisateur sont enregistrées comme des exceptions non déclenchables. Utilisez ungestionnaire de crochets non relevablespour l'introspection du rappel ayant échoué.
Les erreurs dans les rappels de fonctions définies par l'utilisateur sont enregistrées en tant qu'exceptions irrécupérables. Utilisez un gestionnaire de hook non activable pour effectuer une introspection sur les rappels ayant échoué.

 

Cela signifie que lorsque des erreurs se produisent dans les rappels des fonctions définies par l'utilisateur de SQLite (telles que les fonctions d'agrégation, les fonctions scalaires, etc.), ces erreurs ne sont pas générées comme les exceptions Python normales et peuvent être interceptées par des blocs try-sauf. Au lieu de cela, ils sont capturés par SQLite ou le module sqlite3 de Python et enregistrés d'une manière ou d'une autre (généralement écrits dans le journal ou dans la sortie d'erreur standard), mais n'interrompent pas l'exécution du programme (sauf si l'erreur est très grave).

Pour inspecter et déboguer ces exceptions non capturables, vous pouvez configurer un « gestionnaire de hooks incaptables ». Ce gestionnaire est une fonction que Python appelle lorsqu'une exception non interceptée se produit, en transmettant les informations sur l'exception en tant que paramètre. De cette façon, vous pouvez écrire du code dans la fonction du processeur pour enregistrer ou vérifier ces exceptions afin de faciliter le diagnostic du problème.

Veuillez noter que l'implémentation spécifique peut varier en fonction de la version de Python et des détails d'implémentation du module sqlite3. Par conséquent, il est recommandé de consulter la dernière documentation Python ou la documentation du module sqlite3 pour savoir comment configurer et utiliser le gestionnaire de hook incaptable.

sqlite3.register_adapter(taperadaptateur/)

Inscrivez unadaptateur appelablepour adapter le type Pythontaperdans un type SQLite. L'adaptateur est appelé avec un objet Python de typetapercomme seul argument, et doit renvoyer une valeur de atype que SQLite comprend nativement.
Enregistrez un objet appelable **adaptateur** pour convertir les Pythontype Le type est adapté à un type que SQLite peut comprendre nativement.Cette fonction d'adaptateur prend untypeUn objet de type est appelé comme seul argument et doit renvoyer une valeur d'un type pris en charge nativement par SQLite.
 

Il convient de noter que le «typetype" peut être un peu trompeur, car généralement nous ne faisons pas référence au système intégré de Pythontype Les objets (c'est-à-dire les types eux-mêmes) sont stockés directement dans la base de données. Plus communément, nous souhaitons adapter des objets en Python (qui peuvent être des instances de types personnalisés) dans un format que SQLite peut stocker.Cependant, en prenant la phrase au pied de la lettre, si vous devez faire face àtypeobjet lui-même (bien que cela soit rare en pratique), vous devrez écrire un adaptateur pour le convertir sous une forme que SQLite peut stocker, comme une chaîne représentant le nom du type.

Cependant, un cas d'utilisation plus courant concerne les types Python personnalisés ou les types intégrés tels quedatetimedecimal.Decimaletc.) écrire des adaptateurs afin qu'ils puissent être stockés et récupérés correctement par la base de données SQLite.

Par exemple, si vous disposez d'une classe Python personnaliséeMyClass, et que vous souhaitez stocker son instance dans une base de données SQLite, vous pouvez écrire un adaptateur pour convertir une instance de cette classe en une chaîne (ou un autre type) pouvant être stockée par SQLite, puis écrire un convertisseur pour convertir cette chaîne. àMyClassexemple.

Cependant, pour cette question, si vous souhaitez uniquement gérer Pythontypeobjet (c'est-à-dire les métadonnées du type), vous pouvez écrire un adaptateur pour renvoyer le nom du type (sous forme de chaîne), mais ce n'est généralement pas une pratique courante pour stocker des objets dans une base de données.

sqlite3.register_converter(nom de typeconvertisseur/)

Enregistrez leconvertisseur appelablepour convertir des objets SQLite de typenom de typedans un objet Python d'un type spécifique. Le convertisseur est appelé pour toutes les valeurs SQLite de typenom de type; il est passé unoctetsobjet et doit renvoyer un objet du type Python souhaité. Consultez le paramètredétecter_typesdeconnecter()pour plus d'informations sur le fonctionnement de la détection de type.
Enregistrez un objet appelable **converter** pour convertir les types SQLite entypename Convertit un objet en objet Python d'un type spécifique.Pour tous les typestypenameCe convertisseur est appelé pour toute valeur SQLite ; il reçoit unbytes object comme argument et doit renvoyer un objet du type Python requis.Pour savoir comment fonctionne la détection de type, veuillez vous référer àconnect()Fonctionneldetect_typesparamètre.

Note:nom de typeet le nom du type dans votre requête sont mis en correspondance sans tenir compte de la casse.
AvistypenameLe nom du type dans la requête n'est pas sensible à la casse lors de la correspondance.

Constantes du module

sqlite3.CONTRÔLE_TRANSACTION_HÉRITÉ

Ensemblevalidation automatiqueà cette constante pour sélectionner le comportement de contrôle des transactions de style ancien (pré-Python 3.12). VoirContrôle des transactions via l'attribut isolation_levelpour plus d'informations.
Volontéautocommit Définissez cette constante pour sélectionner le comportement de contrôle des transactions à l'ancienne (pré-Python 3.12).Pour plus d'informations, veuillez vous référer à la rubrique "Passisolation_levelTransactions de contrôle des propriétés".

sqlite3.PARSE_COLNAMES

Transmettez cette valeur d'indicateur à ladétecter_typesparamètre deconnecter()pour rechercher une fonction de conversion en utilisant le nom du type, analysé à partir du nom de la colonne de requête, comme clé du dictionnaire de conversion. Le nom du type doit être entouré de crochets ([]).
Transmettez cette valeur d'indicateur àconnect()Fonctionneldetect_types Paramètre permettant de rechercher la fonction de convertisseur en interrogeant le nom du type résolu dans le nom de la colonne comme clé du dictionnaire du convertisseur. Les noms de types doivent être placés entre crochets ([]).

SELECT p as "p [point]" FROM test;  ! will look up converter "point"

Ce drapeau peut être combiné avecPARSE_DECLTYPESen utilisant le|Opérateur (ou) au niveau du bit.
Ce drapeau peut être utilisé|Opérateur (OU au niveau du bit) ETPARSE_DECLTYPESEn collaboration avec.

sqlite3.PARSE_DECLTYPES

Transmettez cette valeur d'indicateur à ladétecter_typesparamètre deconnecter()pour rechercher une fonction de conversion en utilisant les types déclarés pour chaque colonne. Les types sont déclarés lors de la création de la table de base de données.sqlite3recherchera une fonction de conversion en utilisant le premier mot du type déclaré comme clé du dictionnaire de conversion. Par exemple :
Transmettez cette valeur d'indicateur àconnect()Fonctionneldetect_types Paramètres pour trouver la fonction de conversion en utilisant le type déclaré de chaque colonne de la base de données. Ces types sont déclarés lors de la création de la table de la base de données.sqlite3 La fonction de conversion sera recherchée en utilisant le premier mot du type déclaré comme clé du dictionnaire du convertisseur. Par exemple:

  1. CREATE TABLE test(
  2. i integer primary key, ! will look up a converter named "integer"
  3. p point, ! will look up a converter named "point"
  4. n number(10) ! will look up a converter named "number"
  5. )

Ce drapeau peut être combiné avecANALYSER_LES_NOMS_DES_COLONNESen utilisant le|Opérateur (ou) au niveau du bit.

sqlite3.SQLITE_OK
sqlite3.SQLITE_DENY
sqlite3.SQLITE_IGNORE

Drapeaux qui devraient être renvoyés par leautorisateur_rappel appelabletransmis àConnexion.set_authorizer(), pour indiquer si :
Passer auConnection.set_authorizer()deauthorizer_callbackIndicateurs que la fonction appelable doit renvoyer pour indiquer :

  • L'accès est autorisé (SQLITE_OK), l'accès est autorisé (SQLITE_OK

  • L'instruction SQL doit être interrompue avec une erreur (SQLITE_DENY)
    L'instruction SQL doit être abandonnée avec une erreur (SQLITE_DENY

  • La colonne doit être traitée comme uneNULLvaleur (SQLITE_IGNORE)
    Les colonnes doivent être traitées comme des valeurs NULL (SQLITE_IGNORE

sqlite3.niveau d'API

Constante de chaîne indiquant le niveau DB-API pris en charge. Requis par l'API DB. Codé en dur pour"2.0".
Ces deux constantes de chaîne sontsqlite3Définis en modules, ils suivent la spécification Python Database API (DB-API).

sqlite3.paramstyle

Constante de chaîne indiquant le type de formatage de marqueur de paramètre attendu par lesqlite3module. Requis par l'API DB. Codé en dur pour"qmark".
Cette constante de chaîne spécifiesqlite3 Le type de formatage du marqueur de paramètre attendu par le module. Ceci est requis par la spécification DB-API (Database Application Programming Interface).Il est codé en dur comme"qmark", signifie que lors de la construction de requêtes SQL, les marqueurs de paramètres doivent être représentés par des points d'interrogation (?).

Note

LenamedLe style de paramètre DB-API est également pris en charge.

sqlite3.version_sqlite

Numéro de version de la bibliothèque d'exécution SQLite en tant quechaîne.
Le numéro de version de la bibliothèque d'exécution SQLite, exprimé sous forme de chaîne.

sqlite3.sqlite_version_info

Numéro de version de la bibliothèque d'exécution SQLite en tant quetupledeentiers.
Le numéro de version de la bibliothèque d'exécution SQLite, exprimé sous la forme d'un tuple d'entiers.

sqlite3.sécurité des threads

Constante entière requise par DB-API 2.0, indiquant le niveau de sécurité des threadssqlite3module prend en charge. Cet attribut est défini en fonction de la valeur par défautmode de filetagela bibliothèque SQLite sous-jacente est compilée avec. Les modes de threading SQLite sont :
Constante entière requise par DB-API 2.0, indiquantsqlite3 Le niveau de sécurité des threads pris en charge par le module. Cette propriété est définie en fonction du mode de thread par défaut avec lequel la bibliothèque SQLite sous-jacente a été compilée. Les modes de thread de SQLite incluent :

  1. Fil unique:Dans ce mode, tous les mutex sont désactivés et SQLite n'est pas sûr à utiliser dans plusieurs threads à la fois.
    Single-thread : dans ce mode, tous les mutex sont désactivés et SQLite ne peut pas être utilisé en toute sécurité par plusieurs threads en même temps.

  2. Multi-thread:Dans ce mode, SQLite peut être utilisé en toute sécurité par plusieurs threads à condition qu'aucune connexion à une base de données ne soit utilisée simultanément dans deux threads ou plus.
    Multi-thread : dans ce mode, SQLite peut être utilisé en toute sécurité par plusieurs threads, à condition qu'aucune connexion à la base de données ne soit utilisée simultanément par deux ou plusieurs threads.

  3. Sérialisé:En mode sérialisé, SQLite peut être utilisé en toute sécurité par plusieurs threads sans aucune restriction.
    Sérialisé : en mode sérialisé, SQLite peut être utilisé en toute sécurité par plusieurs threads sans aucune restriction.

Les mappages des modes de thread SQLite aux niveaux de threadsafety DB-API 2.0 sont les suivants :
Le mappage du mode thread de SQLite au niveau de sécurité des threads DB-API 2.0 est le suivant :

Mode de threading SQLite

sécurité des threads

SQLITE_THREADSAFE

Signification de DB-API 2.0

à fil unique

0

0

Les threads ne peuvent pas partager le module

multi-thread

1

2

Les threads peuvent partager le module, mais pas les connexions

sérialisé

3

1

Les threads peuvent partager le module, les connexions et les curseurs

Modifié dans la version 3.11 : Définirsécurité des threadsdynamiquement au lieu de le coder en dur1.

sqlite3.version

Numéro de version de ce module en tant quechaîneCe n'est pas la version de la bibliothèque SQLite.
Le numéro de version de ce module, exprimé sous forme de chaîne.ceNonLe numéro de version de la bibliothèque SQLite.

Obsolète depuis la version 3.12, sera supprimé dans la version 3.14 : Cette constante reflétait le numéro de version dupysqlitepackage, une bibliothèque tierce qui permettait de transmettre en amont les modifications apportées àsqlite3Aujourd’hui, cela n’a plus aucun sens ni aucune valeur pratique.
Obsolète depuis la version 3.12, à supprimer dans la version 3.14 : cette constante était utilisée pour refléterpysqliteLe numéro de version du package,pysqliteIl s'agit d'une bibliothèque tierce qui a été téléchargée vers le serveur en amont.sqlite3 Validez les modifications. Aujourd’hui, cela n’a plus de sens réel ni de valeur pratique.

sqlite3.version_info

Numéro de version de ce module en tant quetupledeentiersCe n'est pas la version de la bibliothèque SQLite.

Obsolète depuis la version 3.12, sera supprimé dans la version 3.14 : Cette constante reflétait le numéro de version dupysqlitepackage, une bibliothèque tierce qui permettait de transmettre en amont les modifications apportées àsqlite3Aujourd’hui, cela n’a plus aucun sens ni aucune valeur pratique.

sqlite3.SQLITE_DBCONFIG_DEFENSIVE
sqlite3.SQLITE_DBCONFIG_DQS_DDL
sqlite3.SQLITE_DBCONFIG_DQS_DML
sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY
sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
sqlite3.SQLITE_DBCONFIG_ACTIVER_CHARGER_EXTENSION
sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG
sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER
sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW
sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE
sqlite3.FORMAT_FICHIER_LEGACY_SQLITE_DBCONFIG
sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
sqlite3.SQLITE_DBCONFIG_RESET_DATABASE
sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP
sqlite3.SQLITE_DBCONFIG_SCHEMA_CONFIGURÉ
sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

Ces constantes sont utilisées pour laConnexion.setconfig()etobtenirconfig()méthodes.
Ces constantes sont utiliséesConnection.setconfig()etgetconfig()méthode.

La disponibilité de ces constantes varie en fonction de la version de SQLite avec laquelle Python a été compilé.
La disponibilité de ces constantes dépend de la version de SQLite avec laquelle SQLite Python a été compilé.

Ajouté dans la version 3.12.

Voir également

Options de configuration de la connexion à la base de données

Documentation SQLite : Options de configuration de la connexion à la base de données

Objets de connexion

classesqlite3.Connexion

Chaque base de données SQLite ouverte est représentée par unConnectionobjet, qui est créé en utilisantsqlite3.connect()Leur objectif principal est de créerLe curseurobjets, etContrôle des transactions.

Voir également

Une connexion à une base de données SQLite possède les attributs et méthodes suivants :

le curseur(usine=Curseur)

Créer et renvoyer unLe curseurobjet. La méthode du curseur accepte un seul paramètre facultatifusine. Si fourni, il doit s'agir d'unappelablerenvoyer une instance deLe curseurou ses sous-classes.
Crée un et renvoie unCursorobjet.cursorLa méthode accepte un seul paramètre facultatiffactory .Si ce paramètre est fourni, il doit s'agir d'un objet appelable qui renvoie unCursorou une instance de sa sous-classe.

blobopen(tableauaucolonnerangée/*lecture seule = Fauxnom='main')

Ouvrir unGouttehandle vers un BLOB existant.

Paramètres:

  • tableauau (str) – Le nom de la table où se trouve le blob.
    Le nom de la table contenant les données BLOB.

  • colonne (str) – Le nom de la colonne où se trouve le blob.
    Nom de colonne contenant des données BLOB.

  • rangée (str) – Le nom de la ligne où se trouve le blob.
    Le nom de la ligne (ou plus précisément l'identifiant de la ligne) qui contient les données BLOB.

  • lecture seulement (booléenéenéenéenéenéenéenéenéenéenéenéenéenéen) - Mis àTruesi le blob doit être ouvert sans autorisation d'écriture. La valeur par défaut estFalse.
    S'il est défini sur True, cela indique que le BLOB doit être ouvert sans autorisation en écriture. La valeur par défaut est False, ce qui permet la lecture et l'écriture.

  • nom (str) – Le nom de la base de données où se trouve le blob. La valeur par défaut est"main".
    Le nom de la base de données contenant les données BLOB. La valeur par défaut est "main", qui est le nom de base de données par défaut dans SQLite.

Augmente :

Erreur opérationnelle– Lorsque vous essayez d’ouvrir un blob dans unWITHOUT ROWIDtableau.
En essayant sansRANGÉESe produit lorsque les données BLOB sont ouvertes dans la table des ID.

Type de retour :

Goutte

Note

La taille du blob ne peut pas être modifiée à l'aide de laGoutteclasse. Utilisez la fonction SQLzeroblobpour créer un blob avec une taille fixe.

Ajouté dans la version 3.11.

commettre()

Validez toute transaction en attente dans la base de données. Sivalidation automatiqueestTrue, ou s'il n'y a pas de transaction ouverte, cette méthode ne fait rien. SiautocommitestFalse, une nouvelle transaction est implicitement ouverte si une transaction en attente a été validée par cette méthode.
Validez toutes les transactions en attente dans la base de données.siautocommit Si c'est vrai, ou s'il n'y a pas de transaction ouverte, cette méthode n'effectue aucune opération.siautocommitest False et que cette méthode valide une transaction en attente, une nouvelle transaction sera démarrée implicitement.

retour en arriere()

Revenir au début de toute transaction en attente. Sivalidation automatiqueestTrue, ou s'il n'y a pas de transaction ouverte, cette méthode ne fait rien. SiautocommitestFalse, une nouvelle transaction est implicitement ouverte si une transaction en attente a été annulée par cette méthode.
Revenez au début de toutes les transactions en attente.siautocommit Si c'est vrai, ou s'il n'y a pas de transaction ouverte, cette méthode n'effectue aucune opération.siautocommitest False, et cette méthode annule une transaction en attente, une nouvelle transaction sera démarrée implicitement.

fermer()

Fermez la connexion à la base de données. Sivalidation automatiqueestFalse, toute transaction en attente est implicitement annulée. SiautocommitestTrueouCONTRÔLE DES TRANSACTIONS HÉRITÉES, aucun contrôle de transaction implicite n'est exécuté. Assurez-vous decommettre()avant de fermer pour éviter de perdre les modifications en attente.
Fermez la connexion à la base de données.siautocommit Si False, toutes les transactions en attente seront implicitement annulées.siautocommitest vrai ouLEGACY_TRANSACTION_CONTROL (contrôle des transactions hérité), le contrôle implicite des transactions ne sera pas effectué.Avant de fermer, assurez-vous d'appelercommit()pour éviter de perdre les modifications en attente.

exécuter(SQLparamètres=()/)

Créer un nouveauLe curseurobjet et appelexécuter()dessus avec le donnéSQLetparamètres. Renvoie le nouvel objet curseur.
créer un nouveauCursorobjet et appelexecute()méthode, en passant dans le donnésql instructions et paramètres.rends ce nouveauCursorobjet.

exécuterplusieurs(SQLparamètres/)

Créer un nouveauLe curseurobjet et appelexécutermany()dessus avec le donnéSQLetparamètres. Renvoie le nouvel objet curseur.
créer un nouveauCursorobjet et appelexecutemany()méthode, en passant dans le donnésql Instructions et séquences de paramètres. Cela permet d'exécuter plusieurs jeux de paramètres en même temps.rends ce nouveauCursorobjet.

exécuterscript(script_sql/)

Créer un nouveauLe curseurobjet et appelexécuterscript()dessus avec le donnéscript_sql. Renvoie le nouvel objet curseur.
créer un nouveauCursorobjet et appelexecutescript() méthode, en passant le script SQL donné. Cela permet l'exécution de plusieurs instructions SQL, séparées par des points-virgules dans le script.rends ce nouveauCursorobjet.

créer_fonction(nomnargfonction*déterministe=Faux)

Créer ou supprimer une fonction SQL définie par l'utilisateur.
Créez ou supprimez une fonction SQL définie par l'utilisateur.

Paramètres:

  • nom (str) – Le nom de la fonction SQL.
    name(str) – Le nom de la fonction SQL.

  • narg (int) – Le nombre d’arguments que la fonction SQL peut accepter. Si-1, il peut prendre n'importe quel nombre d'arguments.
    narg (int) – Le nombre d'arguments que la fonction SQL peut accepter. Si -1, cela signifie qu'il peut accepter n'importe quel nombre d'arguments.

  • fonction (rappeler| Aucun) – Unappelablequi est appelé lorsque la fonction SQL est invoquée. L'appelable doit renvoyerun type supporté nativement par SQLite. Mis àNonepour supprimer une fonction SQL existante.
    func (rappel | Aucun) – Cet objet appelable (rappel) sera exécuté lorsque la fonction SQL est appelée. Cet objet appelable doit renvoyer un type pris en charge nativement par SQLite. Si la valeur est Aucun, les fonctions SQL existantes sont supprimées.

  • déterministe (booléenéenéenéenéenéenéenéenéenéenéenéenéenéen) - SiTrue, la fonction SQL créée est marquée commedéterministe, ce qui permet à SQLite d'effectuer des optimisations supplémentaires.
    deterministic(bool) – Si True, marque la fonction SQL créée comme déterministe, ce qui permet à SQLite d'effectuer des optimisations supplémentaires.

Augmente :

Erreur non prise en charge- Sidéterministeest utilisé avec les versions SQLite antérieures à 3.8.3.

Modifié dans la version 3.8 : Ajout dudéterministeparamètre.

Exemple:

>>>

  1. >>> import hashlib
  2. >>> def md5sum(t):
  3. ... return hashlib.md5(t).hexdigest()
  4. >>> con = sqlite3.connect(":memory:")
  5. >>> con.create_function("md5", 1, md5sum)
  6. >>> for row in con.execute("SELECT md5(?)", (b"foo",)):
  7. ... print(row)
  8. ('acbd18db4cc2f85cedef654fccc4a4d8',)
  9. >>> con.close()
créer_agrégat(nomn_argclasse_agrégat)

Créez ou supprimez une fonction d’agrégation SQL définie par l’utilisateur.
Créez ou supprimez une fonction d'agrégation SQL définie par l'utilisateur.

Paramètres:

  • nom (str) – Le nom de la fonction d’agrégation SQL.
         name(str) – Le nom de la fonction d'agrégation SQL.

  • n_arg (int) – Le nombre d’arguments que la fonction d’agrégation SQL peut accepter. Si-1, il peut prendre n'importe quel nombre d'arguments.
    Nombre de paramètres qu'une fonction d'agrégation SQL peut accepter. Si -1, cela signifie qu'il peut accepter n'importe quel nombre d'arguments.

  • classe_agrégat (classeeee| Aucun) –

    Une classe doit implémenter les méthodes suivantes :
    Une classe doit implémenter les méthodes suivantes :

    • step(): Ajoutez une ligne à l'agrégat.

    • finalize(): Renvoie le résultat final de l'agrégat sous la formeun type supporté nativement par SQLite.
      finalize(): Cette méthode est utilisée pour renvoyer le résultat final de l'agrégation.

    Le nombre d'arguments que lestep()la méthode doit accepter est contrôlée parn_arg.
    step()Le nombre de paramètres qu'une méthode doit accepter est donné parn_argcontrôle.

    Mis àNonepour supprimer une fonction d'agrégation SQL existante.
    Définir commeNonepour supprimer les fonctions d'agrégation SQL existantes.

Exemple:

  1. class MySum:
  2. def __init__(self):
  3. self.count = 0
  4. def step(self, value):
  5. self.count += value
  6. def finalize(self):
  7. return self.count
  8. con = sqlite3.connect(":memory:")
  9. con.create_aggregate("mysum", 1, MySum)
  10. cur = con.execute("CREATE TABLE test(i)")
  11. cur.execute("INSERT INTO test(i) VALUES(1)")
  12. cur.execute("INSERT INTO test(i) VALUES(2)")
  13. cur.execute("SELECT mysum(i) FROM test")
  14. print(cur.fetchone()[0])
  15. con.close()
créer_une_fonction_de_fenêtre(nomnombre_paramsclasse_agrégat/)

Créez ou supprimez une fonction de fenêtre d’agrégation définie par l’utilisateur.

Paramètres:

  • nom (str) – Le nom de la fonction de fenêtre d’agrégation SQL à créer ou à supprimer.

  • nombre_params (int) – Le nombre d’arguments que la fonction de fenêtre d’agrégation SQL peut accepter. Si-1, il peut prendre n'importe quel nombre d'arguments.

  • classe_agrégat (classeeee| Aucun) –

    Une classe qui doit implémenter les méthodes suivantes :

    • step():Ajouter une ligne à la fenêtre actuelle.

    • value(): Renvoie la valeur actuelle de l'agrégat.

    • inverse(): Supprimer une ligne de la fenêtre actuelle.

    • finalize(): Renvoie le résultat final de l'agrégat sous la formeun type supporté nativement par SQLite.

    Le nombre d'arguments que lestep()etvalue()les méthodes doivent accepter sont contrôlées parnombre_params.

    Mis àNonepour supprimer une fonction de fenêtre d'agrégation SQL existante.

Augmente :

Erreur non prise en charge– Si utilisé avec une version de SQLite antérieure à 3.25.0, qui ne prend pas en charge les fonctions de fenêtre d’agrégation.

Ajouté dans la version 3.11.

Exemple:

# Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc
class WindowSumInt:
    def __init__(self):
        self.count = 0

    def step(self, value):
        """Add a row to the current window."""
        self.count += value

    def value(self):
        """Return the current value of the aggregate."""
        return self.count

    def inverse(self, value):
        """Remove a row from the current window."""
        self.count -= value

    def finalize(self):
        """Return the final value of the aggregate.

        Any clean-up actions should be placed here.
        """
        return self.count


con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE test(x, y)")
values = [
    ("a", 4),
    ("b", 5),
    ("c", 3),
    ("d", 8),
    ("e", 1),
]
cur.executemany("INSERT INTO test VALUES(?, ?)", values)
con.create_window_function("sumint", 1, WindowSumInt)
cur.execute("""
    SELECT x, sumint(y) OVER (
        ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
    ) AS sum_y
    FROM test ORDER BY x
""")
print(cur.fetchall())
con.close()

créer_collation(nomappelable/)

Créer un classement nomménomen utilisant la fonction de classementappelableappelableest passé deuxchaînearguments, et il devrait renvoyer unentier:

  • 1si le premier est commandé plus haut que le deuxième

  • -1si le premier est commandé plus bas que le deuxième

  • 0s'ils sont ordonnés de manière égale

L'exemple suivant montre un classement de tri inversé :

def collate_reverse(string1, string2):
    if string1 == string2:
        return 0
    elif string1 < string2:
        return 1
    else:
        return -1

con = sqlite3.connect(":memory:")
con.create_collation("reverse", collate_reverse)

cur = con.execute("CREATE TABLE test(x)")
cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)])
cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse")
for row in cur:
    print(row)
con.close()

Supprimer une fonction de classement en définissantappelableàNone.

Modifié dans la version 3.11 : le nom du classement peut contenir n'importe quel caractère Unicode. Auparavant, seuls les caractères ASCII étaient autorisés.

interrompre()

Appelez cette méthode à partir d'un autre thread pour interrompre toutes les requêtes qui pourraient être en cours d'exécution sur la connexion. Les requêtes interrompues génèreront unErreur opérationnelle.

définir_autorisateur(autorisateur_rappel)

Registreappelable autorisateur_rappelà invoquer pour chaque tentative d'accès à une colonne d'une table dans la base de données. Le rappel doit renvoyer l'une desSQLITE_OKSQLITE_DENY, ouSQLITE_IGNOREpour signaler comment l'accès à la colonne doit être géré par la bibliothèque SQLite sous-jacente.

Le premier argument de la fonction de rappel indique le type d'opération à autoriser. Le deuxième et le troisième argument seront des arguments ouNoneen fonction du premier argument. Le 4ème argument est le nom de la base de données (« main », « temp », etc.) le cas échéant. Le 5ème argument est le nom du déclencheur ou de la vue le plus interne responsable de la tentative d'accès ouNonesi cette tentative d'accès provient directement du code SQL d'entrée.

Veuillez consulter la documentation SQLite concernant les valeurs possibles pour le premier argument et la signification du deuxième et du troisième argument en fonction du premier. Toutes les constantes nécessaires sont disponibles dans lesqlite3module.

Qui passeNonecommeautorisateur_rappeldésactivera l'autorisateur.

Modifié dans la version 3.11 : Ajout de la prise en charge de la désactivation de l'autorisateur à l'aideNone.

définir_gestionnaire_de_progression(gestionnaire_de_progrèsn)

Registreappelable gestionnaire_de_progrèsà invoquer pour chaqueninstructions de la machine virtuelle SQLite. Ceci est utile si vous souhaitez être appelé depuis SQLite lors d'opérations de longue durée, par exemple pour mettre à jour une interface graphique.

Si vous souhaitez effacer un gestionnaire de progression précédemment installé, appelez la méthode avecNonepourgestionnaire_de_progrès.

Le renvoi d'une valeur différente de zéro à partir de la fonction de gestionnaire mettra fin à la requête en cours d'exécution et entraînera la génération d'uneErreur de la base de donnéesexception.

définir_trace_callback(trace_callback)

Registreappelable trace_callbackà invoquer pour chaque instruction SQL réellement exécutée par le backend SQLite.

Le seul argument passé au rappel est l'instruction (commestr) qui est en cours d'exécution. La valeur de retour du rappel est ignorée. Notez que le backend n'exécute pas uniquement les instructions transmises àCurseur.execute()méthodes. D'autres sources incluentgestion des transactionsde lasqlite3module et l'exécution des déclencheurs définis dans la base de données courante.

Qui passeNonecommetrace_callbackdésactivera le rappel de trace.

Note

Les exceptions générées dans le rappel de trace ne sont pas propagées. En tant qu'aide au développement et au débogage, utilisezactiver_callback_tracebacks()pour activer l'impression des tracebacks à partir des exceptions déclenchées dans le rappel de trace.

Ajouté dans la version 3.3.

activer_load_extension(activé/)

Activez le moteur SQLite pour charger les extensions SQLite à partir de bibliothèques partagées siactivéestTrue; sinon, interdire le chargement des extensions SQLite. Les extensions SQLite peuvent définir de nouvelles fonctions, des agrégats ou de nouvelles implémentations de tables virtuelles. Une extension bien connue est l'extension de recherche en texte intégral distribuée avec SQLite.

Note

Lesqlite3Le module n'est pas construit avec la prise en charge des extensions chargeables par défaut, car certaines plates-formes (notamment macOS) ont des bibliothèques SQLite qui sont compilées sans cette fonctionnalité. Pour obtenir la prise en charge des extensions chargeables, vous devez passer le--activer les extensions SQLite chargeablesoption pourconfigurer.

Soulève unévénement d'audit sqlite3.enable_load_extensionavec des argumentsconnectionenabled.

Ajouté dans la version 3.2.

Modifié dans la version 3.10 : Ajout dusqlite3.enable_load_extensionévénement d'audit.

con.enable_load_extension(True)

# Load the fulltext search extension
con.execute("select load_extension('./fts3.so')")

# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")

# disable extension loading again
con.enable_load_extension(False)

# example from SQLite wiki
con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)")
con.executescript("""
    INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery');
    INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter');
    """)
for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):
    print(row)

charger_extension(chemin/*point d'entrée = Aucun)

Charger une extension SQLite à partir d'une bibliothèque partagée. Activer le chargement d'extension avecactiver_load_extension()avant d'appeler cette méthode.

Paramètres:

  • chemin (str) – Le chemin vers l’extension SQLite.

  • point d'accès (str | Aucun) – Nom du point d’entrée. SiNone(par défaut), SQLite proposera son propre nom de point d'entrée ; voir la documentation SQLiteChargement d'une extensionpour plus de détails.

Soulève unévénement d'audit sqlite3.load_extensionavec des argumentsconnectionpath.

Ajouté dans la version 3.2.

Modifié dans la version 3.10 : Ajout dusqlite3.load_extensionévénement d'audit.

Modifié dans la version 3.12 : Ajout dupoint d'accèsparamètre.

iterdump()

Renvoyer unitérateurpour vider la base de données en tant que code source SQL. Utile lors de la sauvegarde d'une base de données en mémoire pour une restauration ultérieure. Similaire à.dumpcommande dans lesqlite3coquille.

Exemple:

# Convert file example.db to SQL dump file dump.sql
con = sqlite3.connect('example.db')
with open('dump.sql', 'w') as f:
    for line in con.iterdump():
        f.write('%sn' % line)
con.close()

Voir également

Comment gérer les encodages de texte non UTF-8

sauvegarde(cible*pages=-1progrès=Aucunnom='main'sommeil=0,250)

Créer une sauvegarde d'une base de données SQLite.

Fonctionne même si la base de données est consultée par d'autres clients ou simultanément par la même connexion.

Paramètres:

  • cible (Connexion) – La connexion à la base de données dans laquelle enregistrer la sauvegarde.

  • pages (int) – Le nombre de pages à copier à la fois. Si égal ou inférieur à0, la base de données entière est copiée en une seule étape. La valeur par défaut est-1.

  • progrès (rappeler| Aucun) – Si défini sur unappelable, il est invoqué avec trois arguments entiers pour chaque itération de sauvegarde : lestatutde la dernière itération, lerestantnombre de pages restant à copier, et letotalnombre de pages. La valeur par défaut estNone.

  • nom (str) – Le nom de la base de données à sauvegarder. Soit"main"(par défaut) pour la base de données principale,"temp"pour la base de données temporaire, ou le nom d'une base de données personnalisée telle que jointe à l'aide duATTACH DATABASEInstruction SQL.

  • dormir (flotter) – Le nombre de secondes de veille entre les tentatives successives de sauvegarde des pages restantes.

Exemple 1, copier une base de données existante dans une autre :

def progress(status, remaining, total):
    print(f'Copied {total-remaining} of {total} pages...')

src = sqlite3.connect('example.db')
dst = sqlite3.connect('backup.db')
with dst:
    src.backup(dst, pages=1, progress=progress)
dst.close()
src.close()

Exemple 2, copier une base de données existante dans une copie transitoire :

src = sqlite3.connect('example.db')
dst = sqlite3.connect(':memory:')
src.backup(dst)
dst.close()
src.close()

Ajouté dans la version 3.7.

Voir également

Comment gérer les encodages de texte non UTF-8

obtenirlimite(catégorie/)

Obtenez une limite d’exécution de connexion.

Paramètres:

catégorie (int) - LeCatégorie de limite SQLiteà interroger.

Type de retour :

int

Augmente :

Erreur de programmation- Sicatégorien'est pas reconnu par la bibliothèque SQLite sous-jacente.

Exemple, interrogez la longueur maximale d'une instruction SQL pourConnexion con(la valeur par défaut est 1000000000) :

>>>

>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)
1000000000

Ajouté dans la version 3.11.

définirlimite(catégorielimitee/)

Définissez une limite d'exécution de connexion. Les tentatives d'augmentation d'une limite au-delà de sa limite supérieure stricte sont silencieusement tronquées à la limite supérieure stricte. Que la limite ait été modifiée ou non, la valeur précédente de la limite est renvoyée.

Paramètres:

  • catégorie (int) - LeCatégorie de limite SQLiteà régler.

  • limitee (int) – La valeur de la nouvelle limite. Si elle est négative, la limite actuelle reste inchangée.

Type de retour :

int

Augmente :

Erreur de programmation- Sicatégorien'est pas reconnu par la bibliothèque SQLite sous-jacente.

Par exemple, limitez le nombre de bases de données attachées à 1 pourConnexion con(la limite par défaut est 10) :

>>>

>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)
10
>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
1

Ajouté dans la version 3.11.

obtenirconfig(sur/)

Interroger une option de configuration de connexion booléenne.

Paramètres:

sur (int) - UNCode SQLITE_DBCONFIG.

Type de retour :

booléenéenéenéenéenéenéenéenéenéenéenéenéenéen

Ajouté dans la version 3.12.

définirconfig(suractiver=Vrai/)

Définissez une option de configuration de connexion booléenne.

Paramètres:

Ajouté dans la version 3.12.

sérialiser(*nom='main')

Sérialiser une base de données dans unoctetsobjet. Pour un fichier de base de données sur disque ordinaire, la sérialisation est simplement une copie du fichier sur disque. Pour une base de données en mémoire ou une base de données « temporaire », la sérialisation est la même séquence d'octets qui serait écrite sur le disque si cette base de données était sauvegardée sur le disque.

Paramètres:

nom (str) – Le nom de la base de données à sérialiser. La valeur par défaut est"main".

Type de retour :

octets

Note

Cette méthode n'est disponible que si la bibliothèque SQLite sous-jacente dispose de l'API de sérialisation.

Ajouté dans la version 3.11.

désérialiser(données/*nom='main')

Désérialiser unsérialisébase de données dans unConnexion. Cette méthode provoque la déconnexion de la connexion à la base de données.nom, et rouvrirnomen tant que base de données en mémoire basée sur la sérialisation contenue dansdonnées.

Paramètres:

  • données (octets) – Une base de données sérialisée.

  • nom (str) – Le nom de la base de données dans laquelle désérialiser. La valeur par défaut est"main".

Augmente :

Note

Cette méthode n'est disponible que si la bibliothèque SQLite sous-jacente dispose de l'API de désérialisation.

Ajouté dans la version 3.11.

validation automatique

Cet attribut contrôlePEP 249-comportement transactionnel conforme.autocommita trois valeurs autorisées :

En changeantautocommitàFalseouvrira une nouvelle transaction et la changera enTruevalidera toute transaction en attente.

VoirContrôle des transactions via l'attribut autocommitpour plus de détails.

Note

Leniveau_d'isolationl'attribut n'a aucun effet à moins quevalidation automatiqueestCONTRÔLE DES TRANSACTIONS HÉRITÉES.

Ajouté dans la version 3.12.

en_transaction

Cet attribut en lecture seule correspond au SQLite de bas niveaumode de validation automatique.

Truesi une transaction est active (il y a des modifications non validées),Falsesinon.

Ajouté dans la version 3.2.

niveau_d'isolation

Contrôle lemode de gestion des transactions héritéesdesqlite3. Si défini surNone, les transactions ne sont jamais ouvertes implicitement. Si défini sur l'une des"DEFERRED""IMMEDIATE", ou"EXCLUSIVE", correspondant au sous-jacentComportement des transactions SQLitegestion des transactions implicitesest effectuée.

Si elle n'est pas remplacée par laniveau_d'isolationparamètre deconnecter(), la valeur par défaut est"", qui est un alias pour"DEFERRED".

Note

En utilisantvalidation automatiquepour contrôler la gestion des transactions, il est recommandé d'utiliserisolation_levelisolation_leveln'a aucun effet à moins quevalidation automatiqueest réglé surCONTRÔLE DES TRANSACTIONS HÉRITÉES(le défaut).

usine_de_lignes

La premièreusine_de_lignespourLe curseurobjets créés à partir de cette connexion. L'affectation à cet attribut n'affecte pas larow_factorydes curseurs existants appartenant à cette connexion, uniquement les nouveaux.Nonepar défaut, ce qui signifie que chaque ligne est renvoyée sous forme detuple.

VoirComment créer et utiliser des usines de lignespour plus de détails.

fabrique_de_textes

UNappelablequi accepte unoctetsparamètre et renvoie une représentation textuelle de celui-ci. L'appelable est invoqué pour les valeurs SQLite avec leTEXTtype de données. Par défaut, cet attribut est défini surstr.

VoirComment gérer les encodages de texte non UTF-8pour plus de détails.

total_changes

Renvoie le nombre total de lignes de base de données qui ont été modifiées, insérées ou supprimées depuis l'ouverture de la connexion à la base de données.

Objets curseurs

UNCursorl'objet représente uncurseur de base de donnéesqui est utilisé pour exécuter des instructions SQL et gérer le contexte d'une opération de récupération. Les curseurs sont créés à l'aideConnexion.curseur(), ou en utilisant l'un desméthodes de raccourci de connexion.

Les objets curseur sontitérateurs, ce qui signifie que si vousexécuter()unSELECTrequête, vous pouvez simplement parcourir le curseur pour récupérer les lignes résultantes :

for row in cur.execute("SELECT t FROM data"):
    print(row)

classesqlite3.Curseur

UNLe curseurl'instance possède les attributs et méthodes suivants.

exécuter(SQLparamètres=()/)

Exécutez une seule instruction SQL, en liant éventuellement les valeurs Python à l'aide deespaces réservés.

Paramètres:

Augmente :

Erreur de programmation- SiSQLcontient plus d'une instruction SQL.

Sivalidation automatiqueestCONTRÔLE DES TRANSACTIONS HÉRITÉESniveau_d'isolationn'est pasNoneSQLest unINSERTUPDATEDELETE, ouREPLACEdéclaration, et il n'y a pas de transaction ouverte, une transaction est implicitement ouverte avant l'exécutionSQL.

Obsolète depuis la version 3.12, sera supprimé dans la version 3.14 :Avertissement d'obsolescenceest émis siespaces réservés nomméssont utilisés etparamètresest une séquence au lieu d'undict. À partir de Python 3.14,Erreur de programmationsera plutôt soulevé.

Utiliserexécuterscript()pour exécuter plusieurs instructions SQL.

exécuterplusieurs(SQLparamètres/)

Pour chaque article dansparamètres, exécutez à plusieurs reprises laparamétréInstruction SQL DMLSQL.

Utilise la même gestion de transaction implicite queexécuter().

Paramètres:

Augmente :

Erreur de programmation- SiSQLcontient plus d'une instruction SQL ou n'est pas une instruction DML.

Exemple:

rows = [
    ("row1",),
    ("row2",),
]
# cur is an sqlite3.Cursor object
cur.executemany("INSERT INTO data VALUES(?)", rows)

Note

Toutes les lignes résultantes sont ignorées, y compris les instructions DML avecClauses de RETOUR.

Obsolète depuis la version 3.12, sera supprimé dans la version 3.14 :Avertissement d'obsolescenceest émis siespaces réservés nomméssont utilisés et les éléments dansparamètressont des séquences au lieu dedicts. À partir de Python 3.14,Erreur de programmationsera plutôt soulevé.

exécuterscript(script_sql/)

Exécutez les instructions SQL dansscript_sql. Si lavalidation automatiqueestCONTRÔLE DES TRANSACTIONS HÉRITÉESet il y a une transaction en attente, une transaction impliciteCOMMITl'instruction est exécutée en premier. Aucun autre contrôle de transaction implicite n'est effectué ; tout contrôle de transaction doit être ajouté àscript_sql.

script_sqlDoit être unchaîne.

Exemple:

# cur is an sqlite3.Cursor object
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")

fetchone()

Siusine_de_lignesestNone, renvoie le résultat de la requête de ligne suivante sous forme detuple. Sinon, transmettez-le à la fabrique de lignes et renvoyez son résultat.Nonesi aucune autre donnée n'est disponible.

chercherbeaucoup(taille=curseur.taille du tableau)

Renvoyer le prochain ensemble de lignes d'un résultat de requête sous forme delisteeeeeeee. Renvoie une liste vide si aucune autre ligne n'est disponible.

Le nombre de lignes à récupérer par appel est spécifié par letailleparamètre. Sitaillen'est pas donné,taille du tableaudétermine le nombre de lignes à extraire. Si moins detailledes lignes sont disponibles, autant de lignes que disponibles sont renvoyées.

Notez qu'il y a des considérations de performances impliquées dans letailleparamètre. Pour des performances optimales, il est généralement préférable d'utiliser l'attribut arraysize. Si letailleun paramètre est utilisé, il est alors préférable qu'il conserve la même valeur d'unrécupérerplusieurs()appeler le suivant.

récupérer l'ensemble()

Renvoyer toutes les lignes (restantes) d'un résultat de requête sous forme delisteeeeeeee. Renvoie une liste vide si aucune ligne n'est disponible. Notez que letaille du tableauL'attribut peut affecter les performances de cette opération.

fermer()

Fermez le curseur maintenant (plutôt que lorsque vous le souhaitez)__del__est appelé).

Le curseur sera inutilisable à partir de ce moment ; unErreur de programmationune exception sera levée si une opération est tentée avec le curseur.

définir les tailles d'entrée (tailles/)

Requis par l'API DB. Ne fait rien danssqlite3.

définir la taille de sortie (taillecolonne=Aucune/)

Requis par l'API DB. Ne fait rien danssqlite3.

taille du tableau

Attribut de lecture/écriture qui contrôle le nombre de lignes renvoyées parrécupérerplusieurs()La valeur par défaut est 1, ce qui signifie qu'une seule ligne sera extraite par appel.

connexion

Attribut en lecture seule qui fournit la base de données SQLiteConnexionappartenant au curseur. UnLe curseurobjet créé en appelantavec.curseur()aura unconnexionattribut qui fait référence àescroquer:

>>>

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True
>>> con.close()

description

Attribut en lecture seule qui fournit les noms de colonnes de la dernière requête. Pour rester compatible avec l'API Python DB, il renvoie un tuple de 7 pour chaque colonne où se trouvent les six derniers éléments de chaque tupleNone.

Il est prévu pourSELECTdes instructions sans aucune ligne correspondante également.

dernierrowid

Attribut en lecture seule qui fournit l'ID de la dernière ligne insérée. Il n'est mis à jour qu'après une opération réussieINSERTouREPLACEdéclarations utilisant leexécuter()méthode. Pour les autres déclarations, aprèsexécutermany()ouexécuterscript(), ou si l'insertion a échoué, la valeur delastrowidreste inchangé. La valeur initiale delastrowidestNone.

Note

S'insère dansWITHOUT ROWIDles tables ne sont pas enregistrées.

Modifié dans la version 3.6 : Ajout de la prise en charge de laREPLACEdéclaration.

nombre de lignes

Attribut en lecture seule qui fournit le nombre de lignes modifiées pourINSERTUPDATEDELETE, etREPLACEdéclarations; est-1pour d'autres déclarations, y compris les requêtes CTE. Il n'est mis à jour que par leexécuter()etexécutermany()méthodes, une fois l'instruction exécutée jusqu'à son terme. Cela signifie que toutes les lignes résultantes doivent être récupérées pour querowcountà mettre à jour.

usine_de_lignes

Contrôler la manière dont une ligne est extraite de ceciCursorest représenté. SiNone, une ligne est représentée comme untuple. Peut être réglé sur le inclussqlite3.ligne; ou unappelablequi accepte deux arguments, unLe curseurobjet et letupledes valeurs de ligne et renvoie un objet personnalisé représentant une ligne SQLite.

Par défaut, quoiConnexion.row_factoryétait réglé sur lorsque leCursora été créé. L'attribution à cet attribut n'affecte pasConnexion.row_factoryde la connexion parent.

VoirComment créer et utiliser des usines de lignespour plus de détails.

Objets de ligne

classesqlite3.ligne

UNRowl'instance sert de solution hautement optimiséeusine_de_lignespourConnexionobjets. Il prend en charge l'itération, les tests d'égalité,longueur(), etcartographieaccès par nom de colonne et index.

DeuxRowles objets sont comparables s'ils ont des noms de colonnes et des valeurs identiques.

VoirComment créer et utiliser des usines de lignespour plus de détails.

clés()

Renvoyer unlisteeeeeeeedes noms de colonnes commecordes. Immédiatement après une requête, c'est le premier membre de chaque tuple dansCurseur.description.

Modifié dans la version 3.5 : ajout de la prise en charge du découpage.

Objets blob

classesqlite3.Blob

Ajouté dans la version 3.11.

UNGouttel'instance est uneobjet de type fichierqui peut lire et écrire des données dans un BLOB SQLite. Appelezlen(tache)pour obtenir la taille (nombre d'octets) du blob. Utilisez les indices ettranchespour un accès direct aux données blob.

Utilisez leGouttecomme ungestionnaire de contextepour s'assurer que la poignée du blob est fermée après utilisation.

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE test(blob_col blob)")
con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

# Write to our blob, using two write operations:
with con.blobopen("test", "blob_col", 1) as blob:
    blob.write(b"hello, ")
    blob.write(b"world.")
    # Modify the first and last bytes of our blob
    blob[0] = ord("H")
    blob[-1] = ord("!")

# Read the contents of our blob
with con.blobopen("test", "blob_col", 1) as blob:
    greeting = blob.read()

print(greeting)  # outputs "b'Hello, world!'"
con.close()

fermer()

Fermez le blob.

Le blob sera inutilisable à partir de ce moment.Erreur(ou sous-classe) une exception sera levée si une autre opération est tentée avec le blob.

lire(longueur=-1/)

Lirelongueuroctets de données du blob à la position de décalage actuelle. Si la fin du blob est atteinte, les données jusqu'à EOF seront renvoyées. Lorsquelongueurn'est pas spécifié, ou est négatif,lire()lira jusqu'à la fin du blob.

écrire(données/)

Écriredonnéesau blob au décalage actuel. Cette fonction ne peut pas modifier la longueur du blob. L'écriture au-delà de la fin du blob entraîneraValeurErreur.

dire()

Renvoie la position d'accès actuelle du blob.

chercher(compenserorigine=os.SEEK_SET/)

Définir la position d'accès actuelle du blob surcompenser. Leorigineel'argument par défaut estos.SEEK_SET(positionnement absolu du blob). Autres valeurs pourorigineesontos.SEEK_CUR(rechercher par rapport à la position actuelle) etos.SEEK_END(recherche par rapport à l'extrémité du blob).

Objets PrepareProtocol

classesqlite3.Préparer le protocole

Le seul but du type PrepareProtocol est d'agir comme unPEP 246protocole d'adaptation de style pour les objets qui peuvents'adapteràtypes SQLite natifs.

Des exceptions

La hiérarchie des exceptions est définie par DB-API 2.0 (PEP 249).

exceptionsqlite3.Avertissement

Cette exception n'est pas actuellement soulevée par lesqlite3module, mais peut être déclenché par des applications utilisantsqlite3, par exemple si une fonction définie par l'utilisateur tronque les données lors de l'insertion.Warningest une sous-classe deException.

exceptionsqlite3.Erreur

La classe de base des autres exceptions de ce module. Utilisez-la pour intercepter toutes les erreurs avec une seule exception.saufdéclaration.Errorest une sous-classe deException.

Si l'exception provient de la bibliothèque SQLite, les deux attributs suivants sont ajoutés à l'exception :

code_erreur_sqlite

Le code d'erreur numérique duAPI SQLite

Ajouté dans la version 3.11.

nom_erreur_sqlite

Le nom symbolique du code d'erreur numérique duAPI SQLite

Ajouté dans la version 3.11.

exceptionErreur d'interface sqlite3

Exception levée pour une mauvaise utilisation de l'API C SQLite de bas niveau. En d'autres termes, si cette exception est levée, cela indique probablement un bug dans lesqlite3module.InterfaceErrorest une sous-classe deErreur.

exceptionsqlite3.Erreur de base de données

Exception levée pour les erreurs liées à la base de données. Elle sert d'exception de base pour plusieurs types d'erreurs de base de données. Elle n'est levée implicitement que par les sous-classes spécialisées.DatabaseErrorest une sous-classe deErreur.

exceptionsqlite3.Erreur de données

Exception levée pour les erreurs causées par des problèmes avec les données traitées, comme des valeurs numériques hors limites et des chaînes trop longues.DataErrorest une sous-classe deErreur de la base de données.

exceptionsqlite3.Erreur opérationnelle

Exception levée pour les erreurs liées au fonctionnement de la base de données et qui ne sont pas nécessairement sous le contrôle du programmeur. Par exemple, le chemin de la base de données est introuvable ou une transaction n'a pas pu être traitée.OperationalErrorest une sous-classe deErreur de la base de données.

exceptionsqlite3.Erreur d'intégrité

Exception levée lorsque l'intégrité relationnelle de la base de données est affectée, par exemple en cas d'échec d'une vérification de clé étrangère. Il s'agit d'une sous-classe deErreur de la base de données.

exceptionsqlite3.Erreur interne

Exception générée lorsque SQLite rencontre une erreur interne. Si cette exception se produit, cela peut indiquer qu'il existe un problème avec la bibliothèque d'exécution SQLite.InternalErrorest une sous-classe deErreur de la base de données.

exceptionsqlite3.Erreur de programmation

Exception soulevée poursqlite3Erreurs de programmation d'API, par exemple en fournissant un nombre incorrect de liaisons à une requête ou en essayant d'opérer sur une requête ferméeConnexionProgrammingErrorest une sous-classe deErreur de la base de données.

exceptionsqlite3.Erreur non prise en charge

Exception levée dans le cas où une méthode ou une API de base de données n'est pas prise en charge par la bibliothèque SQLite sous-jacente. Par exemple, la définitiondéterministeàTruedanscréer_fonction(), si la bibliothèque SQLite sous-jacente ne prend pas en charge les fonctions déterministes.NotSupportedErrorest une sous-classe deErreur de la base de données.

Types SQLite et Python

SQLite prend en charge nativement les types suivants :NULLINTEGERREALTEXTBLOB.

Les types Python suivants peuvent ainsi être envoyés à SQLite sans aucun problème :

Type Python

Types de SQLite

None

NULL

int

INTEGER

flotter

REAL

str

TEXT

octets

BLOB

Voici comment les types SQLite sont convertis en types Python par défaut :

Types de SQLite

Type Python

NULL

None

INTEGER

int

REAL

flotter

TEXT

dépend defabrique_de_textesstrpar défaut

BLOB

octets

Le système de type dusqlite3Le module est extensible de deux manières : vous pouvez stocker des types Python supplémentaires dans une base de données SQLite viaadaptateurs d'objet, et vous pouvez laisser lesqlite3module convertit les types SQLite en types Python viaconvertisseurs.

Adaptateurs et convertisseurs par défaut (obsolète)

Note

Les adaptateurs et convertisseurs par défaut sont obsolètes à partir de Python 3.12. Utilisez plutôt leRecettes d'adaptateurs et de convertisseurset les adapter à vos besoins.

Les adaptateurs et convertisseurs par défaut obsolètes se composent de :

Note

Le convertisseur « timestamp » par défaut ignore les décalages UTC dans la base de données et renvoie toujours une valeur naïvedatetime.datetimeobjet. Pour conserver les décalages UTC dans les horodatages, laissez les convertisseurs désactivés ou enregistrez un convertisseur prenant en charge les décalages avecconvertisseur_registre().

Obsolète depuis la version 3.12.

Interface de ligne de commande

Lesqlite3le module peut être invoqué comme un script, en utilisant l'interpréteur-mswitch, afin de fournir un shell SQLite simple. La signature de l'argument est la suivante :

python -m sqlite3 [-h] [-v] [filename] [sql]

Taper.quitou CTRL-D pour quitter le shell.

-h, --aide

Imprimer l'aide CLI.

-v, --version

Imprimer la version de la bibliothèque SQLite sous-jacente.

Ajouté dans la version 3.12.

Guides pratiques

Comment utiliser des espaces réservés pour lier des valeurs dans des requêtes SQL

Les opérations SQL doivent généralement utiliser des valeurs provenant de variables Python. Cependant, méfiez-vous de l'utilisation des opérations de chaîne de Python pour assembler des requêtes, car elles sont vulnérables auxAttaques par injection SQL. Par exemple, un attaquant peut simplement fermer le guillemet simple et injecterOR TRUEpour sélectionner toutes les lignes :

>>>

>>> # Never do this -- insecure!
>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
>>> cur.execute(sql)

Utilisez plutôt la substitution de paramètres de l'API DB. Pour insérer une variable dans une chaîne de requête, utilisez un espace réservé dans la chaîne et remplacez les valeurs réelles dans la requête en les fournissant sous forme detupledes valeurs au deuxième argument du curseurexécuter()méthode.

Une instruction SQL peut utiliser l'un des deux types d'espaces réservés : des points d'interrogation (style qmark) ou des espaces réservés nommés (style nommé). Pour le style qmark,paramètresDoit être unséquencedont la longueur doit correspondre au nombre d'espaces réservés, ou unErreur de programmationest soulevé. Pour le style nommé,paramètresdoit être une instance d'undict(ou une sous-classe), qui doit contenir des clés pour tous les paramètres nommés ; tous les éléments supplémentaires sont ignorés. Voici un exemple des deux styles :

con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE lang(name, first_appeared)")

# This is the named style used with executemany():
data = (
    {"name": "C", "year": 1972},
    {"name": "Fortran", "year": 1957},
    {"name": "Python", "year": 1991},
    {"name": "Go", "year": 2009},
)
cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

# This is the qmark style used in a SELECT query:
params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()

Note

PEP 249les espaces réservés numériques sontpaspris en charge. S'ils sont utilisés, ils seront interprétés comme des espaces réservés nommés.

Comment adapter les types Python personnalisés aux valeurs SQLite

SQLite ne prend en charge qu'un ensemble limité de types de données en mode natif. Pour stocker des types Python personnalisés dans des bases de données SQLite,adaptereux à l'un desLes types Python que SQLite comprend nativement.

Il existe deux manières d'adapter les objets Python aux types SQLite : laisser votre objet s'adapter lui-même ou utiliser unadaptateur appelable. Ce dernier aura la priorité sur le premier. Pour une bibliothèque qui exporte un type personnalisé, il peut être judicieux de permettre à ce type de s'adapter. En tant que développeur d'applications, il peut être plus judicieux de prendre le contrôle direct en enregistrant des fonctions d'adaptateur personnalisées.

Comment écrire des objets adaptables

Supposons que nous ayons unPointclasse qui représente une paire de coordonnées,xety, dans un système de coordonnées cartésiennes. La paire de coordonnées sera stockée sous forme de chaîne de texte dans la base de données, en utilisant un point-virgule pour séparer les coordonnées. Cela peut être implémenté en ajoutant un__conform__(self, protocol)méthode qui renvoie la valeur adaptée. L'objet passé àprotocolesera de typePréparez le protocole.

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __conform__(self, protocol):
        if protocol is sqlite3.PrepareProtocol:
            return f"{self.x};{self.y}"

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(4.0, -3.2),))
print(cur.fetchone()[0])
con.close()
Comment enregistrer les appelables de l'adaptateur

L'autre possibilité est de créer une fonction qui convertit l'objet Python en un type compatible SQLite. Cette fonction peut ensuite être enregistrée à l'aide deregister_adapter().

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

def adapt_point(point):
    return f"{point.x};{point.y}"

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(1.0, 2.5),))
print(cur.fetchone()[0])
con.close()

Comment convertir des valeurs SQLite en types Python personnalisés

L'écriture d'un adaptateur vous permet de convertirdepuistypes Python personnalisésàValeurs SQLite. Pour pouvoir convertirdepuisValeurs SQLiteàtypes Python personnalisés, nous utilisonsconvertisseurs.

Revenons à laPointclasse. Nous avons stocké les coordonnées x et y séparées par des points-virgules sous forme de chaînes dans SQLite.

Tout d’abord, nous allons définir une fonction de conversion qui accepte la chaîne comme paramètre et construit unPointobjet de celui-ci.

Note

Les fonctions du convertisseur sonttoujourspassé unoctetsobjet, quel que soit le type de données SQLite sous-jacent.

def convert_point(s):
    x, y = map(float, s.split(b";"))
    return Point(x, y)

Nous devons maintenant diresqlite3lorsqu'il doit convertir une valeur SQLite donnée. Cela se fait lors de la connexion à une base de données, en utilisant ledétecter_typesparamètre deconnecter()Il existe trois options :

  • Implicite : ensembledétecter_typesàPARSE_DECLTYPES

  • Explicite : ensembledétecter_typesàANALYSER_LES_NOMS_DES_COLONNES

  • Les deux : ensembledétecter_typesàsqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMESLes noms de colonnes ont priorité sur les types déclarés.

L'exemple suivant illustre les approches implicites et explicites :

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

def adapt_point(point):
    return f"{point.x};{point.y}"

def convert_point(s):
    x, y = list(map(float, s.split(b";")))
    return Point(x, y)

# Register the adapter and converter
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)

# 1) Parse using declared types
p = Point(4.0, -3.2)
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.execute("CREATE TABLE test(p point)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute("SELECT p FROM test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()

# 2) Parse using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.execute("CREATE TABLE test(p)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute('SELECT p AS "p [point]" FROM test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()

Recettes d'adaptateurs et de convertisseurs

Cette section présente des recettes pour les adaptateurs et convertisseurs courants.

import datetime
import sqlite3

def adapt_date_iso(val):
    """Adapt datetime.date to ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(datetime.date, adapt_date_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

def convert_date(val):
    """Convert ISO 8601 date to datetime.date object."""
    return datetime.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return datetime.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return datetime.datetime.fromtimestamp(int(val))

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)

Comment utiliser les méthodes de raccourci de connexion

En utilisant leexécuter()exécutermany(), etexécuterscript()méthodes de laConnexionclasse, votre code peut être écrit de manière plus concise car vous n'avez pas à créer le (souvent superflu)Le curseurobjets explicitement. Au lieu de cela, leLe curseurles objets sont créés implicitement et ces méthodes de raccourci renvoient les objets curseur. De cette façon, vous pouvez exécuter uneSELECTdéclaration et l'itérer directement en utilisant un seul appel sur leConnexionobjet.

# Create and fill the table.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(name, first_appeared)")
data = [
    ("C++", 1985),
    ("Objective-C", 1984),
]
con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

# Print the table contents
for row in con.execute("SELECT name, first_appeared FROM lang"):
    print(row)

print("I just deleted", con.execute("DELETE FROM lang").rowcount, "rows")

# close() is not a shortcut method and it's not called automatically;
# the connection object should be closed manually
con.close()

Comment utiliser le gestionnaire de contexte de connexion

UNConnexionL'objet peut être utilisé comme gestionnaire de contexte qui valide ou annule automatiquement les transactions ouvertes en quittant le corps du gestionnaire de contexte. Si le corps de l'objetavecinstruction se termine sans exception, la transaction est validée. Si cette validation échoue, ou si le corps de lawithl'instruction génère une exception non interceptée, la transaction est annulée. Sivalidation automatiqueestFalse, une nouvelle transaction est implicitement ouverte après la validation ou l'annulation.

S'il n'y a pas de transaction ouverte à la sortie du corps duwithdéclaration, ou sivalidation automatiqueestTrue, le gestionnaire de contexte ne fait rien.

Note

Le gestionnaire de contexte n'ouvre pas implicitement une nouvelle transaction ni ne ferme la connexion. Si vous avez besoin d'un gestionnaire de contexte de fermeture, envisagez d'utilisercontextlib.closing().

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")

# Successful, con.commit() is called automatically afterwards
with con:
    con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# con.rollback() is called after the with block finishes with an exception,
# the exception is still raised and must be caught
try:
    with con:
        con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Connection object used as context manager only commits or rollbacks transactions,
# so the connection object should be closed manually
con.close()

Comment travailler avec les URI SQLite

Voici quelques astuces URI utiles :

  • Ouvrir une base de données en mode lecture seule :

>>>

>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
>>> con.execute("CREATE TABLE readonly(data)")
Traceback (most recent call last):
OperationalError: attempt to write a readonly database
  • Ne créez pas implicitement un nouveau fichier de base de données s'il n'existe pas déjà ; cela entraîneraErreur opérationnellesi impossible de créer un nouveau fichier :

>>>

>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (most recent call last):
OperationalError: unable to open database file
  • Créer une base de données nommée partagée en mémoire :

db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
with con1:
    con1.execute("CREATE TABLE shared(data)")
    con1.execute("INSERT INTO shared VALUES(28)")
res = con2.execute("SELECT data FROM shared")
assert res.fetchone() == (28,)

con1.close()
con2.close()

Vous trouverez plus d'informations sur cette fonctionnalité, y compris une liste de paramètres, dans leDocumentation sur les URI de SQLite.

Comment créer et utiliser des usines de lignes

Par défaut,sqlite3représente chaque ligne comme untuple. Si untuplene correspond pas à vos besoins, vous pouvez utiliser lesqlite3.ligneclasse ou une coutumeusine_de_lignes.

Alors querow_factoryexiste en tant qu'attribut à la fois sur leLe curseuret leConnexion, il est recommandé de définirConnexion.row_factory, donc tous les curseurs créés à partir de la connexion utiliseront la même fabrique de lignes.

Rowfournit un accès nommé indexé et insensible à la casse aux colonnes, avec une surcharge de mémoire et un impact sur les performances minimes sur une période donnée.tuple. UtiliserRowen tant qu'usine de lignes, attribuez-la à larow_factoryattribut:

>>>

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = sqlite3.Row

Les requêtes renvoient désormaisRowobjets:

>>>

>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0]         # Access by index.
'Earth'
>>> row["name"]    # Access by name.
'Earth'
>>> row["RADIUS"]  # Column names are case-insensitive.
6378
>>> con.close()

Note

LeFROMla clause peut être omise dans leSELECTcomme dans l'exemple ci-dessus. Dans de tels cas, SQLite renvoie une seule ligne avec des colonnes définies par des expressions, par exemple des littéraux, avec les alias donnésexpr AS alias.

Vous pouvez créer un personnaliséusine_de_lignesqui renvoie chaque ligne sous forme dedict, avec les noms de colonnes mappés aux valeurs :

def dict_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    return {key: value for key, value in zip(fields, row)}

En l'utilisant, les requêtes renvoient désormais undictau lieu d'untuple:

>>>

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
...     print(row)
{'a': 1, 'b': 2}
>>> con.close()

La fabrique de lignes suivante renvoie untuple nommé:

from collections import namedtuple

def namedtuple_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    cls = namedtuple("Row", fields)
    return cls._make(row)

namedtuple_factory()peut être utilisé comme suit :

>>>

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = namedtuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> row
Row(a=1, b=2)
>>> row[0]  # Indexed access.
1
>>> row.b   # Attribute access.
2
>>> con.close()

Avec quelques ajustements, la recette ci-dessus peut être adaptée pour utiliser unclasse de données, ou toute autre classe personnalisée, au lieu d'untuple nommé.

Comment gérer les encodages de texte non UTF-8

Par défaut,sqlite3les usagesstrpour adapter les valeurs SQLite avec leTEXTtype de données. Cela fonctionne bien pour le texte codé en UTF-8, mais cela peut échouer pour d'autres codages et UTF-8 non valide. Vous pouvez utiliser unfabrique_de_textespour gérer de tels cas.

À cause de SQLitesaisie flexible, il n'est pas rare de rencontrer des colonnes de tableau avec leTEXTtype de données contenant des codages non UTF-8, voire des données arbitraires. Pour illustrer cela, supposons que nous ayons une base de données avec du texte codé ISO-8859-2 (Latin-2), par exemple une table d'entrées de dictionnaire tchèque-anglais. En supposant que nous ayons maintenant unConnexionexempleconconnecté à cette base de données, nous pouvons décoder le texte codé en latin-2 en utilisant cecifabrique_de_textes:

con.text_factory = lambda data: str(data, encoding="latin2")

Pour les données UTF-8 non valides ou arbitraires stockées dansTEXTcolonnes du tableau, vous pouvez utiliser la technique suivante, empruntée à laGuide pratique Unicode:

con.text_factory = lambda data: str(data, errors="surrogateescape")

Note

Lesqlite3L'API du module ne prend pas en charge les chaînes contenant des substituts.

Voir également

Guide pratique Unicode

Explication

Contrôle des transactions

sqlite3propose plusieurs méthodes permettant de contrôler si, quand et comment les transactions de base de données sont ouvertes et fermées.Contrôle des transactions via l'attribut autocommitest recommandé, tandis queContrôle des transactions via l'attribut isolation_levelconserve le comportement pré-Python 3.12.

Contrôle des transactions via leautocommitattribut

La méthode recommandée pour contrôler le comportement des transactions est la suivante :Connexion.autocommitattribut, qui doit de préférence être défini à l'aide de la commandevalidation automatiqueparamètre deconnecter().

Il est suggéré de définirvalidation automatiqueàFalse, ce qui impliquePEP 249-contrôle des transactions conforme. Cela signifie :

  • sqlite3garantit qu'une transaction est toujours ouverte, doncconnecter()Connexion.commit(), etConnexion.rollback()ouvrira implicitement une nouvelle transaction (immédiatement après la fermeture de celle en attente, pour les deux dernières).sqlite3les usagesBEGIN DEFERREDdéclarations lors de l'ouverture des transactions.

  • Les transactions doivent être validées explicitement en utilisantcommit().

  • Les transactions doivent être annulées explicitement à l'aide derollback().

  • Une restauration implicite est effectuée si la base de données estfermer()-ed avec des modifications en attente.

Ensemblevalidation automatiqueàTruepour activer SQLitemode de validation automatique. Dans ce mode,Connexion.commit()etConnexion.rollback()n'ont aucun effet. Notez que le mode de validation automatique de SQLite est distinct duPEP 249-conformeConnexion.autocommitattribut; utiliserConnexion.en_transactionpour interroger le mode autocommit de bas niveau de SQLite.

Ensemblevalidation automatiqueàCONTRÔLE DES TRANSACTIONS HÉRITÉESde laisser le comportement de contrôle des transactions auConnexion.niveau_isolationattribut. VoirContrôle des transactions via l'attribut isolation_levelpour plus d'informations.

Contrôle des transactions via leisolation_levelattribut

Note

La méthode recommandée pour contrôler les transactions est via levalidation automatiqueattribut. VoirContrôle des transactions via l'attribut autocommit.

SiConnexion.autocommitest réglé surCONTRÔLE DES TRANSACTIONS HÉRITÉES(par défaut), le comportement de la transaction est contrôlé à l'aide de laConnexion.niveau_isolationattribut. Sinon,isolation_leveln'a aucun effet.

Si l'attribut de connexionniveau_d'isolationn'est pasNone, les nouvelles transactions sont implicitement ouvertes avantexécuter()etexécutermany()exécuteINSERTUPDATEDELETE, ouREPLACEinstructions ; pour les autres instructions, aucune gestion de transaction implicite n'est effectuée. Utilisez l'commettre()etretour en arriere()méthodes pour valider et annuler respectivement les transactions en attente. Vous pouvez choisir la méthode sous-jacenteComportement des transactions SQLite— c'est-à-dire si et quel type deBEGINdéclarationssqlite3exécute implicitement – ​​via leniveau_d'isolationattribut.

Siniveau_d'isolationest réglé surNone, aucune transaction n'est ouverte implicitement. Cela laisse la bibliothèque SQLite sous-jacente dansmode de validation automatique, mais permet également à l'utilisateur d'effectuer sa propre gestion des transactions à l'aide d'instructions SQL explicites. Le mode de validation automatique de la bibliothèque SQLite sous-jacente peut être interrogé à l'aide deen_transactionattribut.

Leexécuterscript()la méthode valide implicitement toute transaction en attente avant l'exécution du script SQL donné, quelle que soit la valeur deniveau_d'isolation.

Modifié dans la version 3.6 :sqlite3utilisé pour valider implicitement une transaction ouverte avant les instructions DDL. Ce n'est plus le cas.

Modifié dans la version 3.12 : la méthode recommandée pour contrôler les transactions est désormais via levalidation automatiqueattribut.