Pourquoi une API générée plutôt qu'un backend écrit à la main
Dans la plupart des applications, une grande partie du code serveur ne fait que traduire des requêtes HTTP en SQL : lister, filtrer, paginer, créer, modifier, supprimer, en vérifiant à chaque fois que l'utilisateur a le droit de le faire. Ce code est répétitif, il faut le tester, et chaque nouvelle colonne oblige à le retoucher.
Hasura part du schéma de la base. Une table suivie devient un type GraphQL, une clé étrangère devient un champ imbriqué, et une règle de permission écrite une fois s'applique à toutes les requêtes. La logique propre à votre métier — un paiement, un envoi d'e-mail, un calcul — reste dans votre code, que Hasura appelle par webhook. Vous gardez la base PostgreSQL : rien n'est enfermé dans un format propriétaire.
Ce que Hasura apporte
- API GraphQL instantanée — requêtes, mutations, filtres, tri, pagination et agrégats sur chaque table suivie.
- Relations — les clés étrangères deviennent des champs imbriqués, interrogeables en une seule requête.
- Souscriptions temps réel — un client s'abonne à une requête et reçoit les changements par WebSocket.
- Permissions par rôle — règles par ligne et par colonne, alimentées par les claims d'un jeton JWT.
- Actions et triggers — webhooks appelés par une mutation, par un changement de données ou selon un horaire cron.
- Console et endpoints REST — administration web, explorateur GraphiQL, et conversion d'une requête en route REST.
Hasura face aux autres façons d'exposer PostgreSQL
Faites défiler le tableau
| Hasura | API écrite à la main | PostgREST | |
|---|---|---|---|
| API générée depuis le schéma | Oui, GraphQL et REST | Non | Oui, REST |
| Relations imbriquées en une requête | Oui | Selon le code | Oui, par embedding |
| Temps réel | Souscriptions GraphQL | À développer | Non |
| Permissions | Par rôle, ligne et colonne, dans la console | Dans le code | Rôles et RLS PostgreSQL |
| Logique métier | Actions et triggers en webhooks | Libre | Fonctions SQL |
| Interface d'administration | Console web | Non | Non |
Prérequis
Un VPS Ubuntu 24.04 avec 1 Go de RAM suffit pour démarrer : au repos, le moteur Hasura et PostgreSQL occupent ensemble environ 200 Mo. Prévoyez 2 Go dès que la base grossit ou que les souscriptions se multiplient. Il vous faut Docker avec le plugin Compose, et un nom de domaine pointant vers le VPS, avec nginx et un certificat HTTPS : votre API sera appelée par des navigateurs et des applications mobiles, elle doit répondre sur une adresse stable et chiffrée.
Installer Hasura avec Docker Compose
Préparer les secrets
Créez le répertoire de l'application et un fichier
.envportant le mot de passe de la base et l'admin secret, la clé maîtresse de l'API. Le fichier n'est lisible que par root.mkdir -p /opt/hasura && cd /opt/hasura cat > .env <<EOF DB_PASSWORD=$(openssl rand -hex 16) ADMIN_SECRET=$(openssl rand -hex 24) EOF chmod 600 .envCréer le fichier Compose
Ce
docker-compose.ymldémarre PostgreSQL sur le réseau interne de la stack, sans port publié, puis Hasura une fois la base prête. Le port de Hasura n'est publié que sur la boucle locale ; la console est servie depuis l'image, sans appel au CDN de l'éditeur, et la télémétrie est coupée.services: postgres: image: postgres:17.11-alpine restart: unless-stopped environment: POSTGRES_DB: hasura POSTGRES_USER: hasura POSTGRES_PASSWORD: ${DB_PASSWORD} volumes: - hasura-pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U hasura -d hasura"] interval: 10s retries: 10 hasura: image: hasura/graphql-engine:v2.51.3 restart: unless-stopped depends_on: postgres: condition: service_healthy ports: - "127.0.0.1:8103:8080" env_file: .env environment: HASURA_GRAPHQL_DATABASE_URL: postgres://hasura:${DB_PASSWORD}@postgres:5432/hasura HASURA_GRAPHQL_ADMIN_SECRET: ${ADMIN_SECRET} HASURA_GRAPHQL_ENABLE_CONSOLE: "true" HASURA_GRAPHQL_CONSOLE_ASSETS_DIR: /srv/console-assets HASURA_GRAPHQL_DEV_MODE: "false" HASURA_GRAPHQL_ENABLE_TELEMETRY: "false" volumes: hasura-pgdata: {}Démarrer la stack
Au premier démarrage, Hasura crée ses tables de métadonnées dans le schéma
hdb_cataloget connecte la base comme sourcedefault. Le point/healthzrépondOKquand le moteur est prêt.docker compose up -d curl -fsS http://127.0.0.1:8103/healthz # OKPublier en HTTPS derrière nginx
Ajoutez un bloc
serverpour votre domaine, avec un certificat Let's Encrypt. Les en-têtesUpgradeetConnectionsont indispensables : les souscriptions passent par WebSocket.location / { proxy_pass http://127.0.0.1:8103; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; }
L'admin secret ne quitte jamais le serveur
Sans HASURA_GRAPHQL_ADMIN_SECRET, la console et toute l'API sont ouvertes à quiconque connaît l'adresse. Avec lui, il donne tous les droits : lecture et écriture de toutes les tables, exécution de SQL, modification des métadonnées. Gardez-le pour la console et vos scripts d'administration, et ne le placez jamais dans le code d'un frontend ou d'une application mobile.
Créer une table et l'interroger
Ouvrez https://api.example.com/console, saisissez l'admin secret, puis, dans l'onglet Data, créez une table todos avec les colonnes id (entier auto-incrémenté), title (texte) et done (booléen). Cliquez sur Track : la table apparaît aussitôt dans l'explorateur de l'onglet API. Depuis un script d'administration, la même requête s'envoie avec l'admin secret :
curl -s https://api.example.com/v1/graphql \
-H "x-hasura-admin-secret: $ADMIN_SECRET" \
-H 'content-type: application/json' \
-d '{"query":"{ todos { id title done } }"}'Authentifier vos utilisateurs et poser les permissions
Vos utilisateurs ne doivent pas utiliser l'admin secret : ils présentent un jeton JWT émis par votre fournisseur d'identité (Logto, Authentik, Zitadel, Auth0…). Indiquez à Hasura où trouver les clés de vérification, et quel rôle donner aux requêtes sans jeton, dans le fichier .env :
HASURA_GRAPHQL_JWT_SECRET={"type":"RS256","jwk_url":"https://auth.example.com/oidc/jwks"}
HASURA_GRAPHQL_UNAUTHORIZED_ROLE=anonymousRelancez la stack avec docker compose up -d : le service hasura lit ce fichier par env_file. Le jeton doit porter les claims x-hasura-default-role, x-hasura-allowed-roles et x-hasura-user-id. Dans l'onglet Permissions de chaque table, définissez alors ce que chaque rôle peut lire, insérer ou modifier — par exemple, le rôle user ne voit que les lignes où user_id vaut X-Hasura-User-Id.
Dépannage
La console affiche « invalid x-hasura-admin-secret » : le secret saisi ne correspond pas à la valeur du .env. Vérifiez-la avec grep ADMIN_SECRET /opt/hasura/.env, puis rechargez la page.
Hasura redémarre en boucle : la base n'est pas joignable. docker compose logs hasura affiche l'erreur de connexion ; vérifiez que le mot de passe de l'URL HASURA_GRAPHQL_DATABASE_URL est bien celui de PostgreSQL. Si vous l'avez changé après le premier démarrage, PostgreSQL a gardé l'ancien : il ne lit POSTGRES_PASSWORD qu'à la création du volume.
Les souscriptions se coupent : le reverse proxy ne transmet pas la mise à niveau WebSocket. Ajoutez les en-têtes Upgrade et Connection montrés plus haut, et augmentez proxy_read_timeout si vos clients restent longtemps inactifs.
Une table n'apparaît pas dans l'API : elle existe dans la base mais n'est pas suivie. Cliquez sur Track dans l'onglet Data, ou suivez toutes les tables du schéma en une fois.
Installation en un clic depuis le Marketplace ServOrbit
Le Marketplace ServOrbit installe Hasura sur votre VPS sans ligne de commande : il déploie PostgreSQL et le moteur Hasura, génère l'admin secret et le mot de passe de la base, connecte la base comme source default et publie l'API en HTTPS sur un sous-domaine de votre domaine ou sur le sous-domaine gratuit du VPS. L'admin secret s'affiche dans votre espace client ; il ne reste qu'à ouvrir la console et à créer vos tables.
