PB Collections Smart

A comprehensive skill for PocketBase collection and schema design — covering collection types, field definitions, relation modeling, auth collection configuration, and schema migration patterns for PocketBase applications.

When to Use This Skill

Choose PB Collections Smart when you need to:

• Design collection schemas for a new PocketBase application
• Configure auth collections with custom fields
• Model relationships between collections (one-to-many, many-to-many)
• Plan schema migrations for evolving applications
• Set up collection-level settings (indexes, unique constraints)

Consider alternatives when:

• You need API rules and security (use a PB API rules skill)
• You need deployment configuration (use a PB deploy skill)
• You need general database design (use a database modeling skill)

Quick Start

Copy
// Collection schema definition (migration format)
// migrations/create_collections.js

migrate((db) => {
  // Users collection (auth type)
  const users = new Collection({
    name: "users",
    type: "auth",
    schema: [
      { name: "name", type: "text", required: true },
      { name: "avatar", type: "file", options: { maxSelect: 1, maxSize: 5242880 } },
      { name: "role", type: "select", options: { values: ["user", "admin", "moderator"] } },
      { name: "bio", type: "text", options: { maxLength: 500 } },
    ],
  });

  // Posts collection (base type)
  const posts = new Collection({
    name: "posts",
    type: "base",
    schema: [
      { name: "title", type: "text", required: true },
      { name: "content", type: "editor" },
      { name: "author", type: "relation", options: { collectionId: users.id, maxSelect: 1 } },
      { name: "tags", type: "select", options: { values: ["tech", "design", "business"], maxSelect: 5 } },
      { name: "status", type: "select", options: { values: ["draft", "published", "archived"] } },
      { name: "published_at", type: "date" },
      { name: "cover_image", type: "file", options: { maxSelect: 1 } },
    ],
  });

  db.save(users);
  db.save(posts);
});

Core Concepts

Collection Types

Type	System Fields	Use Case
base	id, created, updated	Standard data collections
auth	id, created, updated, email, emailVisibility, username, verified	User accounts
view	Depends on source query	Read-only computed views

Field Types

Field Type	Purpose	Options
text	Short text strings	minLength, maxLength, pattern
number	Numeric values	min, max, noDecimal
bool	True/false values	—
email	Email addresses	exceptDomains, onlyDomains
url	Web URLs	exceptDomains, onlyDomains
date	Date and time	min, max
select	Single/multi select	values, maxSelect
file	File uploads	maxSelect, maxSize, mimeTypes
relation	Link to another collection	collectionId, maxSelect
json	Arbitrary JSON data	maxSize
editor	Rich text (HTML)	convertUrls

Relationship Patterns

Copy
// One-to-Many: Author → Posts
// Posts collection has:
{ name: "author", type: "relation", options: { collectionId: "users", maxSelect: 1 } }

// Many-to-Many: Posts ↔ Tags (via junction)
// Option A: Multi-select relation field
{ name: "tags", type: "relation", options: { collectionId: "tags", maxSelect: 99 } }

// Option B: Junction collection
const post_tags = new Collection({
  name: "post_tags",
  type: "base",
  schema: [
    { name: "post", type: "relation", options: { collectionId: "posts", maxSelect: 1 } },
    { name: "tag", type: "relation", options: { collectionId: "tags", maxSelect: 1 } },
  ],
});

// Self-referential: Comments → Parent Comment
{ name: "parent", type: "relation", options: { collectionId: "comments", maxSelect: 1 } }

// One-to-One: User → Profile
// Profile collection:
{
  name: "user",
  type: "relation",
  options: { collectionId: "users", maxSelect: 1 },
  unique: true  // Enforces one-to-one
}

Auth Collection Configuration

Copy
// Custom auth collection with additional fields
const users = new Collection({
  name: "users",
  type: "auth",
  options: {
    allowEmailAuth: true,
    allowUsernameAuth: true,
    allowOAuth2Auth: true,
    minPasswordLength: 8,
    requireEmail: true,
    onlyVerified: false,  // Set true to require email verification
  },
  schema: [
    { name: "name", type: "text", required: true },
    { name: "avatar", type: "file", options: {
      maxSelect: 1,
      maxSize: 5242880,
      mimeTypes: ["image/jpeg", "image/png", "image/webp"],
    }},
    { name: "role", type: "select", options: {
      values: ["user", "moderator", "admin"],
      maxSelect: 1,
    }},
    { name: "organization", type: "relation", options: {
      collectionId: "organizations",
      maxSelect: 1,
    }},
  ],
});

Configuration

Parameter	Description	Example
collection_type	Type of collection	"base" / "auth" / "view"
collection_name	Name of the collection	"posts"
auth_methods	Enabled auth methods (auth type)	["email", "oauth2"]
indexes	Fields to index	["title", "author"]
unique_fields	Fields with unique constraints	["slug", "email"]

Best Practices

1. Name collections with plural nouns — Use posts, users, comments, not post, user, comment. PocketBase auto-generates API endpoints from collection names, and plural paths (/api/collections/posts/records) read more naturally.

2. Use select fields instead of boolean flags for statuses — status: select("draft", "published", "archived") is more flexible than is_published: bool. Adding new states later is trivial with select but requires schema changes with booleans.

3. Set maxSelect: 1 for single relations explicitly — Relation fields default to multi-select. A post should have exactly one author, not an array. Always set maxSelect: 1 for one-to-many relationships on the "many" side.

4. Use view collections for computed data — Instead of duplicating data or adding computed fields, create view collections with SQL queries that join and aggregate data. Views stay in sync automatically and don't consume storage.

5. Plan your file field configuration upfront — Set mimeTypes to restrict uploads to expected file types, maxSize to prevent oversized uploads, and maxSelect for single vs. multiple files. Retroactively restricting these after data exists is more complex.

Common Issues

Relation field references deleted collection — If you delete a collection that other collections reference via relation fields, those relation fields become orphaned. Always check for relation dependencies before deleting a collection. PocketBase's admin UI warns about this, but migrations may not.

Auth collection email settings conflict — Setting requireEmail: true and allowUsernameAuth: true without allowEmailAuth: true creates confusion. Users can register with a username but must provide an email they can't use to log in. Ensure your auth configuration is internally consistent.

View collections can't be written to — View collections are read-only computed queries. Attempting to create, update, or delete records in a view collection returns an error. If you need writable computed data, use base collections with server-side hooks that maintain the computed values.