Skip to content

Créer une extension Postgres en Rust, Episode 1 : Un nouveau monde

Photo Credit Jacob Colvin

{% include-markdown "index.md" start="" end="" %}

Objectifs

Dans cette première partie, nous avons pour objectifs de:

  • Initialiser un environnement de developpement [PGRX]
  • Créer une extension minimale
  • Lancer l'extension dans une instance Postgres

Bonjour le monde

On peut maintenant créer une extension nommée world avec:

cargo pgrx new world

Un nouveau dossier world vient d'apparaitre et contient le strict nécessaire pour générer une extension Postgres, notamment un fichier source (src/lib.rs) qui contient la fonction suivante hello_world:

#[pg_extern]
fn hello_world() -> &'static str {
    "Hello, world"
}

La fonction retourne une valeur statique de type str ( appelé slice de chaînes de caractères) qui représente simplement une suite de caractères UTF-8. Cette valeur de retour sera automatiquement convertie en type TEXT pour Postgres.

Tous les types essentiels de Postgres sont automatiquement convertis en type Rust La liste complète des conversions est disponible ci-dessous:

https://github.com/pgcentralfoundation/pgrx#mapping-of-postgres-types-to-rust

Lancer l'extension

[PGRX] va maintenant pouvoir lancer une instance Postgres, charger cette nouvelle extension, créer une base de test et ouvrir une session de travail dessus:

cd world
cargo pgrx run

Attention! Cette commande va compiler une centaine de paquets Rust (crates) et peut durer une dizaine de minutes !

world=# CREATE EXTENSION world;
CREATE EXTENSION

world=# SELECT hello_world();
 hello_world
--------------
 Hello, world
(1 row)

Ajouter une nouvelle fonction

Dans le fichier world/src/lib.rs, on peut ajouter autant de nouvelles fonctions que nécessaires.

Par exemple:

#[pg_extern]
fn hello(name: &str) -> String {
    format!("Hello, {name}")
}

Note: Par facilité, on utilise ici le type String plutot que &str pour la valeur de retour... Le type String sera également converti en type TEXT pour Postgres

Lançons à nouveau l'extension

cargo pgrx run

Cette fois, seul le module world est recompilé !

Une fois dans la nouvelle session psql, on recharge l'extension:

world=# DROP EXTENSION world;
world=# CREATE EXTENSION world;

Et la nouvelle fonction est disponible:

world=# SELECT hello('Bob');
   hello
------------
 Hello, Bob
(1 row)

Ecrire la même chose en C ?

En guise de comparaison, voici 2 extensions similaires écrites en langage C:

https://github.com/magnusp/pg_hello/blob/master/pg_hello.c

https://github.com/petr-korobeinikov/postgresql-extension-example/blob/master/hello_ext/hello_ext.c

Pour aller plus loin...

Voici quelques propositions d'activités pour poursuivre la découverte:

  • En utilisant la macro panic!, créer une fonction hello2() qui renvoie une erreur si la variable name est vide.

  • En utilisant la commande match, dites "Bonjour" si le nom Pierre et "Hola" si le nom est Diego ou Maya.

Un exemple d'implémentation est disponible sur:

https://gitlab.com/daamien/pgrx-notebook/-/blob/main/world/src/lib.rs

Bilan

En quelques minutes, on a pu créer une extension Postgres pour écrire et tester des fonctions internes.

Si l'on fait la comparaison avec le framework classique de développement d'extensions en C ( PGXS ), on remarque déjà plusieurs avantages clairs

  • La création de l'environnement de développement est automatisée
  • La création de nouvelles fonctions est très simple
  • Tous les types de base Postgres sont automatiquement convertis
  • La manipulation des chaines de caractères est bien plus souple en Rust

La suite au prochain épisode !

Jusqu'où Rust nous menera-t-il ? Rendez-vous dans l'[Episode 2 : Demander le luhn] pour le savoir !