Migrations SQL à distance

Pour appliquer du DDL ou du DML contrôlé sur le schéma tenant sans ouvrir la console (CI, générateurs de code, agents), Kuunda expose un point de terminaison sur l’application dashboard (pas sur la passerelle PostgREST). Le comportement est proche d’un flux « type Supabase » : authentification par la clé projet service_role uniquement.

Point de terminaison

Méthode : POST
URL : {origine_dashboard}/api/projects/{ref8}/migrate/service-role
En production, l’origine dashboard est souvent https://app.kuunda-cloud.com (variable NEXT_PUBLIC_APP_URL dans cette doc).
Le ref8 dans l’URL doit être celui du projet associé à la clé (sinon 403).

Authentification

En-tête apikey ou Authorization: Bearer avec la clé service_role du projet. La clé anon est refusée (service_role_required).

Corps de la requête

JSON :

{ "sql": "CREATE TABLE …" }

Limites de taille et filtres SQL : alignés sur l’éditeur SQL de la console (garde-fous côté monorepo : tenant-migration-sql-guards).

Exemple cURL

Remplacez abcdef12 par la ref de votre projet et la clé par votre secret service_role.

curl -sS -X POST "https://app.kuunda-cloud.com/api/projects/abcdef12/migrate/service-role" \
  -H "Content-Type: application/json" \
  -H "apikey: <VOTRE_CLE_SERVICE_ROLE>" \
  -d '{"sql":"CREATE TABLE example (id uuid PRIMARY KEY DEFAULT gen_random_uuid());"}'

Sécurité

Ne jamais exposer la clé service_role dans le front ou dans un dépôt public.
Préférer des appels depuis le serveur (CI, backend, agent avec secret managé).
Réponse JSON en cas de succès : même forme que la route console query/migrate (ok, rowCount, etc.).

Voir aussi

Console : Paramètres → API — bloc « Migrations SQL à distance » avec URL et exemple pour votre projet.
Entrée technique de l'API (passerelle) — PostgREST, pas les migrations.
SDK : packages/kuunda-js/README.md (section migrations).