API Base de données
L'API base de données lit et écrit les données sans passer par les objets Document. Elle est plus rapide que l'API de documents, mais elle n'exécute pas les méthodes des contrôleurs.
Les exemples utilisent le type de document ToDo (champs description, status, priority, date, allocated_to). Les valeurs sont fictives.
frappe.db.get_list
frappe.db.get_list(doctype, filters=None, or_filters=None, fields=None, order_by=None, group_by=None, limit=None, offset=None, as_list=False, pluck=None)
Alias : frappe.get_list.
Renvoie une liste d'enregistrements d'un type de document. Dodock applique les autorisations de l'utilisateur de la session. Par défaut, chaque enregistrement est un dictionnaire.
frappe.db.get_list(
"ToDo",
filters={"status": "Open"},
fields=["description", "date"],
order_by="date desc",
offset=10,
limit=20,
as_list=True,
)
# résultat
# (("Relancer le devis", datetime.date(2026, 11, 4)),
# ("Préparer la réunion", datetime.date(2026, 11, 2)))
# Tâches dont la date est après le 8 septembre 2026
frappe.db.get_list("ToDo", filters={"date": [">", "2026-09-08"]})
# Tâches dont la description contient « devis »
frappe.db.get_list("ToDo", filters={"description": ["like", "%devis%"]})
# Liste simple des noms
frappe.db.get_list("ToDo", filters={"status": "Open"}, pluck="name")
# ["a1b2c3d4e5", "f6g7h8i9j0"]
# Nombre de tâches par statut
frappe.db.get_list(
"ToDo",
fields=["status", {"COUNT": "name", "as": "count"}],
group_by="status",
)
# [{"status": "Open", "count": 12},
# {"status": "Closed", "count": 40},
# {"status": "Cancelled", "count": 3}]
fields, comme "count(name) as count". Utilisez la syntaxe dictionnaire : {"COUNT": "name", "as": "count"}. Les fonctions disponibles incluent COUNT, SUM, AVG, MAX et MIN.Les arguments start, page_length, limit_start et limit_page_length fonctionnent encore, mais ils sont dépréciés. Utilisez offset et limit.
frappe.db.get_all
Alias : frappe.get_all.
Même signature que frappe.db.get_list, mais sans contrôle des autorisations. Utilisez-la dans du code serveur qui n'expose pas le résultat à n'importe quel utilisateur.
frappe.db.get_value
frappe.db.get_value(doctype, filters=None, fieldname="name", as_dict=False, order_by=..., cache=False, for_update=False)
Alias : frappe.get_value.
Renvoie la valeur d'un ou plusieurs champs du premier enregistrement trouvé. filters est le nom d'un document ou un dictionnaire de filtres. Si aucun enregistrement ne correspond, la méthode renvoie None.
# Une valeur
description = frappe.db.get_value("ToDo", "a1b2c3d4e5", "description")
# Plusieurs valeurs
description, status = frappe.db.get_value("ToDo", "a1b2c3d4e5", ["description", "status"])
# Dictionnaire
todo = frappe.db.get_value("ToDo", "a1b2c3d4e5", ["description", "status"], as_dict=True)
todo.description
# Avec des filtres : premier enregistrement qui correspond
description, status = frappe.db.get_value("ToDo", {"status": "Open"}, ["description", "status"])
frappe.db.get_values
frappe.db.get_values(doctype, filters=None, fieldname="name", as_dict=False, limit=None)
Comme get_value, mais renvoie tous les enregistrements qui correspondent, sous forme de liste.
frappe.db.get_values("ToDo", {"status": "Open"}, ["name", "description"], as_dict=True)
frappe.db.get_single_value
frappe.db.get_single_value(doctype, fieldname, cache=True)
Renvoie la valeur d'un champ d'un type de document unique (Single).
time_zone = frappe.db.get_single_value("System Settings", "time_zone")
frappe.db.set_value
frappe.db.set_value(doctype, name, fieldname, value=None, update_modified=True)
Écrit la valeur d'un ou plusieurs champs directement dans la base de données. name peut aussi être un dictionnaire de filtres. Dodock met à jour la date de modification, sauf avec update_modified=False.
# Un champ
frappe.db.set_value("ToDo", "a1b2c3d4e5", "status", "Closed")
# Plusieurs champs
frappe.db.set_value("ToDo", "a1b2c3d4e5", {"status": "Closed", "priority": "Low"})
# Sans changer la date de modification
frappe.db.set_value("ToDo", "a1b2c3d4e5", "status", "Closed", update_modified=False)
validate et on_update. Utilisez-la pour des champs techniques ou masqués. Pour un type de document unique, utilisez frappe.db.set_single_value(doctype, fieldname, value).frappe.db.exists
frappe.db.exists(doctype, name=None, cache=False)
Renvoie le nom du document s'il existe, sinon None.
# Par nom
frappe.db.exists("ToDo", "a1b2c3d4e5") # "a1b2c3d4e5"
# Par filtres
frappe.db.exists("ToDo", {"status": "Open", "allocated_to": "jean@example.com"})
# Par filtres, avec la clé "doctype"
frappe.db.exists({"doctype": "ToDo", "status": "Open"})
frappe.db.count
frappe.db.count(doctype, filters=None, cache=False)
Renvoie le nombre d'enregistrements qui correspondent aux filtres.
frappe.db.count("ToDo")
frappe.db.count("ToDo", {"status": "Open"})
frappe.db.delete
frappe.db.delete(doctype, filters=None)
Supprime les enregistrements qui correspondent aux filtres, avec une requête DELETE. Les méthodes du contrôleur ne s'exécutent pas et Dodock ne garde pas de copie dans Document supprimé. Pour supprimer un document avec ses contrôles, utilisez frappe.delete_doc.
frappe.db.delete("ToDo", {"status": "Cancelled"})
frappe.db.commit
frappe.db.commit()
Valide la transaction en cours avec la requête SQL COMMIT.
Dodock valide la transaction à la fin d'une requête web réussie de type POST, PUT, PATCH ou DELETE. Il ne la valide pas pour une requête GET. Vous n'avez donc pas besoin d'appeler cette méthode dans la plupart des cas. Appelez-la pour valider un long traitement en plusieurs fois, par exemple dans une tâche d'arrière-plan.
frappe.db.rollback
frappe.db.rollback(save_point=None)
Annule la transaction en cours avec la requête SQL ROLLBACK. Avec save_point, annule jusqu'au point de sauvegarde créé avec frappe.db.savepoint(nom).
Dodock annule la transaction si une exception se produit pendant une requête web.
SQL brut sur PostgreSQL
Sur PostgreSQL, Dodock utilise le pilote psycopg 3 (dépendance psycopg[binary]). Le pilote psycopg2 n'est plus utilisé : une application qui l'importe ou qui s'appuie sur ses adaptateurs de types doit être adaptée. Les méthodes ci-dessus ne changent pas. Cette section concerne le SQL que vous écrivez avec frappe.db.sql.
Liaison des paramètres
Pour les requêtes SELECT, INSERT, UPDATE, DELETE et WITH, les paramètres sont liés côté serveur. Les autres instructions (SET, DDL) sont liées côté client, car PostgreSQL n'accepte pas de paramètres liés dans ces instructions. Une requête de plus de 65 535 paramètres est aussi liée côté client.
| Valeur passée | Traitement |
|---|---|
| Entier ou booléen | Envoyé comme texte non typé (True devient "1"), pour que PostgreSQL le convertisse selon la colonne comparée |
IN %s avec une liste ou un tuple | Réécrit en = ANY(%s), avec un seul paramètre tableau, quelle que soit la longueur de la liste |
NOT IN %s avec une liste | Réécrit en <> ALL(%s) |
Autre séquence (par exemple (a, b) = %s) | Étendue en (%s, %s) |
Liste vide dans IN %s | Ne renvoie aucun enregistrement, sans erreur de syntaxe |
Dans un tableau, les nombres décimaux sont envoyés comme texte, pour qu'une liste du type [1, 1.5] reste valide.
# Exemple fictif : tâches par nom
frappe.db.sql(
"select name from tabToDo where name in %s order by name",
(["a1b2c3d4e5", "f6g7h8i9j0"],),
)
# (("a1b2c3d4e5",), ("f6g7h8i9j0",))
# Liste vide : aucun résultat
frappe.db.sql("select name from tabToDo where name in %s", ((),))
# ()
Paramètres sans type
Avec la liaison côté serveur, PostgreSQL doit pouvoir déduire le type d'un paramètre. Une requête brute comme %s IS NULL ou CONCAT(%s, ...) échoue. Ajoutez un transtypage explicite, par exemple CONCAT(%s::text, name). Le générateur de requêtes (frappe.qb) ajoute lui-même ::text aux paramètres des fonctions Concat et Concat_ws sur PostgreSQL.
Échappement
frappe.db.escape ne double plus les antislashs : C:\temp est relu tel quel. Les apostrophes sont toujours échappées.
Valeurs lues
- Les colonnes
json,jsonbetuuidsont lues comme des chaînes de caractères. - Les colonnes
timesont lues comme destimedelta. - Les nombres
numericsont lus comme desfloat.
Transactions et connexion
- Chaque transaction s'ouvre en isolation
REPEATABLE READ. Dodock règlesearch_path(selondb_schema) et le niveau d'isolation après la connexion, et non dans les options de démarrage, que PgBouncer rejette. Ces réglages survivent à unrollback. - Dodock ouvre lui-même chaque transaction (
START TRANSACTION) ; le pilote n'en ajoute pas. frappe.db.close()annule la transaction encore ouverte avant de fermer la connexion.frappe.db.connect()ferme la connexion qu'elle remplace.
Insertion en masse
Sur PostgreSQL, frappe.db.bulk_insert envoie les lignes par COPY, par lots de chunk_size lignes (10 000 par défaut). Avec ignore_duplicates=True, la méthode utilise un INSERT classique, car COPY n'a pas de clause ON CONFLICT. Une valeur de type liste, tuple ou dictionnaire n'est pas acceptée par COPY et lève une TypeError.
Erreur de plan en cache
Une connexion qui a préparé un SELECT * échoue une fois avec « cached plan must not change result type » si une autre connexion modifie la table entre-temps. La connexion récupère au rollback suivant : relancez la requête.