Référence de la fonction pour la gestion du plan de requête Aurora PostgreSQL

L'extension apg_plan_mgmt fournit les fonctions suivantes.

apg_plan_mgmt.copy_outline

Copiez un hachage et un contour de plan SQL donnés vers un hachage et un contour de plan SQL cible, écrasant ainsi le hachage et le contour de plan de la cible. Cette fonction est disponible dans apg_plan_mgmt versions 2.3 et supérieures.

Syntaxe

apg_plan_mgmt.copy_outline(
    source_sql_hash,
    source_plan_hash,
    target_sql_hash,
    target_plan_hash,
    force_update_target_plan_hash
)

Valeur renvoyée

Renvoie 0 lorsque la copie est réussie. Déclenche des exceptions pour les entrées non valides.

Paramètres

Paramètre	Description
source_sql_hash	L'ID sql_hash associé à la valeur plan_hash à copier vers la requête cible.
source_plan_hash	L'ID plan_hash à copier vers la requête cible.
target_sql_hash	L'ID sql_hash de la requête à mettre à jour avec le hachage et le plan source.
target_plan_hash	L'ID plan_hash de la requête à mettre à jour avec le hachage et le plan source.
force_update_target_plan_hash	(Facultatif) L'target_plan_hashID de la requête est mis à jour même si le plan source n'est pas reproductible pour. target_sql_hash Lorsqu'elle est définie sur true, la fonction peut être utilisée pour copier des plans dans des schémas où les noms des relations et les colonnes sont cohérents.

Notes d’utilisation

Cette fonction vous permet de copier un hachage de plan et un contour de plan qui utilise des astuces dans d'autres instructions similaires, ce qui vous évite d'avoir à utiliser des instructions d'astuces en ligne à chaque occurrence dans les instructions cibles. Si la requête cible mise à jour résulte en un plan invalide, cette fonction soulève une erreur et annule la tentative de mise à jour.

apg_plan_mgmt.delete_plan

Supprimez un plan géré.

Syntaxe

apg_plan_mgmt.delete_plan(
    sql_hash,
    plan_hash
) 

Valeur renvoyée

Renvoie 0 si la suppression a réussi ou -1 si elle a échoué.

Paramètres

Paramètre	Description
sql_hash	ID sql_hash de l'instruction SQL gérée du plan.
plan_hash	ID plan_hash du plan géré.

apg_plan_mgmt.evolve_plan_baselines

Vérifie si un plan déjà approuvé est plus rapide ou si un plan identifié par l'optimiseur de requêtes en tant que plan à coût minimal est plus rapide.

Syntaxe

apg_plan_mgmt.evolve_plan_baselines(
    sql_hash, 
    plan_hash,
    min_speedup_factor,
    action
)

Valeur renvoyée

Nombre de plans qui n'étaient pas plus rapides que le meilleur plan approuvé.

Paramètres

Paramètre	Description
sql_hash	ID sql_hash de l'instruction SQL gérée du plan.
plan_hash	ID plan_hash du plan géré. Utilisez NULL pour indiquer que tous les plans ont la même valeur d'ID sql_hash.
min_speedup_factor	Le facteur de montée en charge minimum est le nombre de fois qu'un plan doit être plus rapide que le meilleur des plans déjà approuvés pour être approuvé. Sinon, ce facteur peut être le nombre de fois qu'un plan doit être plus lent pour être rejeté ou désactivé. Il s'agit d'une valeur flottante positive.
action	Action que la fonction doit exécuter. Les valeurs valides sont notamment les suivantes. La casse n'a pas d'importance. 'disable' – Désactivez tout plan correspondant qui ne respecte pas le facteur de montée en charge minimum. 'approve' – Activez tout plan correspondant qui respecte le facteur de montée en charge minimum et définissez son statut sur approved. 'reject' – Pour chaque plan correspondant qui ne respecte pas le facteur de montée en charge minimum, définissez son statut sur rejected. NULL – La fonction renvoie simplement le nombre de plans qui ne présentent aucun avantage en termes de performances, car ils ne respectent pas le facteur de montée en charge minimum.

Notes d'utilisation

Définissez les plans spécifiés sur approuvé, rejeté ou désactivé selon que la durée de planification et d'exécution est plus rapide que celle du meilleur plan approuvé selon un facteur que vous pouvez définir. Le paramètre d'action peut être défini sur 'approve' ou 'reject' pour approuver ou rejeter automatiquement un plan qui respecte les critères de performance. Vous pouvez également le définir sur '' (chaîne vide) pour tester les performances et produire un rapport, mais sans effectuer d'action.

Vous pouvez inutilement éviter d'exécuter à nouveau la fonction apg_plan_mgmt.evolve_plan_baselines pour un plan sur lequel elle a été exécutée récemment. À cette fin, limitez les plans aux plans non approuvés créés récemment. Vous pouvez également éviter d'exécuter la fonction apg_plan_mgmt.evolve_plan_baselines sur un plan approuvé qui a reçu un horodatage last_verified récent.

Effectuez un test des performances pour comparer la durée de planification et d'exécution de chaque plan par rapport à d'autres plans de la référence. Dans certains cas, il n'existe qu'un seul plan pour une instruction et ce plan est approuvé. Dans ce cas, comparez la durée de planification et la durée d'exécution du plan à ce que seraient ces durées si aucun plan n'était utilisé.

L'avantage (ou le désavantage) incrémentiel de chaque plan est enregistré dans la vue apg_plan_mgmt.dba_plans de la colonne total_time_benefit_ms. Lorsque cette valeur est positive, il y a un avantage mesurable en termes de performances à inclure ce plan dans la référence.

En plus de consigner la durée de planification et d'exécution de chaque plan candidat, la colonne last_verified de la vue apg_plan_mgmt.dba_plans est mise à jour avec current_timestamp. L'horodatage last_verified peut être utilisé pour éviter d'exécuter à nouveau cette fonction sur un plan dont les performances ont récemment été vérifiées.

apg_plan_mgmt.get_explain_plan

Génère le texte d'une instruction EXPLAIN pour l'instruction SQL spécifiée.

Syntaxe

apg_plan_mgmt.get_explain_plan(
    sql_hash,
    plan_hash,
    [explainOptionList]
) 

Valeur renvoyée

Renvoie des statistiques d'exécution pour les instructions SQL spécifiées. Utiliser sans explainOptionList pour renvoyer un plan EXPLAIN simple.

Paramètres

Paramètre	Description
sql_hash	ID sql_hash de l'instruction SQL gérée du plan.
plan_hash	ID plan_hash du plan géré.
explainOptionList	Liste séparée par des virgules d'options d'explication. Les valeurs valides incluent 'analyze', 'verbose', 'buffers', 'hashes' et 'format json'. Si la liste des explainOptionList est NULL ou une chaîne vide (''), cette fonction génère une instruction EXPLAIN, sans aucune statistique.

Notes d'utilisation

Pour le explainOptionList, vous pouvez utiliser l'une des mêmes options que vous utiliseriez avec une instruction EXPLAIN. L'optimiseur Aurora PostgreSQL concatène la liste des options que vous fournissez à l'instruction EXPLAIN.

apg_plan_mgmt.plan_last_used

Renvoie la date last_used du plan spécifié depuis la mémoire partagée.

Note

La valeur de la mémoire partagée est toujours à jour sur l'instance de base de données principale du cluster de bases de données. La valeur est uniquement vidée vers périodiquement dans la colonne last_used de la vue apg_plan_mgmt.dba_plans.

Syntaxe

apg_plan_mgmt.plan_last_used(
    sql_hash,
    plan_hash
) 

Valeur renvoyée

Renvoie la date last_used.

Paramètres

Paramètre	Description
sql_hash	ID sql_hash de l'instruction SQL gérée du plan.
plan_hash	ID plan_hash du plan géré.

apg_plan_mgmt.reload

Recharge les plans dans la mémoire partagée depuis la vue apg_plan_mgmt.dba_plans.

Syntaxe

apg_plan_mgmt.reload()

Valeur renvoyée

Aucun.

Paramètres

Aucune.

Notes d'utilisation

Appelez reload dans les cas suivants :

• Utilisez-le pour rafraîchir immédiatement la mémoire partagée d'un réplica en lecture seule, plutôt que d'attendre que les nouveaux plans se propagent au réplica.

• Utilisez-le après l'importation de plans gérés.

apg_plan_mgmt.set_plan_enabled

Activez ou désactivez un plan géré.

Syntaxe

apg_plan_mgmt.set_plan_enabled(
    sql_hash, 
    plan_hash, 
    [true | false]
)

Valeur renvoyée

Renvoie 0 si le paramétrage a réussi ou -1 s'il a échoué.

Paramètres

Paramètre	Description
sql_hash	ID sql_hash de l'instruction SQL gérée du plan.
plan_hash	ID plan_hash du plan géré.
enabled	Valeur booléenne true ou false : La valeur true active le plan. La valeur false désactive le plan.

apg_plan_mgmt.set_plan_status

Définissez le statut d'un plan géré sur Approved, Unapproved, Rejected ou Preferred.

Syntaxe

apg_plan_mgmt.set_plan_status(
    sql_hash, 
    plan_hash, 
    status
)

Valeur renvoyée

Renvoie 0 si le paramétrage a réussi ou -1 s'il a échoué.

Paramètres

Paramètre	Description
sql_hash	ID sql_hash de l'instruction SQL gérée du plan.
plan_hash	ID plan_hash du plan géré.
status	Chaîne dotée de l'une des valeurs suivantes : 'Approved' 'Unapproved' 'Rejected' 'Preferred' La casse que vous utilisez n'a pas d'importance, mais la valeur du statut est définie avec des capitales initiales dans la vue apg_plan_mgmt.dba_plans. Pour de plus amples informations sur ces valeurs, veuillez consulter la rubrique status de la section Référence pour la vue apg_plan_mgmt.dba_plans.

apg_plan_mgmt.update_plans_last_used

Met immédiatement à jour le tableau des plans avec la date last_used stockée dans la mémoire partagée.

Syntaxe

apg_plan_mgmt.update_plans_last_used()

Valeur renvoyée

Aucun.

Paramètres

Aucune.

Notes d'utilisation

Appelez update_plans_last_used pour veiller à ce que les requêtes de la colonne dba_plans.last_used utilise les informations les plus récentes. Si la date last_used n'est pas immédiatement mise à jour, un processus en arrière-plan met à jour la table des plans avec la date last_used une fois par heure (par défaut).

Par exemple, si une instruction avec un certain sql_hash commence à s'exécuter lentement, vous pouvez déterminer quels plans de cette instruction ont été exécutés depuis le début de la régression des performances. Pour ce faire, commencez par vider les données de la mémoire partagée sur le disque afin que les dates last_used soient à jour, puis interrogez tous les plans du sql_hash de l'instruction présentant la régression des performances. Dans la requête, assurez-vous que le date last_used est supérieure ou égale à la date à laquelle la régression des performances a commencé. La requête identifie le plan ou l'ensemble de plans susceptibles d'être responsables de la régression des performances. Vous pouvez utiliser apg_plan_mgmt.get_explain_plan avec explainOptionList défini sur verbose, hashes. Vous pouvez également utiliser apg_plan_mgmt.evolve_plan_baselines pour analyser le plan et tous les autres plans susceptibles de s'avérer plus performants.

La fonction update_plans_last_used affecte uniquement l'instance de base de données principale du cluster de bases de données.

apg_plan_mgmt.validate_plans

Validez le fait que l'optimiseur peut toujours recréer des plans. L'optimiseur valide les plans Approved, Unapproved et Preferred, que les plans soient activés ou désactivés. Les plans Rejected ne sont pas validés. Vous pouvez également utiliser la fonction apg_plan_mgmt.validate_plans pour supprimer ou désactiver des plans non valides.

Syntaxe

apg_plan_mgmt.validate_plans(
    sql_hash, 
    plan_hash, 
    action)
            
apg_plan_mgmt.validate_plans(
    action)

Valeur renvoyée

Nombre de plans non valides.

Paramètres

Paramètre	Description
sql_hash	ID sql_hash de l'instruction SQL gérée du plan.
plan_hash	ID plan_hash du plan géré. Utilisez NULL pour inclure tous les plans ayant la même valeur d'ID sql_hash.
action	Action que la fonction doit exécuter pour les plans non valides. Les valeurs de chaînes valides sont notamment les suivantes. La casse n'a pas d'importance. 'disable' – Chaque plan non valide est désactivé. 'delete' – Chaque plan non valide est supprimé. 'update_plan_hash' – Met à jour l'ID plan_hash des plans qui ne peuvent pas être reproduits exactement. Il vous permet aussi de corriger un plan en réécrivant le code SQL. Vous pouvez ensuite enregistrer le bon plan comme plan Approved pour le SQL original. NULL – La fonction renvoie simplement le nombre de plans non valides. Aucune autre action n'est exécutée. '' – Une chaîne vide génère un message indiquant le nombre de plans valides et non valides. Toute autre valeur est traitée comme une chaîne vide.

Notes d'utilisation

Utilisez le formulaire validate_plans(action) pour valider tous les plans gérés pour toutes les instructions gérées dans la vue apg_plan_mgmt.dba_plans complète.

Utilisez le formulaire validate_plans(sql_hash, plan_hash, action) pour valider un plan géré spécifié avec plan_hash pour une instruction gérée spécifiée avec sql_hash.

Utilisez le formulaire validate_plans(sql_hash, NULL, action) pour valider tous les plans gérés pour l'instruction gérée spécifiée avec sql_hash.