Les Collections PocketBase expliquées simplement – Guide 2026

Introduction

Dans PocketBase, les collections sont au cœur de tout projet. Elles fonctionnent comme des tables dans une base de données traditionnelle, mais avec une simplicité qui les rend accessibles même aux débutants. Chaque collection stocke des enregistrements, qui sont simplement des lignes de données. Par exemple, une collection "produits" pourrait contenir des enregistrements pour chaque article de votre boutique en ligne.

PocketBase utilise SQLite comme base de données intégrée, ce qui signifie que tout est géré dans un seul fichier. Les collections sont créées automatiquement sous forme de tables SQL basées sur leur nom et leurs champs (les colonnes). Vous pouvez les gérer via l'interface d'administration (le Dashboard), les API web ou même par code en Go ou JavaScript.

Pour une petite entreprise ou une startup, les collections permettent de structurer rapidement vos données sans vous noyer dans des configurations complexes. Imaginez : en quelques clics, vous avez une table pour vos clients, une pour vos commandes, et tout est prêt pour une API REST automatique. Ce guide va vous expliquer pas à pas les bases, en partant de zéro, pour que vous puissiez coder votre première API sans stress.

Types de collections

PocketBase propose trois types principaux de collections, chacun adapté à un usage spécifique. Choisir le bon type dès le départ évite des complications plus tard.

Collections Base

C'est le type par défaut, et le plus polyvalent. Une collection Base sert à stocker n'importe quel type de données : articles de blog, produits d'e-commerce, événements d'un calendrier... Par exemple, pour une startup qui gère un catalogue de produits, une collection Base "produits" pourrait inclure des champs comme nom, prix et description.

Les collections Base supportent toutes les opérations : création, lecture, mise à jour et suppression d'enregistrements. Elles déclenchent aussi des événements en temps réel, ce qui est utile pour synchroniser des apps mobiles ou web en direct.

Collections Auth

Ces collections sont spécialisées pour la gestion des utilisateurs. Elles héritent de toutes les fonctionnalités d'une Base, mais ajoutent des champs système obligatoires comme email, password, verified (pour la vérification d'email) et tokenKey (pour les sessions JWT).

Vous ne pouvez pas renommer ou supprimer ces champs système, mais vous pouvez les configurer – par exemple, rendre l'email optionnel ou ajouter un champ pour les rôles. Une application peut avoir plusieurs collections Auth : une pour les clients, une pour les admins, etc. Cela permet des logins séparés et des permissions personnalisées.

Pour une SMB, c'est idéal pour un système de membres : vos employés se connectent via une collection Auth "staff", tandis que les clients utilisent une autre.

Collections View

Ces collections sont en lecture seule et génèrent leurs données via une requête SQL personnalisée. Elles sont parfaites pour des vues agrégées, comme un résumé de ventes mensuelles sans exposer la table brute.

Par exemple, pour afficher le nombre total de commentaires par post, vous pourriez créer une View avec cette requête SQL :

SELECT
    posts.id,
    posts.name,
    count(comments.id) as totalComments
FROM posts
LEFT JOIN comments ON comments.postId = posts.id
GROUP BY posts.id

Les Views n'acceptent pas de créations ou modifications directes, et elles ne supportent pas les événements en temps réel. C'est un outil puissant pour des dashboards analytiques dans une startup, sans alourdir votre base principale.

PocketBase gère automatiquement la création de ces types via l'interface ou les API. Commencez toujours par une Base pour tester, puis passez à Auth pour l'authentification et View pour les rapports.

Création et gestion via l'interface Admin (UI)

La beauté de PocketBase, c'est son Dashboard accessible à http://127.0.0.1:8090/_/ une fois le serveur lancé. C'est une interface web intuitive, sans installation supplémentaire, qui vous permet de créer et gérer les collections sans écrire une ligne de code.

Pour créer une collection :

1. Allez dans l'onglet "Collections".
2. Cliquez sur "New collection".
3. Donnez un nom (par exemple, "todos") et choisissez le type (Base par défaut).
4. Ajoutez des champs un par un (on en parle plus bas).
5. Configurez les règles d'accès si besoin.
6. Sauvegardez : PocketBase génère instantanément la table SQL et l'API correspondante.

La gestion quotidienne est tout aussi simple : listez les enregistrements, ajoutez-en de nouveaux via un formulaire, modifiez ou supprimez. Pour les Views, vous entrez directement la requête SQL dans un éditeur intégré, et un aperçu s'affiche pour valider.

Pour une petite entreprise, c'est un gain de temps énorme. Pas besoin de DBA ou d'outils externes comme phpMyAdmin – tout est dans le navigateur. Si vous êtes en équipe, les super-utilisateurs (admins) peuvent collaborer en temps réel sur les structures.

Notez que les API et les SDK (Go/JS) permettent aussi la création programmatique, mais pour débuter, restez sur l'UI.

Champs : Les briques de vos données

Les champs définissent la structure de vos enregistrements. Tous les champs (sauf JSON) sont non-nullables par défaut, avec une valeur "zéro" (chaîne vide, 0, false, etc.) si rien n'est fourni. Explorons les types principaux, avec des exemples adaptés à une startup.

Champs de base : Text, Number, Bool, Email, URL

• Text : Pour des chaînes de caractères. Options : longueur min/max, unique, pattern (regex pour validation). Exemple : un champ "nom" pour un produit. Vous pouvez activer l'autogénéré, comme pour un slug : si vous définissez un pattern "post-{id}-", PocketBase le remplit automatiquement.
• Number : Entiers ou décimaux. Supporte min/max et modificateurs comme +5 pour incrémenter. Parfait pour prix ou quantités : {"prix": 29.99}.
• Bool : True/false, défaut false. Utile pour "actif" ou "en stock".
• Email : Valide automatiquement les adresses. Exemple : champ "contact" dans une collection clients.
• URL : Pour liens web, avec validation intégrée.

Champs avancés : Date, Editor, Select

• Date : Format RFC3339 (ex. "2024-11-30T10:00:00Z"). Pour filtrer par jour, spécifiez l'heure complète : created >= '2024-11-30 00:00:00.000Z' && created <= '2024-11-30 23:59:59.999Z'. Utilisez AutoDate pour horodatages automatiques (created/updated).
• Editor : Stocke du HTML riche. Idéal pour descriptions de produits dans une boutique.
• Select : Énumérations. Single (une valeur) ou multiple (array). Modificateurs : + pour ajouter, - pour retirer. Exemple : rôles comme ["admin", "user"] dans une Auth.

Champs multimédias et relations : File, Relation

• File : Gère uploads. Single ou multiple (array de noms de fichiers). Les fichiers sont stockés localement ou sur S3 ; seul le nom va en DB. Modificateurs : + pour ajouter, - pour supprimer. Exemple : {"images+": new File(...)}. Pour une startup e-commerce, c'est essentiel pour photos de produits.
• Relation : Liens vers d'autres collections. Single (ID string) ou multiple (array d'IDs). Supporte expand pour charger les données liées. Modificateurs comme pour File. Exemple : un produit lié à une catégorie : {"categorie": "CAT_ID"}.

Autres champs : JSON, GeoPoint, AutoNumber

• JSON : Seul champ nullable, pour données flexibles (objets ou arrays). Utile pour métadonnées variables.
• GeoPoint : Coordonnées {lon: 12.34, lat: 56.78}. Défaut : Null Island (0,0). Parfait pour apps de livraison : record.set("position", {lon: 2.35, lat: 48.85}) en JS.
• AutoNumber : Compteurs automatiques, comme ID séquentiel pour factures.

Ajoutez des options comme required (obligatoire), unique (unicité), ou index (pour performances sur gros volumes). Pour une SMB, commencez avec 5-10 champs par collection pour éviter la surcharge.

Indexes et options avancées

Les indexes accélèrent les recherches sur les gros datasets – PocketBase les crée automatiquement sur les champs uniques ou relations. Vous pouvez en ajouter manuellement via l'UI pour des champs souvent filtrés, comme "date_creation".

Options communes :

• Min/Max : Pour numbers (ex. prix entre 0 et 1000) ou text (longueur 3-50).
• Pattern : Regex pour valider, ex. ^[a-zA-Z0-9]+$ pour slugs sans espaces.
• Autogenerate : Pour text, avec motifs comme "{counter}-{random}".

Ces options valident les données à l'entrée, évitant les erreurs. Dans une startup, indexez les champs de recherche (nom, email) dès le début pour scaler sans ralentir.

Règles d'accès et filtres : La sécurité de base

Sans règles, tout est public – dangereux pour une entreprise. Les règles sont des expressions simples évaluées à chaque opération (list, view, create...).

Bases :

• @request.auth.id : ID de l'utilisateur connecté.
• Opérateurs : =, !=, &&, ||, parenthèses.

Exemples :

• Seulement l'auteur voit : author = @request.auth.id.
• Par rôle : Ajoutez un select "role" en Auth, puis @request.auth.role = "staff".
• Mixte : @request.auth.id != "" && (role = "admin" || owner = @request.auth.id).

Pour relations imbriquées : relField.subRel.author = @request.auth.id. Activez "Manage" pour déléguer la gestion complète.

Filtres dans les queries : Utilisez-les pour des recherches comme name ~ "pocket" (LIKE) ou distance(geo, {lon:2, lat:48}) < 10km.

Configurez-les dans l'UI par action (Create, Update...). Pour débutants, commencez par des règles ownership simples.

Exemples réels pour SMB et startups

Exemple 1 : Collection produits pour e-commerce

Créez une Base "produits" :

• Champs : name (text, required), price (number, min=0), images (file, multiple), category (relation vers "categories").
• Règle list : @request.auth.id != "" (seulement connectés voient).
• Index sur name et price.

Via UI : Ajoutez un enregistrement avec upload photo. API : POST /api/collections/produits/records avec JSON et File.

Pour une startup, cela donne une API prête pour votre app Shopify-like.

Exemple 2 : Auth pour utilisateurs clients

Collection Auth "clients" :

• Champs système + phone (text), preferences (JSON).
• Règle create : email ~ "@" (validation basique).

Login via /api/collections/clients/auth-with-password. Ajoutez MFA plus tard.

Exemple 3 : View pour dashboard ventes

View "ventes_mensuelles" :
SQL : SELECT month(order_date) as mois, sum(total) as chiffre FROM orders GROUP BY mois.

Affichez dans un frontend pour suivre les KPI sans queries complexes.

Ces exemples montrent comment PocketBase s'adapte à des besoins réels sans boilerplate.

Conclusion

Les collections sont la fondation de PocketBase : avec Base pour les données brutes, Auth pour les users et View pour les insights, vous structurez tout efficacement. Via l'UI, ajoutez champs et règles en minutes, et votre API est live.

Pour une petite entreprise ou startup, c'est l'outil parfait pour prototyper vite sans équipe dev massive. Testez avec un projet simple, comme un CRUD de tâches, et passez à l'auth. Prochain guide : manipuler les records via API.