Tutoriels on Benjamin Geer

Créer une application hypermédia en Rust

Mon, 05 Oct 2026 07:02:00 +0000

Ceci est le troisième article d’une série :

Créer des applications hypermédia sécurisées pour un monde aux ressources limitées, qui présente la série
Créer une application hypermédia en Go
l’article présent

Aperçu de l’application #

L’application qui sert d’exemple dans Hypermedia Systems est une application CRUD qui gère une liste de contacts. Le livre montrer comment créer une application hypermédia qui offre bonne interface utilisateur, en alternative aux applications monopages. Grâce à une minuscule bibliothèque JavaScript (htmx) et à quelques attributs déclaratifs sur les éléments HTML, toutes sortes d’interactions utilisateur peuvent récupérer des fragments de code HTML depuis le serveur et ne modifier que certaines parties de la page. Par exemple, quand on passe d’une page à une autre dans la liste des contacts ou qu’on supprime un contact, la liste affichée s’actualise sans que la page ne soit rechargée.

Réalisons cette application en Rust, avec deux objectifs :

La rendre plus réaliste en ajoutant une interface utilisateur internationalisée, une base de données relationnelle avec un index de recherche en texte intégral, une meilleure validation des entrées, une pagination par curseur et des tests d’interface utilisateur.
La rendre facile à maintenir, en limitant au maximum le code répétitif et en tirant parti des vérifications effectuées lors de la compilation pour éviter les bugs.

Nous utiliserons dans un premier temps une base de données SQLite, puis passerons à PostgreSQL dans une étape ultérieure. Le code source des deux versions est disponible ici :

Bibliothèques #

Notre première tâche est de choisir quelques bibliothèques.

Templates HTML #

Notre interface utilisateur est basée sur des templates HTML. Il y a un template de mise en page qui fournit un en-tête et affiche des messages d’information (comme « Le contact a été ajouté ») en réponse aux actions de l’utilisateur·ice. D’autres templates, comme un formulaire permettant de modifier un contact, peuvent être imbriqués dans cette mise en page. Il y a aussi des templates qui génèrent des fragments de code HTML qui remplacent une ou plusieurs parties de la page affichée. Par exemple, quand on clique sur un lien de pagination, la liste des contacts s’actualise ainsi que les liens de pagination.

Il nous faudra donc un moteur de template, de préférence à typage sûr. Les moteurs de template à typage sûr se déclinent essentiellement en deux catégories : celle qui permet d’écrire quasiment du code HTML standard, et celle qui permet d’exprimer la structure d’un document HTML dans un langage de programmation. Je préfère la première catégorie, car plus la syntaxe des templates se rapproche du HTML, plus il sera facile pour un concepteur UX, ou toute personne maîtrisant HTML, de travailler sur ces templates sans avoir à connaître Rust.

J’ai choisi Askama, qui est facile à utiliser et compile les templates en Rust. Comme sa syntaxe est basée sur celle de Jinja, les environnements de développement qui prennent en charge Jinja fonctionneront aussi avec Askama. Pour l’utiliser, on écrit les templates dans des fichiers HTML. Pour chaque template, on écrit une définition de struct en Rust qui contient les variables du template et qui se réfère au fichier HTML via une macro. Dans les implémentations de nos points de terminaison HTTP, nous appellerons la méthode render de cette struct pour générer du code HTML.

Internationalisation #

Nous souhaitons que notre application prenne en charge différentes langues. Dans cet exemple, j’ai réalisé la prise en charge de l’anglais et du français. Pour faciliter la maintenance, nous voulons éviter de créer une version différente de chaque template pour chaque langue, ou d’encombrer les templates avec les différentes traductions d’un même message. Il nous faut donc une bibliothèque permettant d’appeler une fonction depuis un template et d’obtenir la traduction d’un message dans la langue cible.

Un point important à prendre en compte est le choix des concepteurs de la bibliothèque quant au type d’identifiant qui représente un message. Certaines bibliothèques (comme gettext) utilisent le texte entier du message dans la langue par défaut comme identifiant de message. Les limites de cette approche sont clairement exposées dans le contract social de Project Fluent:

Tout d’abord, cela signifie que toute modification apportée à la chaîne source invalide toutes les traductions de cette chaîne. Cela alourdit considérablement la charge de travail des développeur·euses, qui doivent veiller à ne jamais modifier les messages dans la langue source, car cela entraînerait la nécessité de mettre à jour toutes les traductions.

D’autre part, cela complique l’utilisation de plusieurs messages qui ont la même chaîne source mais qui devraient être traduits différemment.

Je préfère donc les bibliothèques qui utilisent des identifiants de message uniques choisis par les développeur·euses.

Un autre critère important dans le choix d’une bibliothèque concerne la manière dont elle gère les pluriels. Alors que les pluriels sont relativement simples en français (il n’y a que deux catégories, le singulier et le pluriel), de nombreuses langues comportent davantage de catégories ainsi que des règles syntaxiques qui nécessitent d’adapter la phrase de manière plus complexe en fonction du nombre exprimé. Une bonne bibliothèque d’internationalisation doit implémenter les règles de pluriel CLDR d’Unicode, qui prennent en charge plus de 200 langues.

J’avais envie d’essayer Project Fluent, mais il semblerait que ce projet ait été abandonné. J’ai donc opté pour karatepe, qui offre les fonctionnalités dont on a besoin. Karatepe fournit un langage dédié permettant de définir les messages et d’écrire leurs traductions, ainsi qu’une macro qui compile les définitions en fonctions Rust. Voici, par exemple, une définition de message qui prend un paramètre numérique, amount :

`1`	`contacts_count(amount: ..)`

Et voici sa traduction en français :

contacts_count(amount) = ({amount} {amount => {
    one => contact
    _ => contacts
  }} au total)

La définition du message est compilée en une fonction Rust, contacts_count, que nous pouvons appeler directement depuis un template. Lors de l’exécution, nous pouvons accéder à la traduction d’un message via la Translation correspondant à la langue cible. Nous verrons ci-dessous comment obtenir celle qui convient.

Puisque nous internationalisons l’application, nous pouvons aussi améliorer la validité interculturelle des noms de champs : au lieu de first_name (« prénom ») et last_name (« nom de famille »), qui ne conviennent pas aux langues (comme le chinois) dans lesquelles le nom de famille vient en premier, nous suivrons la recommandation de l’ontologie FOAF, qui préconise given_name (« nom personnel ») et family_name (« nom de famille »).

Accès à la base de données et migration de schéma #

Nous pourrions utiliser un mapping object-relationnel (ORM), mais à mon avis il vaut mieux écrire notre code SQL nous-mêmes. Les ORM peuvent générer des requêtes inefficaces.¹ Écrire notre propre code SQL nous permet de tirer pleinement parti des fonctionnalités du SQL moderne et de ses possibilités d’optimisation des requêtes, notamment en concevant conjointement les requêtes et les index, et en affinant les requêtes en tenant compte des plans d’exécution choisis par l’optimiseur de requêtes de la base de données. (Voir mon article Optimiser des requêtes PostgreSQL avec un jeu de données ouvert pour un exemple.)

À mon avis, l’idéal est d’avoir une bibliothèque qui implémente la sûreté du typage pour les requêtes SQL, de sorte que celles-ci soient vérifiées lors de la compilation et renvoient automatiquement des structs Rust. C’est exactement ce que fait la crate SQLx. Elle peut même renvoyer nos propres structs en dérivant son trait FromRow.

Par exemple, imaginons que nous ayons mal orthographié le nom d’une colonne (familyname au lieu de family_name) dans une requête :

let contact: Contact = sqlx::query_as!(
    Contact,
    "SELECT id, familyname, given_name, phone, email
    FROM contact WHERE id = $1",
    id
)
.fetch_one(&mut *tx)
.await?;

Par défaut, la macro query_as! se connectera à la base de données de développement lors de la compilation pour vérifier la requête, et nous obtiendrons une erreur de compilation :

1
2

error: error returned from database: (code: 1) no such column: familyname
   --> src/db.rs:236:23

SQLx utilise aussi des instructions préparées pour prévenir les attaques par injection SQL et fournit un outil en ligne de commande pour gérer les migrations de schéma.

Framework de serveur HTTP #

Nous utiliserons axum, qui implémente des conversions à typage sûr entre les requêtes et les structs Rust via Serde, et qui est facile à utiliser avec Askama.

Tests d’interface utilisateur #

S’il s’agissait de créer une application monopage, notre serveur aurait une API JSON, et nous pourrions écrire des tests vérifiant qu’il renvoie les données correctes pour différentes requêtes. Mais notre application renvoie du code HTML. Nous allons donc écrire des tests analogues aux tests d’API JSON, en nous concentrant sur les fonctionnalités pratiques des réponses HTML. À l’aide de la crate dom_query, nous analyserons ces réponses et utiliserons des sélecteurs CSS pour vérifier le contenu de certains éléments. Nous aurons ainsi la liberté de modifier considérablement la conception graphique des pages sans avoir à changer nos tests.

Conception de la base de données #

(Si vous avez déjà lu la version Go de cet article, vous pouvez sauter cette section.)

Notre base de données est très simple. Il y a une seule table, contact :

CREATE TABLE IF NOT EXISTS contact (
  id INTEGER PRIMARY KEY,
  family_name TEXT NOT NULL,
  given_name TEXT NOT NULL,
  phone TEXT,
  email TEXT UNIQUE NOT NULL
) STRICT;

Il y a toutefois quelques détails à prendre en compte.

J’ai défini la table avec l’option STRICT. Par défaut, SQLite dispose d’un système de types très flexible, ce que certaines personnes apprécient. Je préfère obtenir des erreurs quand il y a un bug dans mon programme. Avec l’option STRICT, SQLite effectue une vérification stricte des types lors de l’exécution, en plus des vérifications effectuées par sqlc lors de la compilation.

Les colonnes pouvant prendre la valeur NULL ajoutent un peu de complexité à notre code. Par conséquent, pour simplifier les choses dans cet exemple, nous n’autoriserons que la colonne phone à prendre la valeur NULL.

L’application devrait afficher la liste des contacts triée selon un certain ordre. Nous utiliserons ORDER BY family_name, given_name, email. Pour optimiser les performances, nous ajoutons un index correspondant à cet ordre de tri :

1
2

CREATE INDEX IF NOT EXISTS idx_contact_sort
ON contact (family_name, given_name, email);

Comme l’application exige que les adresses e-mail soient uniques, j’ai mis une contrainte UNIQUE sur le champ email, et nous aurons besoin de faire une requête comme celle-ci :

`1`	`SELECT 1 FROM contact WHERE email = ?;`

Pour que cette requête soit efficace, nous créons un index sur la colonne email :

`1`	`CREATE INDEX IF NOT EXISTS idx_contact_email ON contact (email);`

Nous souhaitons disposer d’un index de recherche en texte intégral nous permettant de trouver les contacts dont le nom correspond à une chaîne de caractères. L’utilisateur pourra saisir les premières lettres de given_name et/ou de family_name pour obtenir une liste des contacts correspondants. Heureusement, SQLite propose un module de recherche en texte intégral, qui s’appelle FTS5. Pour l’utiliser, il faut créer une table virtuelle pour y stocker l’index :

CREATE VIRTUAL TABLE IF NOT EXISTS contact_fts USING fts5(
    family_name,
    given_name,
    phone UNINDEXED,
    email UNINDEXED,
    content = 'contact',
    content_rowid = 'id'
);

Nous utiliserons des déclencheurs pour que la table contact_fts reste synchronisée avec la table contact. Et voilà qui conclut notre schéma de base de données.

Architecture logicielle #

Étant donné la simplicité de cette application CRUD, une architecture modèle-vue-contrôleur suffira. Les vues sont des templates HTML et les contrôleurs sont des routes HTTP. Le type principal du modèle est Contact, que nous verrons dans un instant. La couche d’abstraction de base de données est tout simplement une struct qui contient le pool de connexions et dispose de méthodes comme celle-ci :

1
2
3

pub async fn get(&self, id: ContactId) -> Result<Contact, DatabaseError> {
    // ...
}

Analyser au lieu de valider #

Nous allons appliquer le principe d’Alexis King, Parse, don’t validate. En bref, cela veut dire que, plutôt que de représenter, par exemple, une adresse mail sous la forme d’un &str, on utilise le motif newtype en créant un type dédié, appelé Email, qui ne peut être construit qu’à partir d’une entrée valide. Cela présente plusieurs avantages :

Toutes les fonctions de la couche de base de données n’acceptent que des newtypes et des structs composées de newtypes et ne peuvent donc pas recevoir de valeurs non valides.
Comme il est impossible de créer une valeur non valide, on n’a jamais à se demander si une valeur a déjà été validée, et on ne risque pas de la valider deux fois.
La nécessité de passer un &Email à une fonction au lieu d’un &str peut permettre d’éviter certaines erreurs, comme le fait d’utiliser la mauvaise variable dans un appel de fonction ou de se tromper dans l’ordre des paramètres.
Les paramètres des fonctions deviennent plus clairs : after: &Cursor est plus explicite que after: &str.

Nous utiliserons la bibliothèque nutype pour définir nos newtypes. Elle propose toute une gamme de fonctions de validation intégrées, par exemple pour la validation à l’aide d’expressions régulières. Comme il s’agit d’une application internationalisée, nous utiliserons des expressions régulières Unicode pour prendre en charge :

tous les caractères Unicode qui pourrait figurer dans le nom d’une personne
n’importe quel numéro de téléphone utilisable dans n’importe quel pays
l’internationalisation des adresses de courrier électronique

Par exemple, ma modeste tentative d’expression régulière pour les noms accepte des groupes de lettres et de caractères Unicode, séparés par des espaces et/ou des signes de ponctuation :

`1`	`^[\p{L}\p{M}]+(?:(?:\p{P}\p{Zs}\|[\p{P}\p{Zs}])[\p{L}\p{M}]+)*\p{P}?$`

Donc, si vous vous appelez 曼玉-فاتن, tout va bien. Nous pouvons maintenant définir un newtype :

#[nutype(
    validate(regex = NAME_REGEX, len_char_max = 50),
    derive(Debug, Display, PartialEq, Clone, AsRef, Serialize),
    derive_unchecked(sqlx::Type),
)]
#[sqlx(transparent)]
pub struct GivenName(String);

Cela génère un constructeur, GivenName::try_new, qui prend une chaîne de caractères en paramètre et renvoie un Result<GivenName, GivenNameError>. Nous avons également précisé que nous souhaitons que SQLx puisse construire un GivenName sans validation, car nous partons du principe que les données de la base de données ont déjà été validées. Nous avons également la possibilité de ne pas faire confiance à la base de données et d’analyser le GivenName de manière classique au niveau de la couche de base de données.

Après avoir défini quelques autres newtypes de la même façon, nous pouvons définir Contact:

#[derive(Debug, PartialEq, sqlx::FromRow)]
pub struct Contact {
    pub id: ContactId,
    pub family_name: FamilyName,
    pub given_name: GivenName,
    pub phone: Option<Phone>,
    pub email: Email,
}

Quand l’utilisateur·ice est en train de créer un nouveau contact, celui-ci n’a pas encore d’identifiant. Nous définissons donc ContactContent à cet effet :

#[derive(Debug, PartialEq, Serialize)]
pub struct ContactContent {
    pub family_name: FamilyName,
    pub given_name: GivenName,
    pub phone: Option<Phone>,
    pub email: Email,
}

Que doit-il se passer quand l’utilisateur·ice envoie un formulaire pour créer un contact ?

Nous ne voulons pas qu’axum désérialise les données du formulaire et construise directement un ContactContent, car l’analyse s’arrêterait dès la première erreur. Nous souhaitons plutôt pouvoir collecter plusieurs erreurs de validation et les stte toutes à l’utilisateur·ice. Le formulaire comporte un élément <span class="error"> sous chaque champ de saisie pour afficher ces erreurs. Nous pouvons représenter les données du formulaire non analysées sous la forme d’une struct comme celle-ci :

use serde_with::{NoneAsEmptyString, serde_as};

#[serde_as]
#[derive(Debug, Default, Deserialize)]
pub struct ContactForm {
    pub family_name: String,
    pub given_name: String,

    #[serde_as(as = "NoneAsEmptyString")]
    pub phone: Option<String>,

    pub email: String,
}

Nous aimerions analyser un ContactForm et obtenir soit un ContactContent, soit une collection d’erreurs. Il n’existe pas encore de moyen d’automatiser complètement cette tâche, mais nous pouvons écrire une petite fonction pour l’accomplir en utilisant la bibliothèque frunk d’outils de programmation fonctionnelle. Nous allons utiliser son type Validated, qui regroupe les résultats de plusieurs opérations. S’il n’y a pas d’erreurs, Validated::into_result produit une HList, qui est une liste statiquement typée dont les éléments peuvent être de types différents. À partir d’une HList, nous pouvons facilement construire notre ContactContent. Si des erreurs se sont produites, nous les récupérons dans un Vec.

use frunk::prelude::*;
use frunk_core::hlist_pat;

impl ContactForm {
    pub fn parse(&self) -> Result<ContactContent, Vec<ParseError>> {
        let validated = FamilyName::try_new(&self.family_name)
            .map_err(ParseError::from)
            .into_validated()
            + GivenName::try_new(&self.given_name).map_err(ParseError::from)
            + self.phone.as_ref()
                .map(|phone| Phone::try_new(phone)
                    .map_err(ParseError::from))
                .transpose()
            + Email::try_new(&self.email).map_err(ParseError::from);

        validated
            .into_result()
            .map(
                |hlist_pat!(family_name, given_name, phone, email)|
                    ContactContent {
                        family_name,
                        given_name,
                        phone,
                        email,
                    },
            )
    }
}

Notre type ParseError contient l’erreur d’origine (GivenNameError, etc.), ce qui nous permet de déterminer facilement quels champs ont produit des erreurs. Nous pouvons ensuite transmettre au template le ContactForm et un ensemble de messages d’erreur traduits.

Si la validation a réussi, nous pouvons transmettre le ContactContent à la méthode Database::add, qui prend la forme suivante :

pub async fn add(&self, contact: &ContactContent) -> Result<(), Error> {
    let mut tx = self.pool.begin().await?;

    sqlx::query!(
        r#"INSERT INTO contact (family_name, given_name, phone, email)
            VALUES ($1, $2, $3, $4)"#,
        &contact.family_name,
        &contact.given_name,
        &contact.phone,
        &contact.email
    )
    .execute(&mut *tx)
    .await?;

    tx.commit().await?;
    Ok(())
}

Gestion des erreurs #

À qui la faute ? #

Notre stratégie de gestion des erreurs fait la distinction entre les erreurs imputables au client et celles imputables au serveur. Nous pouvons utiliser la crate thiserror pour simplifier l’imbrication des erreurs dans d’autres erreurs :

use thiserror::Error;

#[derive(Error, Debug)]
pub enum Error {
    #[error("Client error: {0}")]
    Client(#[from] ClientError),

    #[error("Server error: {0}")]
    Server(ServerError),
}

#[derive(Error, Debug)]
pub enum ClientError {
    #[error("Page not found")]
    NotFound,

    // ...
}

#[derive(Error, Debug)]
pub enum ServerError {
    #[error("Database error: {0}")]
    Database(#[from] DatabaseError),

    // ...
}

#[derive(Error, Debug)]
pub enum DatabaseError {
    #[error("{0}")]
    Sqlx(#[from] sqlx::Error),
}

impl<E> From<E> for Error
where
    E: Into<ServerError>,
{
    fn from(err: E) -> Self {
        Error::Server(err.into())
    }
}

Si l’erreur est imputable au client, nous allons simplement la signaler à l’utilisateur·ice, par exemple en affichant « Page introuvable ». Si l’erreur est imputable au serveur (par exemple, s’il s’agit d’une DatabaseError), nous afficherons « Erreur interne du serveur » et enregistrerons les détails de l’erreur dans le journal.

Centraliser la gestion des erreurs #

J’aime centraliser la gestion des erreurs pour qu’elle n’encombre pas le reste du code. Avec axum, une route renvoie un Result dont le type d’erreur est n’importe quel type implémentant le trait IntoResponse. Par conséquent, avec un peu d’infrastructure, nous pouvons utiliser l’opérateur ? dans nos routes pour enregistrer l’erreur dans le journal si nécessaire et renvoyer une page d’erreur à l’aide de notre template error.html. Nous créons un type d’erreur appelé ErrorResponse qui contient simplement un code d’état HTTP et du code HTML, puis nous implémentons IntoResponse pour celui-ci. Nous écrivons ensuite une méthode sur notre type Error qui produit une ErrorResponse, à l’aide du template, avec un message d’erreur traduit, et qui enregistre l’erreur dans le journal si elle est imputable au serveur. Cette méthode doit prendre un paramètre &Translation pour que le modèle puisse récupérer le message d’erreur dans la langue cible :

impl Error {
    pub fn to_error_response(self, t: &Translation) -> ErrorResponse {
        // ...
    }
}

Enfin, nous écrivons un trait d’extension pour Result, pour convertir n’importe quelle erreur en ErrorResponse :

pub trait ResultErrorTranslationExt<T, E>
where
    E: std::error::Error,
    Error: From<E>,
{
    fn tr_err(self, t: &Translation) -> Result<T, ErrorResponse>;
}

impl<T, E> ResultErrorTranslationExt<T, E> for Result<T, E>
where
    E: std::error::Error,
    Error: From<E>,
{
    fn tr_err(self, t: &Translation) -> Result<T, ErrorResponse> {
        self.map_err(|err| Error::from(err).to_error_response(t))
    }
}

Nous pouvons désormais créer des routes qui renvoient Result<Html<String>, ErrorResponse> et qui gèrent les erreurs de manière très concise. Par exemple, si la méthode Database::get peut renvoyer une DatabaseError, nous pouvons l’appeler de la façon suivante :

1
2

let t: &Translation = // ...
let contact = app.db.get(id).await.tr_err(t)?;

Les routes et les langues #

Avant de définir les points de terminaison HTTP, il convient de déterminer comment l’application saura quelle langue utiliser. L’en-tête de requête Accept-Language permet au navigateur de fournir une liste, classée par ordre de préférence, des langues choisies par l’utilisateur·ice, mais il faut aussi lui permettre de sélectionner une langue spécifiquement pour cette application :

Cet en-tête sert d’indication lorsque le serveur ne peut pas déterminer la langue du contenu cible autrement (par exemple, utiliser une URL spécifique qui dépend d’une décision explicite de l’utilisateur·ice). Le serveur ne doit jamais passer outre un choix explicite de langue de l’utilisateur·ice. Le contenu d’Accept-Language est souvent hors du contrôle de l’utilisateur·ice (par exemple lors d’un voyage). Un·e utilisateur·ice peut aussi vouloir visiter une page dans une langue différente de celle de l’interface utilisateur.

Ajoutons donc un sélecteur de langue dans l’en-tête de la page et insérons une étiquette de langue BCP 47 au début du chemin d’accès de chaque point de terminaison. Pour le chemin d’accès racine, nous pouvons utiliser l’en-tête Accept-Language et rediriger vers un chemin d’accès contenant une étiquette de langue.

Avec la crate karatepe, l’application charge une Translation pour chaque langue au démarrage. Nous les conservons dans un HashMap (avec icu::locale::LanguageIdentifier comme type de clé) dans l’état partagé de l’application, ainsi que la Database. Voici notre struct AppState :

pub struct AppState {
    pub db: Database,
    pub translations: Arc<HashMap<LanguageIdentifier, Translation>>,
}

Le Router d’axum peut conserver cette struct pour que routes puissent y accéder. Nous le configurons ainsi :

pub fn init_router(app: AppState) -> Router {
    Router::new()
        .route("/", get(index)) // checks Accept-Language
        .route(
            "/{lang}/contacts",
            get(contacts::contacts_get).delete(contacts::contacts_delete),
        )
        .route(
            "/{lang}/contacts/{id}",
            get(contacts::contact_get).delete(contacts::contact_delete),
        )
        // ...
        .with_state(app)
}

Axum fournit des extracteurs que les routes peuvent utiliser pour extraire et analyser les données contenues dans la requête. Nous utilisons l’extracteur Path pour analyser l’étiquette de langue et construire un LanguageIdentifier (qui implémente serde::Deserialize), ce qui nous évite de créer notre propre newtype à cet effet. Il suffit ensuite de créer une petite fonction appelée translation qui prend un LanguageIdentifier en paramètre et renvoie la Translation correspondante issue de l’AppState.

Évitons de créer un de ces sites web agaçants dont le sélecteur de langue vous renvoie à la page d’accueil. Écrivons plutôt une fonction, uris_with_langs, qui prend le chemin d’accès de l’URL actuel, l’adapte à chaque langue disponible et renvoie la liste des chemins obtenus. Dans l’en-tête de la page, nous afficherons ces URL sous forme de liens.

Le template qui affiche un contact s’appelle show.html, et ses variables sont définies dans struct ShowContactTemplate. Notre route contact_get est donc à peu près ceci :

pub async fn contact_get(
    State(app): State<AppState>,
    Path((lang, id)): Path<(LanguageIdentifier, ContactId)>,
    uri: Uri,
) -> Result<Html<String>, ErrorResponse> {
    let t = app.translation(&lang);
    let contact = app.db.get(id).await.tr_err(t)?;

    let template = ShowContactTemplate {
        t,
        lang,
        lang_uris: localisation::uris_with_langs(uri).tr_err(t)?,
        contact,
    };

    Ok(Html(template.render().tr_err(t)?))
}

Pagination #

(Si vous avez déjà lu la version Go de cet article, vous pouvez sauter cette section et celle d’après.)

La pagination dans Hypermedia Systems est basée sur des numéros de page, ce qui est inefficace (la base de données doit toujours récupérer toutes les pages précédant celle que vous avez demandée) et peut produire des résultats inattendus si les données sont modifiées pendant que vous parcourez les pages. Une meilleure méthode consiste à utiliser la pagination par curseurs. Lors du renvoi d’une page de résultats, la couche de base de données renvoie éventuellement deux curseurs, appelés prev et next, que la vue peut présenter sous forme de liens vers la page précédente et la page suivante. Le lien « Page précédente » contient le curseur prev comme paramètre before, et le lien « Page suivante » contient le curseur next comme paramètre after. Quelques astuces sont nécessaires pour que cela fonctionne.

Notre curseur contiendra les valeurs des colonnes family_name, given_name et email, que nous utilisons déjà pour trier les contacts. Comme il y a déjà un index sur ces trois colonnes, dans cet ordre, la base de données peut récupérer efficacement une page de lignes situées avant ou après le curseur.

Nous voulons éviter de renvoyer un curseur prev si nous avons atteint la première page, ou un curseur next si nous avons atteint la dernière. La solution est la suivante : dans une requête « page suivante », si la taille maximale d’une page est N, nous demandons N + 1 lignes. Si nous les obtenons, nous savons qu’une page suivante existe. Nous renvoyons donc un curseur next basé sur la dernière ligne de la page renvoyée. Si un curseur after nous a été transmis dans la requête, nous pouvons supposer qu’il y a une page précédente. Le curseur prev correspondra donc à la première ligne de la page renvoyée.

Nos requêtes SQL permettant d’obtenir une page de contacts doivent tenir compte du fait que les noms ne sont pas forcément uniques. Voici donc notre requête « page suivante » (avec une expression de table commune pour ne pas avoir à transmettre les mêmes paramètres plusieurs fois) :

WITH vars AS (SELECT ? AS family_name, ? AS given_name, ? AS email)
SELECT id, family_name, given_name, phone, email
FROM contact
WHERE (family_name = (SELECT family_name FROM vars)
       AND given_name = (SELECT given_name FROM vars)
       AND email > (SELECT email FROM vars))
OR (family_name = (SELECT family_name FROM vars)
    AND given_name > (SELECT given_name FROM vars))
OR family_name > (SELECT family_name FROM vars)
ORDER BY family_name, given_name, email
LIMIT ?;

Pour les requêtes « page précédente », le principe est le même, mais dans l’ordre inverse.

Traitement des requêtes de recherche en texte intégral #

Il ne reste plus grand-chose à faire pour la recherche en texte intégral. Le point de terminaison /{lang}/contacts reçoit une requête composée d’un ou plusieurs mots ou préfixes de mots. Au niveau de la couche de base de données, nous analysons cette requête pour l’adapter à la syntaxe du module FTS5. Par exemple, G O'Mal devient "G"* + "O'Mal"* et permettra de trouver un contact qui s’appelle Grace O’Malley. Comme nous renvoyons au maximum une page de résultats de recherche en texte intégral, la route transmet des curseurs None au template, qui supprime les liens de pagination au moyen d’un remplacement hors bande réalisé par htmx.

Tests d’intégration #

Les tests unitaires de cette application n’ont rien de remarquable (à moins que vous ne vous appeliez 曼玉-فاتن), mais les tests d’intégration sont plus intéressants. J’en ai écrit deux groupes : l’une pour la couche de base de données, et l’autre pour les points de terminaison HTTP. Dans les deux cas, nous utilisons sqlx::test, qui crée une nouvelle base de données pour chaque test et l’initialise avec une fixture, de sorte que les tests soient isolés les uns des autres. Comme mentionné plus haut, les tests des points de terminaison HTTP analysent les réponses HTML et vérifient le contenu de certains éléments. Nous utilisons le même Router que dans l’application, et analysons les réponses à l’aide de dom_query. Par exemple, pour tester une requête GET vers /{lang}/contacts/{id}/edit, le point de terminaison permettant de modifier un contact existant, nous pouvons procéder ainsi :

#[sqlx::test(fixtures("test-contacts"))]
async fn edit_contact_get(pool: SqlitePool) {
    let server = init_server(pool).await;
    let response = server.get("/en/contacts/1/edit").await;

    assert_eq!(response.status_code(), StatusCode::OK);
    let doc = Document::from(response.text());

    let email_label = doc.select("label[for='email']").text().to_string();
    assert_eq!(email_label, "Email");

    let email = doc.select("#email").attr("value").unwrap().to_string();
    assert_eq!(email, "foo1@bar.com");

    // ...
}

Comme nous examinons uniquement le texte de libellés et de champs de formulaire à l’aide de sélecteurs CSS simples, ce genre de test a peu de chances d’être affecté par des modifications apportées à la mise en page.

PostgreSQL #

Nous n’avons pas à modifier grand-chose pour que notre application utilise PostgreSQL à la place de SQLite.

Recherche en texte intégral #

(Si vous avez déjà lu la version Go de cet article, vous pouvez sauter cette section.)

Tout comme SQLite, Postgres intègre une fonctionnalité de recherche en texte intégral, et celle-ci est encore plus simple à configurer. Nous pouvons stocker les noms des contacts, transformés en valeurs tsvector, dans une colonne générée de la table contact, avec un index GIN pour accélérer les requêtes :

CREATE TABLE IF NOT EXISTS contact (
  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  family_name TEXT NOT NULL,
  given_name TEXT NOT NULL,
  phone TEXT,
  email TEXT UNIQUE NOT NULL,
  textsearch tsvector GENERATED ALWAYS AS (
    to_tsvector(
      'simple',
      COALESCE(family_name, '') || ' ' || COALESCE(given_name, '')
    )
  ) STORED
);

CREATE INDEX textsearch_idx ON contact USING GIN (textsearch);

La requête SQL qui trouve les lignes correspondantes utilise l’opérateur de recherche en texte intégral, @@ :

SELECT id, family_name, given_name, phone, email
FROM contact, to_tsquery($1) query
WHERE query @@ textsearch
ORDER BY ts_rank_cd(textsearch, query)
LIMIT $2;

La syntaxe de la chaîne à transmettre à to_tsquery ne nécessite que quelques ajustements pour fonctionner avec Postgres : si l’utilisateur·ice saisit G O'Mal, nous transmettons l’argument 'G':* & 'O''Mal':*.

Tests d’intégration avec Testcontainers #

Nous pouvons utiliser Testcontainers et faire tourner Postgres dans un conteneur Docker éphémère. La macro #[sqlx:test] exécute les tests en parallèle et les isole les uns des autres en créant une nouvelle base de données dans le même conteneur pour chaque test.

Il y a ici un petit problème à résoudre : #[sqlx:test] génère du code qui lit l’URL de la base de données de test à partir d’une variable d’environnement ou d’un fichier .env, mais nous ne connaissons cette URL qu’une fois que Testcontainers a démarré le conteneur Docker. La solution, basée sur un exemple créé par Matilda Smeds, consiste à utiliser la crate linktime pour définir une fonction d’initialisation de module qui s’exécute avant les tests. Cette fonction lance le conteneur de test et définit la variable d’environnement DATABASE_URL via std::env::set_var.

Conclusion #

En suivant le principe « Analyser au lieu de valider » et en utilisant des outils de génération de code déterministes qui tirent parti des garanties offertes par le système de types de Rust, nous avons réduit au minimum le code répétitif et amélioré les chances que, si nous faisons une erreur, celle-ci soit détectée lors de la compilation plutôt qu’au moment de l’exécution. Cela devrait contribuer à faciliter la maintenance de notre code et à prévenir les bugs.

See the N+1 selects problem and selecting all columns without thinking about it. ↩︎

Créer une application hypermédia en Go

Mon, 05 Oct 2026 07:01:00 +0000

Ceci est le deuxième article d’une série :

Créer des applications hypermédia sécurisées pour un monde aux ressources limitées, qui présente la série
l’article présent
Créer une application hypermédia en Rust

Aperçu de l’application #

L’application qui sert d’exemple dans Hypermedia Systems est une application CRUD qui gère une liste de contacts. Le livre montrer comment créer une application hypermédia qui offre une bonne interface utilisateur, en alternative aux applications monopages. Grâce à une minuscule bibliothèque JavaScript (htmx) et à quelques attributs déclaratifs sur les éléments HTML, toutes sortes d’interactions utilisateur peuvent récupérer des fragments de code HTML depuis le serveur et ne modifier que certaines parties de la page. Par exemple, quand on passe d’une page à une autre dans la liste des contacts ou qu’on supprime un contact, la liste affichée s’actualise sans que la page ne soit rechargée.

Réalisons cette application en Go, avec deux objectifs :

La rendre plus réaliste en ajoutant une interface utilisateur internationalisée, une base de données relationnelle avec un index de recherche en texte intégral, une meilleure validation des entrées, une pagination par curseur et des tests d’interface utilisateur.
La rendre facile à maintenir, en limitant au maximum le code répétitif et en tirant parti des vérifications effectuées lors de la compilation pour éviter les bugs.

Nous utiliserons dans un premier temps une base de données SQLite, puis passerons à PostgreSQL dans une étape ultérieure. Le code source des deux versions est disponible ici :

Bibliothèques #

Notre première tâche est de choisir quelques bibliothèques.

Templates HTML #

Il nous faudra donc un moteur de template. Dans la bibliothèque standard de Go il y a html/template, mais ce package ne propose pas de templates à typage sûr. Les moteurs de template à typage sûr se déclinent essentiellement en deux catégories : celle qui permet d’écrire quasiment du code HTML standard, et celle qui permet d’exprimer la structure d’un document HTML dans un langage de programmation. Je préfère la première catégorie, car plus la syntaxe des templates se rapproche du HTML, plus il sera facile pour un concepteur UX, ou toute personne maîtrisant HTML, de travailler sur ces templates sans avoir à connaître Go.

J’ai choisi templ, qui est facile à utiliser, compile les templates en Go et est bien pris en charge par les environnements de développement. Pour l’utiliser, on écrit des templates sous forme de fonctions dont le corps est en HTML, puis on exécute templ generate pour les compiler en fonctions Go. Nous pouvons appeler ces fonctions depuis les implémentations de nos points de terminaison HTTP.

Internationalisation #

Tout d’abord, cela signifie que toute modification apportée à la chaîne source invalide toutes les traductions de cette chaîne. Cela alourdit considérablement la charge de travail des développeur·euses, qui doivent veiller à ne jamais modifier les messages dans la langue source, car cela entraînerait la nécessité de mettre à jour toutes les traductions.

D’autre part, cela complique l’utilisation de plusieurs messages qui ont la même chaîne source mais qui devraient être traduits différemment.

Je préfère donc les bibliothèques qui utilisent des identifiants de message uniques choisis par les développeur·euses.

J’avais envie d’essayer Project Fluent, mais il semblerait que ce projet ait été abandonné. J’ai donc opté pour go-18n, qui offre les fonctionnalités dont on a besoin. Pour éviter l’encombrement du code, j’ai écrit une fonction comme celle-ci pour chaque message, en fournissant le texte en anglais, qui est la langue par défaut :

func InfoContactCount(loc *i18n.Localizer, count int) string {
  return loc.MustLocalize(&i18n.LocalizeConfig{
    DefaultMessage: &i18n.Message{
      ID:    "InfoContactCount",
      One:   "({{.Count}} total contact)",
      Other: "({{.Count}} total contacts)",
    },
    TemplateData: map[string]any{
      "Count": count,
    },
    PluralCount: count,
  })
}

Nous pouvons appeler cette fonction directement depuis un template. Le programme en ligne de commande goi18n extrait les messages de notre code source pour les enregistrer dans des fichiers texte, où nous pouvons ensuite les traduire. Au moment de l’exécution, nous pouvons accéder à la traduction d’un message via la Localizer correspondant à la langue cible. Nous verrons ci-dessous comment obtenir celui qui convient.

Accès à la base de données et migration de schéma #

La bibliothèque standard de Go fournit le package database/sql, mais celui-ci vous oblige à réaliser vous-même les conversions entre les résultats des requêtes et les structs Go. La maintenance de ces conversions est fastidieuse, et il est facile de faire des erreurs qui ne seront pas détectées lors de la compilation. Nous pourrions utiliser un mapping object-relationnel (ORM), mais à mon avis il vaut mieux écrire notre code SQL nous-mêmes. Les ORM peuvent générer des requêtes inefficaces.¹ Écrire notre propre code SQL nous permet de tirer pleinement parti des fonctionnalités du SQL moderne et de ses possibilités d’optimisation des requêtes, notamment en concevant conjointement les requêtes et les index, et en affinant les requêtes en tenant compte des plans d’exécution choisis par l’optimiseur de requêtes de la base de données. (Voir mon article Optimiser des requêtes PostgreSQL avec un jeu de données ouvert pour un exemple.)

À mon avis, l’idéal est d’avoir une bibliothèque qui implémente la sûreté du typage pour les requêtes SQL, de sorte que celles-ci soient vérifiées lors de la compilation et renvoient automatiquement des structs Go. C’est exactement ce que fait le package sqlc (voir son article de blog de présentation pour une explication plus détaillée). Pour utiliser sqlc, on écrit les requêtes SQL dans des fichiers texte. Quand on exécute sqlc generate en ligne de commande, l’outil se connecte à la base de données pour analyser les requêtes, puis génère un package Go, dans lequel il y a une fonction à typage sûr correspondant à chaque requête.

Par exemple, imaginons que nous ayons mal orthographié le nom d’une colonne (familyname au lieu de family_name) dans une requête :

`1`	`SELECT id, familyname, given_name, phone, email FROM contact WHERE id = ?;`

Nous obtiendrons une erreur lors de l’exécution de sqlc generate:

`1`	`sql/queries.sql:1:1: sqlite3: SQL logic error: no such column: familyname`

Nous allons aussi faire en sorte que sqlc utilise des instructions préparées pour prévenir les attaques par injection SQL.

Comme les schémas des bases de données évoluent, il nous faut aussi un outil qui gère les migrations de schéma. Parmi plusieurs bonnes options j’ai choisi goose.

Framework de serveur HTTP #

La bibliothèque standard de Go propose le module net/http pour créer des serveurs HTTP, mais j’ai choisi le framework Gin, qui implémente des conversions à typage sûr entre les requêtes et les structs Go, ainsi qu’une validation flexible des entrées au moyen du package validator. Et il est facile d’intégrer templ dans Gin.

Tests d’interface utilisateur #

S’il s’agissait de créer une application monopage, notre serveur aurait une API JSON, et nous pourrions écrire des tests vérifiant qu’il renvoie les données correctes pour différentes requêtes. Mais notre application renvoie du code HTML. Nous allons donc écrire des tests analogues aux tests d’API JSON, en nous concentrant sur les fonctionnalités pratiques des réponses HTML. À l’aide du package goquery, nous analyserons ces réponses et utiliserons des sélecteurs CSS pour vérifier le contenu de certains éléments. Nous aurons ainsi la liberté de modifier considérablement la conception graphique des pages sans avoir à changer nos tests.

Conception de la base de données #

(Si vous avez déjà lu la version Rust de cet article, vous pouvez sauter cette section.)

Notre base de données est très simple. Il y a une seule table, contact :

CREATE TABLE IF NOT EXISTS contact (
  id INTEGER PRIMARY KEY,
  family_name TEXT NOT NULL,
  given_name TEXT NOT NULL,
  phone TEXT,
  email TEXT UNIQUE NOT NULL
) STRICT;

Il y a toutefois quelques détails à prendre en compte.

Quand l’application affiche la liste des contacts, celle-ci devrait être triée selon un certain ordre. Nous utiliserons ORDER BY family_name, given_name, email. Pour optimiser les performances, nous ajoutons un index correspondant à cet ordre de tri :

1
2

CREATE INDEX IF NOT EXISTS idx_contact_sort
ON contact (family_name, given_name, email);

Comme l’application exige que les adresses e-mail soient uniques, j’ai mis une contrainte UNIQUE sur le champ email, et nous aurons besoin de faire une requête comme celle-ci :

`1`	`SELECT 1 FROM contact WHERE email = ?;`

Pour que cette requête soit efficace, nous créons un index sur la colonne email :

`1`	`CREATE INDEX IF NOT EXISTS idx_contact_email ON contact (email);`

CREATE VIRTUAL TABLE IF NOT EXISTS contact_fts USING fts5(
    family_name,
    given_name,
    phone UNINDEXED,
    email UNINDEXED,
    content = 'contact',
    content_rowid = 'id'
);

Nous utiliserons des déclencheurs pour que la table contact_fts reste synchronisée avec la table contact. Et voilà qui conclut notre schéma de base de données.

Architecture logicielle #

type Contact struct {
  ID         int64
  FamilyName string
  GivenName  string
  Phone      string
  Email      string
}

La couche d’abstraction de base de données est tout simplement une struct qui contient le pool de connexions et dispose de méthodes comme celle-ci :

func (db *Database) Get(
  ctx context.Context,
  id int64,
) (*model.Contact, error) {
  // ...
}

Validation des entrées #

Que doit-il se passer quand l’utilisateur·ice envoie un formulaire pour créer un contact ? L’application doit valider tous les champs, en ayant la possibilité de collecter plusieurs erreurs de validation et de les signaler toutes à l’utilisateur·ice. Le formulaire comporte un élément <span class="error"> sous chaque champ de saisie pour afficher ces erreurs. Gin nous permet d’associer les champs du formulaire aux champs d’une struct, de désigner des fonctions de validation pour chaque champ et de récupérer une liste d’erreurs de validation. Étant donné qu’un contact qui n’a pas encore été enregistré n’a pas d’identifiant, créons une autre struct à cet effet :

type ContactContent struct {
  FamilyName string `form:"family_name" binding:"required,name"`
  GivenName  string `form:"given_name" binding:"required,name"`
  Phone      string `form:"phone" binding:"omitempty,phone"`
  Email      string `form:"email" binding:"required,email"`
}

La balise form indique le champ du formulaire à associer à un champ donné de la struct, et binding indique les fonctions de validation à exécuter pour le champ. Nous pouvons utiliser les fonctions proposées par le package validator ainsi que les nôtres. Ici, j’ai créé des fonctions appelées name, phone et email, qui utilisent des expressions régulières Unicode. Comme il s’agit d’une application internationalisée, nous aimerions prendre en charge :

tous les caractères Unicode qui pourrait figurer dans le nom d’une personne
n’importe quel numéro de téléphone utilisable dans n’importe quel pays
l’internationalisation des adresses de courrier électronique

Par exemple, ma modeste tentative d’expression régulière pour les noms accepte des groupes de lettres et de caractères Unicode, séparés par des espaces et/ou des signes de ponctuation :

`1`	`^[\p{L}\p{M}]+(?:(?:\p{P}\p{Zs}\|[\p{P}\p{Zs}])[\p{L}\p{M}]+)*\p{P}?$`

Donc, si vous vous appelez 曼玉-فاتن, tout va bien. Nous écrivons une fonction de validation qui utilise cette expression régulière :

var nameValidator validator.Func = func(fl validator.FieldLevel) bool {
  field := fl.Field().String()
  return len(field) <= 50 && NameRegex.MatchString(field)
}

Au démarrage de l’application, nous enregistrons la fonction auprès du package validator :

1
2
3

if validate, ok := binding.Validator.Engine().(*validator.Validate); ok {
  validate.RegisterValidation("name", nameValidator)
}

Gestion des erreurs #

Notre stratégie de gestion des erreurs fait la distinction entre les erreurs imputables au client et celles imputables au serveur :

type ClientError struct {
  Cause error
}

// ...

type NotFoundError struct{}

type ServerError struct {
  Cause error
}

type DatabaseError struct {
  Cause error
}

// ...

Les routes et les langues #

Cet en-tête sert d’indication lorsque le serveur ne peut pas déterminer la langue du contenu cible autrement (par exemple, utiliser une URL spécifique qui dépend d’une décision explicite de l’utilisateur·ice). Le serveur ne doit jamais passer outre un choix explicite de langue de l’utilisateur·ice. Le contenu d’Accept-Language est souvent hors du contrôle de l’utilisateur·ice (par exemple lors d’un voyage). Un·e utilisateur·ice peut aussi vouloir visiter une page dans une langue différente de celle de l’interface utilisateur.

Avec le package go-i18n, l’application initialise un i18n.Bundle au démarrage. Celui-ci contient les identifiants de messages et les traductions, et fera partie de l’état partagé de l’application, comme la Database. Voici notre structure AppState :

type AppState struct {
  Database   *db.Database
  I18NBundle *i18n.Bundle
}

Si nous implémentons les routes sous forme de méthodes dont le récepteur est *AppState, nous pouvons configurer un routeur Gin de la façon suivante :

engine := gin.Default()
engine.GET("/", app.index) // utilise Accept-Language
engine.GET("/:lang/contacts", app.contactsGet)
engine.GET("/:lang/contacts/:id", app.contactGet)
// ...

Gin peut également valider le paramètre :lang et l’associer à un champ de struct. J’ai écrit une petite fonction appelée GetLocalizer, qui renvoie le Localizer correspondant à la langue indiquée dans le chemin d’accès, le cas échéant, et qui, à défaut, utilise l’en-tête Accept-Language.

Évitons de créer un de ces sites web agaçants dont le sélecteur de langue vous renvoie à la page d’accueil. Écrivons plutôt une fonction, URLsWithLangs, qui prend le chemin d’accès de l’URL actuel, l’adapte à chaque langue disponible et renvoie la liste des chemins obtenus. Dans l’en-tête de la page, nous afficherons ces URL sous forme de liens.

Maintenant, si nous créons un template appelé Show qui prend un Contact en paramètre, notre route contactGet sera à peu près ceci :

type LanguagePathParams struct {
  Lang string `uri:"lang" binding:"required,bcp47_strict_language_tag"`
}

type IDPathParams struct {
  ID int64 `uri:"id" binding:"required"`
}

type ContactPathParams struct {
  LanguagePathParams
  IDPathParams
}

func (state *AppState) contactGet(ctx *gin.Context) {
  var pathParams ContactPathParams

  if err := ctx.ShouldBindUri(&pathParams); err != nil {
    state.notFound(ctx)
    return
  }

  loc := localisation.GetLocalizer(state.I18NBundle, pathParams.Lang, ctx)

  contact, err := state.Database.Get(ctx, pathParams.ID)
  if err != nil {
    errorPage(ctx, pathParams.Lang, loc, err)
    return
  }

  urlsWithLangs, err := localisation.URLsWithLangs(ctx.Request.URL)
  if err != nil {
    errorPage(ctx, pathParams.Lang, loc, err)
    return
  }

  ctx.HTML(http.StatusOK, "",
    templates.Show(
      pathParams.Lang,
      loc,
      contact,
      urlsWithLangs,
    ),
  )
}

Pagination #

(Si vous avez déjà lu la version Rust de cet article, vous pouvez sauter cette section et celle d’après.)

Nos requêtes SQL permettant d’obtenir une page de contacts doivent tenir compte du fait que les noms ne sont pas forcément uniques. Voici donc notre requête « page suivante » : (avec une expression de table commune pour ne pas avoir à transmettre les mêmes paramètres plusieurs fois) :

WITH vars AS (SELECT ? AS family_name, ? AS given_name, ? AS email)
SELECT id, family_name, given_name, phone, email
FROM contact
WHERE (family_name = (SELECT family_name FROM vars)
       AND given_name = (SELECT given_name FROM vars)
       AND email > (SELECT email FROM vars))
OR (family_name = (SELECT family_name FROM vars)
    AND given_name > (SELECT given_name FROM vars))
OR family_name > (SELECT family_name FROM vars)
ORDER BY family_name, given_name, email
LIMIT ?;

Pour les requêtes « page précédente », le principe est le même, mais dans l’ordre inverse.

Traitement des requêtes de recherche en texte intégral #

Il ne reste plus grand-chose à faire pour la recherche en texte intégral. Le point de terminaison /:lang/contacts reçoit une requête composée d’un ou plusieurs mots ou préfixes de mots. Au niveau de la couche de base de données, nous analysons cette requête pour l’adapter à la syntaxe du module FTS5. Par exemple, G O'Mal devient "G"* + "O'Mal"* et permettra de trouver un contact qui s’appelle Grace O’Malley. Comme nous renvoyons au maximum une page de résultats de recherche en texte intégral, la route transmet des curseurs nil au template, qui supprime les liens de pagination au moyen d’un remplacement hors bande réalisé par htmx.

Tests d’intégration #

Les tests unitaires de cette application n’ont rien de remarquable (à moins que vous ne vous appeliez 曼玉-فاتن), mais les tests d’intégration sont plus intéressants. J’en ai écrit deux groupes : l’une pour la couche de base de données, et l’autre pour les points de terminaison HTTP. Dans les deux cas, chaque test s’exécute avec une base de données SQLite fraîchement initialisée avec une fixture. Comme mentionné plus haut, les tests des points de terminaison HTTP analysent les réponses HTML et vérifient le contenu de certains éléments. Nous utilisons un routeur Gin en mode test, et net/http/httptest enregistre les réponses, que nous pouvons analyser à l’aide de goquery. Par exemple, pour tester une requête GET vers /:lang/contacts/:id/edit, le point de terminaison permettant de modifier un contact existant, nous pouvons procéder ainsi :

func TestEditContactGet(t *testing.T) {
  server := InitServer(t, "test-contacts")

  recorder := httptest.NewRecorder()
  request, _ := http.NewRequest("GET", "/en/contacts/1/edit", nil)
  server.ServeHTTP(recorder, request)

  test.Equals(t, recorder.Code, http.StatusOK)
  doc, err := goquery.NewDocumentFromReader(recorder.Result().Body)
  if err != nil {
    t.Fatalf("Failed to parse HTTP response: %v", err)
  }

  familyNameLabel := doc.Find("label[for='family_name']").Text()
  test.Equals(t, familyNameLabel, "Family name")

  familyName, _ := doc.Find("#family_name").Attr("value")
  test.Equals(t, familyName, "Aaa")

  // ...
}

PostgreSQL #

Nous n’avons pas à modifier grand-chose pour que notre application utilise PostgreSQL à la place de SQLite.

Recherche en texte intégral #

(Si vous avez déjà lu la version Rust de cet article, vous pouvez sauter cette section.)

CREATE TABLE IF NOT EXISTS contact (
  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  family_name TEXT NOT NULL,
  given_name TEXT NOT NULL,
  phone TEXT,
  email TEXT UNIQUE NOT NULL,
  textsearch tsvector GENERATED ALWAYS AS (
    to_tsvector(
      'simple',
      COALESCE(family_name, '') || ' ' || COALESCE(given_name, '')
    )
  ) STORED
);

CREATE INDEX textsearch_idx ON contact USING GIN (textsearch);

La requête SQL qui trouve les lignes correspondantes utilise l’opérateur de recherche en texte intégral, @@ :

SELECT id, family_name, given_name, phone, email
FROM contact, to_tsquery($1) query
WHERE query @@ textsearch
ORDER BY ts_rank_cd(textsearch, query)
LIMIT $2;

Tests d’intégration avec Testcontainers #

L’exécution de nos tests d’intégration avec Postgres demande un peu plus de travail. Pour exécuter chaque test avec une base de données fraîchement initialisée, comme précédemment, nous pouvons utiliser Testcontainers et faire tourner Postgres dans un conteneur Docker éphémère. Nous exécuterons les tests d’intégration de manière synchrone, et il suffit donc de créer une seule base de données. Le module postgres de Testcontainers propose une fonctionnalité très utile à cet effet : nous pouvons initialiser la base de données avec nos migrations et notre fixture, puis enregistrer un instantané de la base de données. Une fois que chaque test est terminé, nous restaurons la base de données à partir de cet instantané, pour qu’elle soit prête pour le test suivant.

Conclusion #

En utilisant un système de validation déclaratif et des outils de génération déterministe de code dans un langage à typage statique, nous avons réduit au minimum le code répétitif et amélioré les chances que, si nous faisons une erreur, celle-ci soit détectée lors de la compilation plutôt qu’au moment de l’exécution. Cela devrait contribuer à faciliter la maintenance de notre code et à prévenir les bugs.

Passons maintenant à l’écriture de la même application en Rust.

Voir the N+1 selects problem et selecting all columns without thinking about it. ↩︎

Créer des applications hypermédia sécurisées pour un monde aux ressources limitées

Mon, 05 Oct 2026 07:00:00 +0000

Quand je développais des applications web dans les années 1990, il était courant que le server génère des pages HTML à partir de templates, et beaucoup de moteurs de template ont été créés pour cela (y compris par moi). À partir du début des années 2000, les applications web monopages se sont répandues. Dans celles-ci, le serveur renvoie surtout des données au format JSON, alors qu’un framework JavaScript (ou TypeScript) génère le code HTML dans le navigateur. J’ai travaillé sur des applications de ce type et j’ai constaté qu’elles sont difficiles à maintenir, en partie parce que les frameworks JavaScript sont gigantesques et complexes et évoluent rapidement.

On constate aujourd’hui un mécontentement croissant vis-à-vis des applications monopages, non seulement à cause des difficultés de maintenance, mais aussi parce que ces applications doivent charger plusieurs mégaoctets de JavaScript via le réseau avant de pouvoir fonctionner, ce qui les rend lentes, surtout quand la connexion réseau est lente. En même temps, HTML est devenu plus puissant, ce qui rend JavaScript moins indispensable. Par conséquent, il y a un regain d’intérêt pour la génération de code HTML côté serveur.

Un des inconvénients de la génération de code HTML côté serveur dans les années 1990 était la nécessité de recharger la page entière dès qu’un élément changeait. Aujourd’hui cette limitation n’existe plus, grâce à des bibliothèques JavaScript minuscules comme htmx. En ajoutant des attributs déclaratifs aux éléments HTML, on peut permettre à toutes sortes d’interactions utilisateur de récupérer des fragments de code HTML depuis le serveur et de ne remplacer que les parties de la page qui doivent être modifiées. Les applications qui fonctionnent de cette façon sont des « applications hypermédia », et il y a un livre là-dessus qui s’appelle Hypermedia Systems.

Le livre explique la construction d’une application de gestion de contacts à l’aide de htmx, et le code source est fourni en Python. L’ouvrage étant axé sur htmx, le code serveur est très simple : il ne prend en charge que l’anglais, les contacts sont stockés dans un fichier plutôt que dans une base de données, la validation des entrées est très limitée, la pagination est basée sur des numéros de page et il n’y a pas de tests.

Dans un monde aux ressources limitées, il est logique de développer ce type d’applications dans des langages qui se compilent en code machine et utilisent relativement peu de mémoire.¹ Nous aimerions avoir la possibilité d’utiliser une base de données très légère comme SQLite ou d’en choisir une plus puissante comme PostgreSQL. Pour éviter les bugs et les failles de sécurité, nous pouvons privilégier les langages à typage statique qui mettent l’accent sur les fonctionnalités de sécurité intégrées. Et nous aimerions que notre application soit facile à maintenir.

Compte tenu de ces préférences, rendons l’application de Hypermedia Systems plus réaliste. Nous allons y ajouter une interface utilisateur internationalisée, une base de données relationnelle avec un index de recherche en texte intégral, une meilleure validation des entrées, une pagination par curseur et des tests d’interface utilisateur. Dans les prochains articles, je présenterai deux implémentations, l’une en Go et l’autre en Rust, utilisant soit SQLite, soit PostgreSQL. J’expliquerai les choix de conception que j’ai faits dans chaque version et j’aborderai des techniques intéressantes qui ont des applications plus larges. N’étant pas concepteur UX, je ne chercherai pas à améliorer l’interface utilisateur décrite dans le livre, mais j’aurai quelques mots à dire sur ce qui peut faciliter le travail des concepteurs UX. Je ne couvrirai pas la plupart des détails expliqués dans Hypermedia Applications, mais vous pouvez lire ces articles sans avoir lu le livre. Réfléchissons donc à des techniques que nous pouvons utiliser pour développer des applications web sécurisées, économes en ressources et faciles à maintenir :

(Ces deux articles peuvent être lus indépendamment l’un de l’autre.)

La relation entre l’efficacité énergétique et le choix du langage de programmation constitue un domaine de recherche très actif. Voir Energy Efficiency of Programming Languages. ↩︎

Optimiser des requêtes PostgreSQL avec un jeu de données ouvert

Tue, 10 Mar 2026 13:49:30 +0100

Aperçu #

Ce billet illustre brièvement quelques techniques d’optimisation des bases de données, en utilisant la BRÉF (Base Révisée des Élu·es de France), qui contient des données sur les représentant·es élu·es en France de 1948 à 2020. La BRÉF est basée sur des données publiques, dans lesquelles une équipe de chercheurs a corrigé beaucoup d’erreurs et d’incohérences. Elle est publiée sous la forme d’une base de données PostgreSQL qui comprend plusieurs tables et offre beaucoup de possibilités de jointures et d’optimisations.

J’utiliserai ici cette base de données pour développer et optimiser une requête SQL comprenant plusieurs jointures, pour obtenir des informations sur les maires et les communes où elles et ils ont été élu·es. Je construirai la requête à partir d’éléments plus simples, que j’optimiserai au fur et à mesure. Dans le cadre de cet exercice, je pars du principe que nous ne pouvons pas modifier le schéma de la base de données et que nous sommes prêts à payer un certain coût, en espace de stockage et en termes de performances de mise à jour, pour améliorer les performances des requêtes (d’autant plus que la base de données n’est pas très grande et que les mises à jour sont rares). Je me concentrerai donc sur ce que nous pouvons faire en créant des index. Pour identifier et tester des optimisations possibles, nous aurons deux sources d’information :

Les plans d’exécution de PostgreSQL, que nous pouvons obtenir en utilisant la commande EXPLAIN.
Des tests de performance exécutés par mon outil sqlstopwatch, qui exécute des requêtes à maintes reprises et indique le temps de réponse moyen de chaque requête.

Optimiser une requête simple #

Dans la terminologie du BRÉF,

le mandat correspond à la position élective (député, sénateur, etc.) tandis que le terme fonction recouvre une fonction exécutive dans le cadre d’un mandat. Ainsi, une personne peut être élue à la position de conseiller·e municipal·e, puis à celle de maire au sein de ce conseil municipal.

Il y a donc des tables qui s’appellent Mandate et Function et nous commencerons par celles-ci.

Trouvons d’abord toutes les fonctions de type MAIRE. Nous utiliserons EXPLAIN ANALYZE pour que Postgres exécute la requête, puis affiche le plan d’exécution (EXPLAIN) en indiquant le temps nécessaire à son exécution (ANALYZE).

EXPLAIN ANALYZE
SELECT "MandateId"
FROM "Function"
WHERE "FunctionType" = 'MAIRE'

QUERY PLAN
Seq Scan on "Function"  (cost=0.00..5596.96 rows=113829 width=4)
  (actual time=0.010..17.567 rows=114192 loops=1)
  Filter: (("FunctionType")::text = 'MAIRE'::text)
  Rows Removed by Filter: 158845
Planning Time: 0.217 ms
Execution Time: 20.136 ms

Le plan d’exécution est un arbre et chaque node a un coût estimé dont les unités sont arbitraires. Il faut noter que « le coût d’un nœud père comprend le coût de tous ses fils ». Seq Scan veut dire que la base de données parcourt toute la table Function à la recherche de chaînes correspondantes. Pour éviter cela, créons un index sur la colonne FunctionType, puis exécutons EXPLAIN ANALYZE à nouveau avec la même requête. (Dans cet exercice nous nous limiterons à utiliser des index de type B-Tree, que la commande CREATE INDEX utilise par défaut.)

1
2
3

CREATE INDEX index_function ON "Function" (
    "FunctionType"
)

Il en résulte un plan d’exécution différent :

QUERY PLAN
Bitmap Heap Scan on "Function"  (cost=1286.60..4893.46 rows=113829 width=4)
  (actual time=3.764..11.449 rows=114192 loops=1)
  Recheck Cond: (("FunctionType")::text = 'MAIRE'::text)
  Heap Blocks: exact=822
  ->  Bitmap Index Scan on index_function
      (cost=0.00..1258.14 rows=113829 width=0)
      (actual time=3.589..3.589 rows=114192 loops=1)
        Index Cond: (("FunctionType")::text = 'MAIRE'::text)
Planning Time: 0.314 ms
Execution Time: 13.551 ms

Postgres a effectué un parcours de bitmap, que Tom Lane, un des développeurs de Postgres, a expliqué dans ce message publié sur une liste de diffusion.

Un parcours de bitmap récupère tous les pointeurs de n-uplets de l’index en une seule fois, les trie en mémoire à l’aide d’une structure de données appelée « bitmap », puis visite les n-uplets de la table dans l’ordre physique de leur emplacement… Si le bitmap devient trop volumineux, nous le convertissons en bitmap « avec perte », dans lequel nous ne notons que les pages contenant des n-uplets correspondants au lieu de noter chaque n-uplet individuellement. Dans ce cas-là, quand nous lisons ces pages de la table, il faut examiner chaque n-uplet de chaque page lue et revérifier la condition du parcours pour déterminer les n-uplets à renvoyer.

Ceci est plus efficace qu’un parcours de table, mais nous payons toujours le prix de l’accès à la table pour récupérer les n-uplets (c’est-à-dire les lignes) et celui de la revérification de la condition du parcours. Comme il ne nous faut que la colonne MandateId, nous pouvons la mettre elle aussi dans l’index, pour créer un index couvrant pour cette requête :

CREATE INDEX index_function ON "Function" (
    "FunctionType"
)
INCLUDE (
    "MandateId"
)

Cela nous donne un autre plan d’exécution :

QUERY PLAN
Index Only Scan using index_function on "Function"
  (cost=0.42..4490.35 rows=115003 width=4)
  (actual time=0.027..7.354 rows=114192 loops=1)
  Index Cond: ("FunctionType" = 'MAIRE'::text)
  Heap Fetches: 0
Planning Time: 0.184 ms
Execution Time: 9.025 ms

Maintenant Postgres peut faire un parcours d’index seul, parce que toutes les colonnes qu’il nous faut sont dans l’index. Cela semble être une amélioration, mais faisons un test de performance pour vérifier. Testons plusieurs requêtes qui cherchent différentes fonctions, y compris celle de maire. Nous ferons le test d’abord sans index, puis avec chacun des index ci-dessus.

SELECT "MandateId"
FROM "Function"
WHERE "FunctionType" = 'MAIRE'
FETCH FIRST 750 ROWS ONLY

SELECT "MandateId"
FROM "Function"
WHERE "FunctionType" = 'MAIRE DELEGUE'
FETCH FIRST 750 ROWS ONLY

SELECT "MandateId"
FROM "Function"
WHERE "FunctionType" = 'PRESIDENT DU CONSEIL REGIONAL'
FETCH FIRST 750 ROWS ONLY

SELECT "MandateId"
FROM "Function"
WHERE "FunctionType" = 'PREMIER ADJOINT AU MAIRE'
FETCH FIRST 750 ROWS ONLY

Il est clair qu’il vaut mieux avoir un index que ne pas en avoir. Par rapport à l’index qui ne contient que FunctionType, celui qui comprend aussi MandateId (et permet donc un parcours d’index seul) ne change pas grand-chose pour certaines valeurs de FunctionType, mais il est plus de deux fois plus rapide pour MAIRE.

Trier #

Nous aimerions obtenir des résultats triés par date de début de fonction :

EXPLAIN ANALYZE
SELECT "MandateId"
FROM "Function"
WHERE "FunctionType" = 'MAIRE'
ORDER BY "FunctionStartDate"

Sans index, la base de données indique que cette requête prend environ deux fois plus de temps que sans le tri :

QUERY PLAN
Sort  (cost=15354.29..15644.28 rows=115995 width=8)
      (actual time=32.564..37.109 rows=114192 loops=1)
  Sort Key: "FunctionStartDate"
  Sort Method: external merge  Disk: 2016kB
  ->  Seq Scan on "Function"
      (cost=0.00..5596.96 rows=115995 width=8)
      (actual time=0.016..17.797 rows=114192 loops=1)
        Filter: (("FunctionType")::text = 'MAIRE'::text)
        Rows Removed by Filter: 158845
Planning Time: 0.398 ms
Execution Time: 40.132 ms

Il est intéressant de noter que si nous utilisons l’index de la section précédente avec cette requête, cela ne change pas le plan d’exécution cette fois-ci. Postgres a décidé que notre index n’apportera probablement pas d’avantage à cette requête. Pour que l’index vaille la peine d’être utilisé ici, ajoutons-y la colonne FunctionStartDate, pour que les entrées pour chaque type de fonction soient triées par date de début dans l’index :

CREATE INDEX index_function ON "Function" (
    "FunctionType",
    "FunctionStartDate"
)
INCLUDE (
    "MandateId"
)

QUERY PLAN
Index Only Scan using index_function on "Function"
  (cost=0.42..4743.89 rows=115995 width=8)
  (actual time=0.052..9.744 rows=114192 loops=1)
  Index Cond: ("FunctionType" = 'MAIRE'::text)
  Heap Fetches: 0
Planning Time: 0.432 ms
Execution Time: 12.275 ms

Cela nous donne à nouveau un parcours d’index seul, qui semble plus efficace. Faisons un test de performance pour comparer l’index précédent à celui-ci. Nous utiliserons les requêtes de la section précédente, en ajoutant ORDER BY "FunctionStartDate" à chacune d’elles.

Il semble que plus il y a de lignes à trier, plus il soit avantageux d’utiliser un index qui est déjà trié dans l’ordre demandé par la clause ORDER BY. Cet avantage est très important dans le cas de MAIRE (114 192 lignes) et PREMIER ADJOINT AU MAIRE (37 511 lignes) et moins important dans les autres cas, qui renvoient beaucoup moins de lignes.

Ajouter des jointures #

Maintenant que nous avons MandateId, nous pouvons récupérer des clés étrangères sur la ligne correspondante de la table Mandate, puis effectuer des jointures pour obtenir plus d’informations sur la personne qui a été élue et la commune où l’élection a eu lieu. Commençons par la commune. La table Area contient des données sur différents niveaux géographiques, y compris les communes. Avant de pouvoir nous renseigner sur la commune, nous devons obtenir son identifiant dans la table Mandate. Regardons d’abord le plan d’exécution d’une requête qui fait cela, sans l’exécuter :

EXPLAIN
SELECT
    func."FunctionStartDate",
    m."AreaId"
FROM 
    "Function" func,
    "Mandate" m
WHERE
    func."FunctionType" = 'MAIRE'
    AND func."MandateId" = m."MandateId"
ORDER BY func."FunctionStartDate"
FETCH FIRST 750 ROWS ONLY

QUERY PLAN
Limit  (cost=0.85..968.89 rows=750 width=36)
  ->  Nested Loop  (cost=0.85..147087.20 rows=113957 width=36)
        ->  Index Only Scan using index_function on "Function" func
            (cost=0.42..4664.34 rows=113957 width=8)
              Index Cond: ("FunctionType" = 'MAIRE'::text)
        ->  Index Scan using "pk_Mandat" on "Mandate" m
            (cost=0.43..1.25 rows=1 width=36)
              Index Cond: ("MandateId" = func."MandateId")

La base de données fait toujours un Index Only Scan pour la table Fonction, mais elle fait un Index Scan pour la table Mandate, en utilisant l’index de clé primaire de cette table. Cela veut dire qu’elle parcourt l’index jusqu’à ce qu’elle trouve le MandateId correspondant, puis récupère la ligne correspondante de la table Mandate pour obtenir l’AreaId. Nous pouvons créer un index qui contient AreaId pour effectuer un parcours d’index seul :

`1`	`CREATE INDEX index_mandate ON "Mandate" ("MandateId") INCLUDE ("AreaId")`

Voici le plan d’exécution qui en résulte :

QUERY PLAN
Limit  (cost=0.85..505.54 rows=750 width=10)
  ->  Nested Loop  (cost=0.85..76310.71 rows=113401 width=10)
        ->  Index Only Scan using index_function on "Function" func
            (cost=0.42..4643.26 rows=113401 width=8)
              Index Cond: ("FunctionType" = 'MAIRE'::text)
        ->  Index Only Scan using index_mandate on "Mandate" m
            (cost=0.43..0.63 rows=1 width=10)
              Index Cond: ("MandateId" = func."MandateId")

Il semble que le coût ait baissé. Faisons un test de performance, encore une fois avec différentes valeurs pour FunctionType, pour comparer l’index de clé primaire à l’index couvrant. Dans les deux cas nous garderons notre index le plus performant sur Function.

L’index couvrant ne fait pas une grande différence, mais semble toutefois utile.

Maintenant que nous avons l’AreaId de la commune, nous pouvons obtenir son nom et son code géographique (qui n’est pas la même chose que le code postal). Nous aimerions aussi avoir le nom de la personne qui a été élue.

SELECT
    func."FunctionStartDate",
    area."AreaCode" as code_commune,
    area."AreaName" as commune,
    indiv."FirstName",
    indiv."LastName"
FROM "Function" func
JOIN "Mandate" m ON func."MandateId" = m."MandateId"
JOIN "Area" area ON m."AreaId" = area."AreaId"
JOIN "Individual" indiv ON m."IndividualId" = indiv."IndividualId"
WHERE func."FunctionType" = 'MAIRE'
ORDER BY func."FunctionStartDate"
FETCH FIRST 100 ROWS ONLY

Comme il y a plusieurs jointures, j’ai utilisé le mot-clé JOIN pour que la requête soit un peu plus facile à lire. (Cela ne change pas le plan d’exécution.) Et comme la requête renvoie maintenant davantage de colonnes, j’ai demandé moins de lignes, pour que les résultats du test de performance ne soient pas dominés par le temps qu’il faut pour renvoyer les résultats de la requête.

Pour la jointure entre Mandate et Individual, nous ajoutons IndividualId à notre index sur Mandate :

1
2
3

CREATE INDEX index_mandate ON "Mandate" ("MandateId") INCLUDE (
    "AreaId", "IndividualId"
)

Puis nous créons des index couvrants sur Area et Individual pour notre requête :

CREATE INDEX index_area ON "Area" ("AreaId") INCLUDE ("AreaCode", "AreaName");

CREATE INDEX index_indiv ON "Individual" ("IndividualId") INCLUDE (
    "FirstName", "LastName"
);

Cela donne le plan d’exécution suivant :

QUERY PLAN
Limit  (cost=1.57..132.35 rows=100 width=38)
  ->  Nested Loop  (cost=1.57..148131.29 rows=113274 width=38)
        ->  Nested Loop  (cost=1.15..96170.50 rows=113274 width=34)
              ->  Nested Loop  (cost=0.85..82875.64 rows=113274 width=22)
                    ->  Index Only Scan using index_function on "Function" func
                        (cost=0.42..4636.71 rows=113274 width=8)
                          Index Cond: ("FunctionType" = 'MAIRE'::text)
                    ->  Index Only Scan using index_mandate on "Mandate" m
                        (cost=0.43..0.69 rows=1 width=22)
                          Index Cond: ("MandateId" = func."MandateId")
              ->  Memoize  (cost=0.30..0.32 rows=1 width=24)
                    Cache Key: m."AreaId"
                    Cache Mode: logical
                    ->  Index Only Scan using index_area on "Area" area
                        (cost=0.29..0.31 rows=1 width=24)
                          Index Cond: ("AreaId" = (m."AreaId")::text)
        ->  Index Only Scan using index_indiv on "Individual" indiv
            (cost=0.42..0.46 rows=1 width=28)
              Index Cond: ("IndividualId" = (m."IndividualId")::text)

Toutes les données viennent des index, les tables n’étant pas utilisés du tout. Si nous ne créons pas les deux derniers index, il y a des Index Scan plutôt que des Index Only Scan sur Area et Individual. Comparons la performance de cette requête avec et sans ces deux index.

Il y a très peu de différence, mais garderons les index.

Comparons maintenant la performance de cette dernière requête sans aucun index (à part les index de clé primaire qui ont été créés par défaut) et avec tous les index que nous avons créés :

Cette requête est 14 à 24 fois plus rapide avec les index que sans eux.

Encore plus de jointures #

Essayons de récupérer le nom du département auquel la commune appartient. Nous pouvons ajouter une jointure sur la table Inclusion pour trouver l’Area qui représente le département :

EXPLAIN
SELECT
    func."FunctionStartDate",
    area1."AreaCode" as code_commune,
    area1."AreaName" as commune,
    area2."AreaName" as departement,
    indiv."FirstName",
    indiv."LastName"
FROM "Function" func
JOIN "Mandate" m ON func."MandateId" = m."MandateId"
JOIN "Area" area1 ON m."AreaId" = area1."AreaId"
JOIN "Inclusion" incl on m."AreaId" = incl."IncludedAreaId"
JOIN "Area" area2 on incl."IncludingAreaId" = area2."AreaId"
JOIN "Individual" indiv ON m."IndividualId" = indiv."IndividualId"
WHERE func."FunctionType" = 'MAIRE'
AND area2."AreaType" = 'Département'
ORDER BY func."FunctionStartDate"
FETCH FIRST 100 ROWS ONLY

QUERY PLAN
Limit  (cost=35292.57..35304.24 rows=100 width=51)
  ->  Gather Merge  (cost=35292.57..35351.14 rows=502 width=51)
        Workers Planned: 2
        ->  Sort  (cost=34292.55..34293.18 rows=251 width=51)
              Sort Key: func."FunctionStartDate"
              ->  Nested Loop  (cost=30010.19..34282.96 rows=251 width=51)
                    ->  Parallel Hash Join  (cost=30009.76..34167.82 rows=251 width=47)
                          Hash Cond: (func."MandateId" = m."MandateId")
                          ->  Parallel Index Only Scan using index_function on "Function" func
                              (cost=0.42..3980.29 rows=47235 width=8)
                                Index Cond: ("FunctionType" = 'MAIRE'::text)
                          ->  Parallel Hash  (cost=29971.32..29971.32 rows=3042 width=47)
                                ->  Hash Join  (cost=2914.37..29971.32 rows=3042 width=47)
                                      Hash Cond: ((m."AreaId")::text = (area1."AreaId")::text)
                                      ->  Parallel Seq Scan on "Mandate" m
                                          (cost=0.00..24881.12 rows=572112 width=22)
                                      ->  Hash  (cost=2911.27..2911.27 rows=248 width=43)
                                            ->  Nested Loop
                                                (cost=967.16..2911.27 rows=248 width=43)
                                                  ->  Hash Join
                                                      (cost=966.88..2832.29 rows=248 width=19)
                                                        Hash Cond:
                                                        ((incl."IncludingAreaId")::text =
                                                         (area2."AreaId")::text)
                                                        ->  Seq Scan on "Inclusion" incl
                                                            (cost=0.00..1607.70
                                                             rows=98170 width=15)
                                                        ->  Hash
                                                            (cost=965.40..965.40
                                                             rows=118 width=19)
                                                              ->  Seq Scan on "Area" area2
                                                                  (cost=0.00..965.40
                                                                   rows=118 width=19)
                                                                    Filter:
                                                                    (("AreaType")::text =
                                                                    'Département'::text)
                                                  ->  Index Only Scan using index_area
                                                      on "Area" area1
                                                      (cost=0.29..0.32 rows=1 width=24)
                                                        Index Cond:
                                                        ("AreaId" =
                                                         (incl."IncludedAreaId")::text)
                    ->  Index Only Scan using index_indiv on "Individual" indiv
                        (cost=0.42..0.46 rows=1 width=28)
                          Index Cond: ("IndividualId" = (m."IndividualId")::text)

Qu’est-ce qui s’est passé ? Postgres a décidé qu’une jointure de hachage serait plus efficace que l’ajout d’une autre boucle imbriquée. Plutôt que d’utiliser notre index sur la table Mandate, il compte lire environ 500 000 lignes et les mettre dans une table de hachage en mémoire. Il utilise l’index trié par date sur Fonction, mais comme une table de hachage n’est pas triée, il doit ensuite trier les résultats à nouveau. En utilisant EXPLAIN ANALYZE, nous pouvons constater que la requête prend à peu près 600 ms. Le simple fait d’obtenir le nom du département a ralenti notre requête de plusieurs centaines de fois.

Nous avons plusieurs options :

Donner à l’optimiseur une meilleure option que la jointure de hachage.
Optimiser la jointure de hachage en demandant moins de colonnes (ce qui n’est pas vraiment possible dans notre cas) ou moins de lignes (nous pourrions, par exemple, ajouter une condition WHERE comme func."FunctionStartDate" < DATE '1975-01-01').
Effectuer la jointure dans l’application. Dans le cas présent, comme il n’y a que 101 départements en France et qu’ils changent très rarement, l’application pourrait les lire au démarrage. Le code géographique de chaque commune (que nous avons déjà obtenu avec la requête précédente) contient le code du département. Il serait donc facile pour l’application de chercher le département en mémoire.

Essayons la première option. Nous pouvons ajouter cet index :

1
2
3

CREATE INDEX index_inclusion ON "Inclusion" ("IncludedAreaId") INCLUDE (
    "IncludingAreaId"
);

Cela nous donne à nouveau un plan d’exécution à boucles imbriquées :

QUERY PLAN
Limit  (cost=1002.32..10605.10 rows=100 width=51)
  ->  Nested Loop  (cost=1002.32..58907.08 rows=603 width=51)
        ->  Gather Merge  (cost=1001.89..58630.47 rows=603 width=47)
              Workers Planned: 2
              ->  Nested Loop  (cost=1.87..57560.84 rows=251 width=47)
                    ->  Nested Loop  (cost=1.58..57476.99 rows=272 width=41)
                          ->  Nested Loop  (cost=1.28..53851.27 rows=107699 width=37)
                                ->  Nested Loop  (cost=0.85..36596.43 rows=47235 width=22)
                                      ->  Parallel Index Only Scan using index_function
                                          on "Function" func
                                          (cost=0.42..3980.29 rows=47235 width=8)
                                            Index Cond: ("FunctionType" = 'MAIRE'::text)
                                      ->  Index Only Scan using index_mandate on "Mandate" m
                                          (cost=0.43..0.69 rows=1 width=22)
                                            Index Cond: ("MandateId" = func."MandateId")
                                ->  Memoize  (cost=0.43..0.46 rows=2 width=15)
                                      Cache Key: m."AreaId"
                                      Cache Mode: logical
                                      ->  Index Only Scan using index_inclusion
                                          on "Inclusion" incl
                                          (cost=0.42..0.45 rows=2 width=15)
                                            Index Cond: ("IncludedAreaId" = (m."AreaId")::text)
                          ->  Memoize  (cost=0.30..0.34 rows=1 width=19)
                                Cache Key: incl."IncludingAreaId"
                                Cache Mode: logical
                                ->  Index Scan using "pk_Territoire" on "Area" area2
                                    (cost=0.29..0.33 rows=1 width=19)
                                      Index Cond:
                                      (("AreaId")::text = (incl."IncludingAreaId")::text)
                                      Filter: (("AreaType")::text = 'Département'::text)
                    ->  Index Only Scan using index_area on "Area" area1
                        (cost=0.29..0.31 rows=1 width=24)
                          Index Cond: ("AreaId" = (m."AreaId")::text)
        ->  Index Only Scan using index_indiv on "Individual" indiv
            (cost=0.42..0.46 rows=1 width=28)
              Index Cond: ("IndividualId" = (m."IndividualId")::text)

Le coût reste pourtant assez élevé, et EXPLAIN ANALYZE indique que la requête prend 12 ms environ. Un test de performance indique qu’elle peut être 10 à 20 fois plus lente que notre requête précédente :

Il serait plus efficace de garder la requête précédente et d’effectuer la jointure dans l’application.

Conclusion #

Cette exercice a démontré quelques points importants sur l’optimisation des bases de données :

À chaque fois que nous modifions une requête, il faut revérifier le plan d’exécution pour connaître l’effet de la modification sur les performances.
Des requêtes différentes peuvent avoir besoin d’index différents.
Un parcours d’index seul peut être le meilleur moyen d’améliorer la performance d’une requête dans certains cas, mais il faut vérifier cette hypothèse en la testant.
Parfois la meilleure optimisation est de demander moins de données.

Tous les scripts et les fichiers de configuration que j’ai utilisés pour cet exercice se trouvent dans ce dépôt git.

Pour en savoir plus sur ce sujet, je recommande le site web Use the Index, Luke! de Markus Winand, ainsi que son livre SQL : Au cœur des performances.

Lire la presse avec un pass de la BnF

Sat, 21 Sep 2024 00:00:00 +0000

Beaucoup de titres de presse sont réservés aux abonnés et les abonnements peuvent coûter cher. Pour s’informer à moindre coût, on peut acheter un Pass Lecture/Culture de la Bibliothèque nationale de France. Le prix est actuellement 24 € par an, ou 15 € au tarif réduit. Ce pass donne accès à un grand nombre de titres du monde entier, y compris :

Voici un petit tutoriel pour en tirer le meilleur parti. En somme, c’est moins commode que de s’abonner directement à chaque titre, mais ça coûte beaucoup moins cher. Notez bien qu’après l’achat du pass, il faudra attendre quelques jours pour qu’il commence à fonctionner.

Comment ça marche #

Le moyen d’accéder aux articles dépend du titre de presse. Dans tous les cas, rendez-vous sur la page Bases de données par titre de la BnF. Il y a plusieurs cas de figure :

Lecture sur le site original #

C’est possible avec quelques titres :

Mediapart
Alternatives économiques
Arrêt sur images
The New York Times

Dans les trois premiers cas, il suffit de saisir le titre (par ex. Mediapart) dans le champ Recherche par mot du titre ou de la description de la page Bases de données par titre et de cliquer sur le lien qui s’affiche en dessous. Vous devrez ensuite vous connecter à votre compte BnF, si vous ne l’avez pas encore fait, avant d’être redirigé vers le titre choisi.

Le cas de The New York Times est un peu différent : après avoir saisi le titre, vous verrez des instructions supplémentaires à suivre pour créer un pass New York Times valable 72 heures.

Lecture au format PDF sur Europresse #

C’est possible pour certains titres, y compris :

Courrier international
Le Monde
Le Monde diplomatique
Libération

Saisissez Europresse dans le champ Recherche par mot du titre ou de la description de la page Bases de données par titre et cliquez sur le lien qui apparaît. Une fois sur le site d’Europresse, cliquez sur Publications PDF et cherchez le titre voulu.

Lecture sur le site d’Europresse #

Cela vaut entre autres pour :

Le Monde
Libération

En effet, pour les titres auxquels Europresse donne accès mais qu’il ne propose pas au format PDF, il affiche le texte intégral des articles sur son propre site. L’inconvénient, c’est qu’il ne propose aucune navigation et s’attend à ce que vous trouviez chaque article en utilisant son moteur de recherche.

Sur un ordinateur (avec Firefox ou Chrome) ou sur Android (avec Firefox), je vous conseille d’installer plutôt l’extension Ophirofox dans votre navigateur. Quand vous naviguez sur le site d’un journal compatible, l’extension ajoute un bouton Lire sur Europresse sur les articles réservés aux abonnés. En réalité ce bouton ne fait qu’ouvrir le site d’Europresse, saisir le titre de l’article que vous regardiez et lancer la recherche, ce qui fait gagner du temps.

Ophirofox n’est pas disponible pour iPhone. Dans ce cas-là :

Copiez le titre de l’article.
Visitez Bases de données par titre, saisissez Europresse et cliquez sur le lien affiché.
Cliquez sur Recherche avancée.
Collez le titre la où il y a écrit dans le titre.
Cliquez sur Recherche.

Lecture sur PressReader #

Cela vaut entre autres pour :

The Wall Street Journal
The Economist
Süddeutsche Zeitung
Der Tagesspiegel

Pour y arriver :

Visitez Bases de données par titre, saisissez PressReader et cliquez sur le lien affiché.
Cliquez sur Select Publication.
Trouvez le titre voulu et cliquez dessus.
Cliquez sur une page pour l’agrandir.

Les boutons en bas à gauche permettent d’afficher soit chaque page au format PDF, soit le texte des articles.