Pocketbase

SDK Client, Realtime et Backups PocketBase – Guide 2026

SDK Client, Realtime et Backups PocketBase – Guide 2026

PocketBase est un backend open-source complet qui inclut des APIs utilitaires pour la maintenance quotidienne et des SDK clients pour une intégration simple avec vos applications web ou mobiles. Dans ce guide, nous explorons les APIs pour les health checks, le realtime, les backups, les logs et les settings. Nous couvrons aussi les SDK JavaScript et Dart, avec un focus sur la persistance d'authentification et les uploads mobiles. Ces outils sont essentiels pour les startups et PME qui cherchent une solution légère et scalable, sans complexité inutile.

Ce tutoriel s'adresse aux débutants : nous expliquons chaque concept pas à pas, avec des exemples de code directement utilisables. Tous les détails proviennent de la documentation officielle de PocketBase, mise à jour en 2025. Prêt ? Commençons par les bases des APIs utilitaires.

1. Health Check : Vérifiez l'État de Votre Serveur en Un Coup d'Œil

Le health check est l'API la plus simple de PocketBase. Elle permet de confirmer que votre serveur fonctionne correctement, sans authentification requise. C'est idéal pour les scripts de monitoring ou les déploiements automatisés dans une startup.

L'Endpoint Principal

Utilisez GET /api/health ou HEAD /api/health. La méthode HEAD est plus légère car elle ne renvoie pas le corps de la réponse, juste le code de statut.

Paramètres de Requête :

  • fields (optionnel, string) : Spécifiez les champs à inclure, séparés par des virgules. Par exemple, ?fields=data.canBackup pour ne récupérer que ce champ. Vous pouvez utiliser des modificateurs comme :excerpt(100, true) pour tronquer des chaînes longues avec des points de suspension.

Réponse (200 OK) :

{
  "status": 200,
  "message": "API is healthy.",
  "data": {
    "canBackup": false
  }
}
  • status : Code HTTP (toujours 200 si tout va bien).
  • message : Message lisible ("API is healthy.").
  • data : Objet avec des infos spécifiques, comme canBackup (booléen indiquant si les backups sont activés).

Exemples Pratiques

Pour un appel basique en JavaScript (sans SDK) :

fetch('http://127.0.0.1:8090/api/health')
  .then(response => response.json())
  .then(data => console.log(data.message)); // "API is healthy."

Avec HEAD pour un monitoring rapide :

fetch('http://127.0.0.1:8090/api/health', { method: 'HEAD' })
  .then(response => {
    if (response.ok) {
      console.log('Serveur opérationnel');
    }
  });

Bonnes Pratiques :

  • Intégrez-le dans vos outils CI/CD ou des services comme UptimeRobot pour alerter en cas de panne.
  • Utilisez fields pour réduire la taille des réponses en production.
  • Pas d'authentification : parfait pour des checks publics, mais surveillez les abus potentiels avec des rate limits.

Ce endpoint est minimaliste, mais extensible. En 2025, il reste inchangé, avec un focus sur la simplicité pour les PME qui n'ont pas besoin de métriques avancées.

2. Realtime avec SSE : Mises à Jour en Temps Réel Sans Effort

PocketBase utilise Server-Sent Events (SSE) pour le realtime, ce qui signifie des notifications push pour les créations, mises à jour ou suppressions de records. C'est natif et efficace pour des apps collaboratives, comme un dashboard partagé dans une startup.

Les Endpoints Clés

  • GET /api/realtime : Établit la connexion SSE. Le serveur renvoie immédiatement un événement PB_CONNECT avec un clientId unique.
  • POST /api/realtime : Définit les abonnements. Remplace les précédents et gère l'authentification.

Paramètres pour POST :

  • clientId (requis, string) : L'ID de la connexion SSE.
  • subscriptions (optionnel, array de strings) : Formats comme collection_name (toute la collection) ou collection_name/record_id (un record spécifique). Ajoutez ?options={"query":{"filter":"title ~ 'test'"},"headers":{"x-custom":"value"}} pour des filtres ou headers custom.

Réponses :

  • 204 : Succès (pas de corps).
  • 400 : Erreur de validation (ex. : clientId manquant).
  • 403 : Auth mismatch.
  • 404 : clientId invalide.

L'auth se fait via l'en-tête Authorization sur le POST. Les règles d'accès (ListRule ou ViewRule) s'appliquent aux abonnements.

Événements SSE

  • PB_CONNECT : Connexion établie.
  • Événements pour create, update, delete : Avec action et record (le record modifié).

Timeout : 5 minutes d'inactivité, puis déconnexion automatique (reconnexion si le client est actif).

Exemples avec SDK JavaScript

Initialisez et abonnez-vous :

import PocketBase from 'pocketbase';
const pb = new PocketBase('http://127.0.0.1:8090');

// Auth (optionnel, mais recommandé)
await pb.collection('users').authWithPassword('[email protected]', '1234567890');

// Abonnement à toute la collection
pb.collection('example').subscribe('*', (e) => {
  console.log(e.action, e.record); // ex. : "update", { id: "...", title: "Nouveau titre" }
}, { expand: 'relField' }); // Options pour expansions

// Abonnement à un record spécifique
pb.collection('example').subscribe('RECORD_ID', (e) => {
  console.log(e.record);
});

// Désabonnement
pb.collection('example').unsubscribe('RECORD_ID');
pb.collection('example').unsubscribe(); // Tout pour la collection

Pour Dart (Flutter) :

import 'package:pocketbase/pocketbase.dart';
final pb = PocketBase('http://127.0.0.1:8090');

await pb.collection('users').authWithPassword('[email protected]', '1234567890');

pb.collection('example').subscribe('*', (e) {
  print(e.action);
  print(e.record);
});

pb.collection('example').unsubscribe();

Bonnes Pratiques :

  • Utilisez toujours les SDK pour gérer les reconnexions automatiquement.
  • Testez les règles d'accès : un abonnement à une collection vérifie ListRule.
  • Pour les mobiles, polyfill EventSource (voir section SDK).

En 2025, SSE reste le choix par défaut pour sa simplicité, sans besoin de WebSockets complexes.

3. Backups Automatisés : Sauvegardez Vos Données Sans Stress

Les backups protègent vos données critiques. L'API gère la liste, création, upload, suppression, restauration et téléchargement. Réservé aux superusers, avec verrouillage contre les opérations concurrentes.

Endpoints Principaux

  • GET /api/backups : Liste les backups (avec fields, sort, filter).
  • POST /api/backups : Crée un backup (nom optionnel, format pb_backup_YYYYMMDDHHMMSS.zip).
  • POST /api/backups/upload : Upload un ZIP (multipart/form-data, MIME application/zip).
  • DELETE /api/backups/{key} : Supprime un backup.
  • POST /api/backups/{key}/restore : Restaure (redémarre le serveur).
  • GET /api/backups/{key} : Télécharge (avec token pour sécurité).

Réponses Exemples (liste) :

[
  {
    "key": "pb_backup_20230519162514.zip",
    "modified": "2023-05-19T16:25:57.542Z",
    "size": 251316185
  }
]

Erreurs : 400 (concurrence), 401/403 (auth), 404 (non trouvé).

Pas d'intégration S3 directe dans l'API, mais configurable via settings (voir section suivante) pour stocker les backups sur S3.

Exemples avec SDK

JavaScript :

import PocketBase from 'pocketbase';
const pb = new PocketBase('http://127.0.0.1:8090');

// Auth superuser
await pb.collection('_superusers').authWithPassword('[email protected]', 'secret');

// Créer
await pb.backups.create('mon_backup.zip');

// Lister
const backups = await pb.backups.getFullList();

// Restaurer
await pb.backups.restore('mon_backup.zip');

// Télécharger (avec token)
const token = await pb.files.getToken();
const url = pb.backups.getDownloadUrl(token, 'mon_backup.zip');

Dart similaire :

await pb.collection('_superusers').authWithPassword('[email protected]', 'secret');
await pb.backups.create('mon_backup.zip');
final backups = await pb.backups.getFullList();
await pb.backups.restore('mon_backup.zip');

Pour l'upload :

await pb.backups.upload({ file: new Blob([/* ZIP bytes */]) });

Bonnes Pratiques :

  • Activez les backups cron via settings pour l'automatisation (quotidien, garder 3 max).
  • Testez les restaurations en dev avant prod.
  • Utilisez des tokens pour les downloads sécurisés.

Pour les PME, c'est un gain de temps : un backup complet en une ligne de code.

4. Logs et Settings API : Surveillez et Configurez Votre Backend

Logs : Analysez l'Activité de Votre App

Accès superuser seulement. Endpoints pour lister, voir un log, et stats.

  • GET /api/logs : Liste paginée (page, perPage, sort, filter, fields).
  • GET /api/logs/{id} : Un log spécifique.
  • GET /api/logs/stats : Stats horaires agrégées.

Filtres : Puissants, ex. data.status >= 400 && (data.url ~ 'api' || level > 0).

Réponse Liste :

{
  "page": 1,
  "perPage": 20,
  "totalItems": 2,
  "items": [
    {
      "id": "ai5z3aoed6809au",
      "created": "2024-10-27T09:28:19.524Z",
      "message": "GET /api/collections/...",
      "level": 0,
      "data": {
        "method": "GET",
        "url": "/api/...",
        "status": 200,
        "execTime": 2.392327,
        "userIP": "127.0.0.1"
      }
    }
  ]
}

Exemple JS :

const logs = await pb.logs.getList(1, 20, { filter: 'data.status >= 400' });
const oneLog = await pb.logs.getOne('LOG_ID');
const stats = await pb.logs.getStats({ filter: 'level > 0' });

Bonnes Pratiques : Filtrez par statut pour debugger les erreurs. Gardez max 7 jours via settings.

Settings API : Centralisez Vos Configurations

  • GET /api/settings : Récupère tout (secrets masqués).
  • PATCH /api/settings : Met à jour en bulk (meta, smtp, s3, etc.).
  • POST /api/settings/test/s3 : Teste S3 (storage ou backups).
  • POST /api/settings/test/email : Envoie un email test.
  • POST /api/settings/apple/generate-client-secret : Génère secret OAuth Apple.

Champs Clés :

  • SMTP : enabled, host, port, username, password, tls.
  • S3 : enabled, bucket, region, accessKey, secret (pour fichiers/backups).
  • Meta : appName, appUrl, senderName.
  • Logs : maxDays: 7, minLevel: 0.
  • Backups : cron: "0 0 * * *", cronMaxKeep: 3, s3 nested.
  • RateLimits : Règles comme { label: "*:auth", maxRequests: 2, duration: 3 }.

Exemple Update JS :

await pb.settings.update({
  meta: { appName: 'Ma Startup', appUrl: 'https://monapp.com' },
  smtp: { enabled: true, host: 'smtp.gmail.com', port: 587, username: '[email protected]', password: 'apppass', tls: true }
});

Test S3 :

await pb.settings.testS3('backups'); // 204 si OK

Bonnes Pratiques : Testez SMTP et S3 après config. Activez rate limits pour la sécurité. Pour backups S3, configurez dans backups.s3.

Ces APIs centralisent la gestion, parfait pour une équipe réduite en PME.

5. SDK JavaScript et Dart : Les Outils pour Vos Frontends

Les SDK clients simplifient l'interaction avec les APIs. Un seul instance globale par app.

Installation et Initialisation

JavaScript (npm) :

npm install pocketbase

Pour React Native : Ajoutez react-native-sse et @react-native-async-storage/async-storage.

Init basique :

import PocketBase from 'pocketbase';
const pb = new PocketBase('http://127.0.0.1:8090');

Dart (Flutter) :

dependencies:
  pocketbase: ^0.18.0
  shared_preferences: ^2.2.2

Init :

import 'package:pocketbase/pocketbase.dart';
final pb = PocketBase('http://127.0.0.1:8090');

Méthodes core : create(), getList(), update(), delete(), authWithPassword().

Comparaison

Les deux SDKs sont similaires : même API, support CRUD, realtime, fichiers. JS pour web/mobile, Dart pour Flutter cross-platform.

6. Auth Persistance et Uploads Mobile : Intégrez Sans Frottements

Persistance d'Auth

Sur mobile, stockez le token pour les redémarrages.

JS React Native :

import eventsource from 'react-native-sse';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { AsyncAuthStore } from 'pocketbase';

global.EventSource = eventsource;

const store = new AsyncAuthStore({
  save: async (data) => AsyncStorage.setItem('pb_auth', data),
  initial: await AsyncStorage.getItem('pb_auth'),
});

const pb = new PocketBase('http://127.0.0.1:8090', store);
await pb.collection('users').authWithPassword('[email protected]', 'pass');

Dart Flutter :

import 'package:shared_preferences/shared_preferences.dart';
final prefs = await SharedPreferences.getInstance();
final store = AsyncAuthStore(
  save: (data) => prefs.setString('pb_auth', data),
  initial: prefs.getString('pb_auth'),
);
final pb = PocketBase('http://127.0.0.1:8090', authStore: store);
await pb.collection('users').authWithPassword('[email protected]', 'pass');

Uploads Fichiers Mobile

FormData diffère sur mobile.

JS React Native :

const data = new FormData();
const imageUri = 'path/to/image.jpg'; // De image picker

if (Platform.OS === 'web') {
  const blob = await (await fetch(imageUri)).blob();
  data.append('avatar', blob);
} else {
  data.append('avatar', {
    uri: imageUri,
    type: 'image/jpeg',
    name: 'image.jpg',
  });
}

await pb.collection('users').update('USER_ID', data);

Bonnes Pratiques : Polyfill EventSource pour realtime mobile. Évitez SSR avec PocketBase (sécurité et perf) ; préférez SPAs ou un superuser client serveur-side.

Exemple Superuser Client (Node) :

const pb = new PocketBase('https://example.com');
pb.autoCancellation(false);
await pb.collection('_superusers').authWithPassword('admin', 'pass');

Conclusion : Lancez Votre App en Quelques Lignes

Avec ces APIs et SDK, PocketBase gère le monitoring (health, logs), la résilience (backups, settings) et l'intégration client (realtime, auth, uploads). Pour une startup, c'est du plug-and-play : configurez S3 pour backups auto, abonnez-vous au realtime pour des updates live, et persistez l'auth sur mobile.

Testez en local, puis déployez. Si vous avez des questions, la doc officielle est votre meilleur allié. Prêt à scaler ?

Partager Partager Partager Partager Partager Email

Lire la suite