Initial commit

2025-11-30 09:06:02 +08:00
commit 02cab85880
53 changed files with 12367 additions and 0 deletions
--- a/skills/pocketbase/references/core/collections.md
+++ b/skills/pocketbase/references/core/collections.md
@@ -0,0 +1,544 @@
+# Collections in PocketBase
+
+## Overview
+
+Collections are the fundamental data structures in PocketBase, similar to tables in a relational database. They define the schema and behavior of your data.
+
+## Collection Types
+
+### 1. Base Collection
+Flexible collection with custom schema. Used for:
+- Posts, articles, products
+- Comments, messages
+- Any application-specific data
+
+**Characteristics:**
+- No built-in authentication
+- Custom fields only
+- Full CRUD operations
+- Can be accessed via REST API
+
+### 2. Auth Collection
+Special collection for user accounts. Used for:
+- User registration and login
+- User profiles and settings
+- Authentication workflows
+
+**Characteristics:**
+- Built-in auth fields (`email`, `password`, `emailVisibility`, `verified`)
+- Automatic user ID tracking on creation
+- OAuth2 support
+- Password management
+- Email verification
+- Password reset functionality
+
+### 3. View Collection
+Read-only collection based on SQL views. Used for:
+- Complex joins and aggregations
+- Denormalized data for performance
+- Reporting and analytics
+- Dashboard metrics
+
+**Characteristics:**
+- Read-only (no create, update, delete)
+- Defined via SQL query
+- Auto-updates when source data changes
+- Useful for performance optimization
+
+## Creating Collections
+
+### Via Admin UI
+1. Navigate to Collections
+2. Click "New Collection"
+3. Choose collection type
+4. Configure name and schema
+5. Save
+
+### Via API
+```javascript
+const collection = await pb.collections.create({
+  name: 'products',
+  type: 'base',
+  schema: [
+    {
+      name: 'name',
+      type: 'text',
+      required: true
+    },
+    {
+      name: 'price',
+      type: 'number',
+      required: true
+    }
+  ]
+});
+```
+
+## Schema Field Types
+
+### Text
+Short to medium text strings.
+
+```json
+{
+  "name": "title",
+  "type": "text",
+  "options": {
+    "min": null,
+    "max": null,
+    "pattern": ""
+  }
+}
+```
+
+**Options:**
+- `min` - Minimum character length
+- `max` - Maximum character length
+- `pattern` - Regex pattern for validation
+
+### Number
+Integer or decimal numbers.
+
+```json
+{
+  "name": "price",
+  "type": "number",
+  "options": {
+    "min": null,
+    "max": null,
+    "noDecimal": false
+  }
+}
+```
+
+**Options:**
+- `min` - Minimum value
+- `max` - Maximum value
+- `noDecimal` - Allow only integers
+
+### Email
+Email addresses with validation.
+
+```json
+{
+  "name": "contact_email",
+  "type": "email"
+}
+```
+
+### URL
+URLs with validation.
+
+```json
+{
+  "name": "website",
+  "type": "url"
+}
+```
+
+### Date
+Date and time values.
+
+```json
+{
+  "name": "published_date",
+  "type": "date",
+  "options": {
+    "min": "",
+    "max": ""
+  }
+}
+```
+
+### Boolean
+True/false values.
+
+```json
+{
+  "name": "is_published",
+  "type": "bool"
+}
+```
+
+### JSON
+Arbitrary JSON data.
+
+```json
+{
+  "name": "metadata",
+  "type": "json"
+}
+```
+
+### Relation
+Links to records in other collections.
+
+```json
+{
+  "name": "author",
+  "type": "relation",
+  "options": {
+    "collectionId": "AUTH_COLLECTION_ID",
+    "cascadeDelete": false,
+    "maxSelect": 1,
+    "displayFields": null
+  }
+}
+```
+
+**Options:**
+- `collectionId` - Target collection ID
+- `cascadeDelete` - Delete related records when this is deleted
+- `maxSelect` - Maximum number of related records (1 or null for unlimited)
+- `displayFields` - Fields to display when showing the relation
+
+### File
+File uploads and storage.
+
+```json
+{
+  "name": "avatar",
+  "type": "file",
+  "options": {
+    "maxSelect": 1,
+    "maxSize": 5242880,
+    "mimeTypes": ["image/*"],
+    "thumbs": ["100x100", "300x300"]
+  }
+}
+```
+
+**Options:**
+- `maxSelect` - Maximum number of files
+- `maxSize` - Maximum file size in bytes
+- `mimeTypes` - Allowed MIME types (array or ["*"] for all)
+- `thumbs` - Auto-generate image thumbnails at specified sizes
+
+### Select
+Dropdown with predefined options.
+
+```json
+{
+  "name": "status",
+  "type": "select",
+  "options": {
+    "values": ["draft", "published", "archived"],
+    "maxSelect": 1
+  }
+}
+```
+
+**Options:**
+- `values` - Array of allowed values
+- `maxSelect` - Maximum selections (1 for single select, null for multi-select)
+
+### Autodate
+Automatically populated dates.
+
+```json
+{
+  "name": "created",
+  "type": "autodate",
+  "options": {
+    "onCreate": true,
+    "onUpdate": false
+  }
+}
+```
+
+**Options:**
+- `onCreate` - Set on record creation
+- `onUpdate` - Update on record modification
+
+### Username
+Unique usernames (valid only for auth collections).
+
+```json
+{
+  "name": "username",
+  "type": "username",
+  "options": {
+    "min": 3,
+    "max": null
+  }
+}
+```
+
+## Collection Rules
+
+Rules control who can access, create, update, and delete records.
+
+### Types of Rules
+
+1. **List Rule** - Who can list/view multiple records
+2. **View Rule** - Who can view individual records
+3. **Create Rule** - Who can create new records
+4. **Update Rule** - Who can modify records
+5. **Delete Rule** - Who can delete records
+
+### Rule Syntax
+
+**Authenticated Users Only**
+```
+@request.auth.id != ""
+```
+
+**Owner-Based Access**
+```
+user_id = @request.auth.id
+```
+
+**Role-Based Access**
+```
+@request.auth.role = 'admin'
+```
+
+**Conditional Access**
+```
+status = 'published' || @request.auth.id = author_id
+```
+
+**Complex Conditions**
+```
+@request.auth.role = 'moderator' && @request.auth.verified = true
+```
+
+### Special Variables
+
+- `@request.auth` - Current authenticated user
+- `@request.auth.id` - User ID
+- `@request.auth.email` - User email
+- `@request.auth.role` - User role
+- `@request.auth.verified` - Email verification status
+
+### Rule Examples
+
+**Public Blog Posts**
+```
+List Rule: status = 'published'
+View Rule: status = 'published'
+Create Rule: @request.auth.id != ''
+Update Rule: author_id = @request.auth.id
+Delete Rule: author_id = @request.auth.id
+```
+
+**Private User Data**
+```
+List Rule: user_id = @request.auth.id
+View Rule: user_id = @request.auth.id
+Create Rule: @request.auth.id != ''
+Update Rule: user_id = @request.auth.id
+Delete Rule: user_id = @request.auth.id
+```
+
+**Admin-Only Content**
+```
+List Rule: @request.auth.role = 'admin'
+View Rule: @request.auth.role = 'admin'
+Create Rule: @request.auth.role = 'admin'
+Update Rule: @request.auth.role = 'admin'
+Delete Rule: @request.auth.role = 'admin'
+```
+
+**Moderated Comments**
+```
+List Rule: status = 'approved' || author_id = @request.auth.id
+View Rule: status = 'approved' || author_id = @request.auth.id
+Create Rule: @request.auth.id != ''
+Update Rule: author_id = @request.auth.id
+Delete Rule: author_id = @request.auth.id || @request.auth.role = 'moderator'
+```
+
+## Collection Indexes
+
+Indexes improve query performance on frequently searched or sorted fields.
+
+### Creating Indexes
+
+**Via Admin UI**
+1. Go to collection settings
+2. Click "Indexes" tab
+3. Click "New Index"
+4. Select fields to index
+5. Save
+
+**Via API**
+```javascript
+await pb.collections.update('COLLECTION_ID', {
+  indexes: [
+    'CREATE INDEX idx_posts_status ON posts(status)',
+    'CREATE INDEX idx_posts_author ON posts(author_id)',
+    'CREATE INDEX idx_posts_created ON posts(created)'
+  ]
+});
+```
+
+### Index Best Practices
+
+1. **Index fields used in filters**
+   ```sql
+   CREATE INDEX idx_posts_status ON posts(status)
+   ```
+
+2. **Index fields used in sorts**
+   ```sql
+   CREATE INDEX idx_posts_created ON posts(created)
+   ```
+
+3. **Index foreign keys (relations)**
+   ```sql
+   CREATE INDEX idx_comments_post ON comments(post_id)
+   ```
+
+4. **Composite indexes for multi-field queries**
+   ```sql
+   CREATE INDEX idx_posts_status_created ON posts(status, created)
+   ```
+
+5. **Don't over-index** - Each index adds overhead to writes
+
+## Collection Options
+
+### General Options
+
+- **Name** - Collection identifier (used in API endpoints)
+- **Type** - base, auth, or view
+- **System collection** - Built-in collections (users, _pb_users_auth_)
+- **List encryption** - Encrypt data in list views
+
+### API Options
+
+- **API keys** - Manage read/write API keys
+- **CRUD endpoints** - Enable/disable specific endpoints
+- **File access** - Configure public/private file access
+
+### Auth Collection Options
+
+- **Min password length** - Minimum password requirements
+- **Password constraints** - Require uppercase, numbers, symbols
+- **Email verification** - Require email confirmation
+- **OAuth2 providers** - Configure social login
+
+## Managing Collections
+
+### List Collections
+```javascript
+const collections = await pb.collections.getList(1, 50);
+```
+
+### Get Collection
+```javascript
+const collection = await pb.collections.getOne('COLLECTION_ID');
+```
+
+### Update Collection
+```javascript
+const updated = await pb.collections.update('COLLECTION_ID', {
+  name: 'new_name',
+  schema: [
+    // updated schema
+  ]
+});
+```
+
+### Delete Collection
+```javascript
+await pb.collections.delete('COLLECTION_ID');
+```
+
+### Export Collection Schema
+```javascript
+const collection = await pb.collections.getOne('COLLECTION_ID');
+const schemaJSON = JSON.stringify(collection.schema, null, 2);
+```
+
+## Best Practices
+
+1. **Plan Schema Carefully**
+   - Design before implementing
+   - Consider future needs
+   - Use appropriate field types
+
+2. **Use Relations Wisely**
+   - Normalize data appropriately
+   - Set cascadeDelete when appropriate
+   - Consider performance impact
+
+3. **Set Rules Early**
+   - Security from the start
+   - Test rules thoroughly
+   - Document rule logic
+
+4. **Index Strategically**
+   - Profile slow queries
+   - Index commonly filtered fields
+   - Avoid over-indexing
+
+5. **Use Auth Collections for Users**
+   - Built-in auth features
+   - OAuth2 support
+   - Password management
+
+6. **Use Views for Complex Queries**
+   - Improve performance
+   - Simplify frontend code
+   - Pre-compute expensive joins
+
+## Common Patterns
+
+### Blog/Post System
+```
+Collections:
+- posts (base) - title, content, author, status, published_date
+- categories (base) - name, slug, description
+- tags (base) - name, slug
+- posts_tags (base) - post_id, tag_id (relation join)
+```
+
+### E-commerce
+```
+Collections:
+- products (base) - name, price, description, category, stock
+- orders (base) - user, items, total, status
+- order_items (base) - order, product, quantity, price
+- categories (base) - name, parent (self-relation)
+```
+
+### Social Network
+```
+Collections:
+- posts (base) - author, content, media, created, visibility
+- likes (base) - post, user (unique constraint)
+- follows (base) - follower, following (unique constraint)
+- users (auth) - built-in auth + profile fields
+```
+
+## Troubleshooting
+
+**Collection not showing data**
+- Check listRule
+- Verify user permissions
+- Check if view collection is properly configured
+
+**Slow queries**
+- Add database indexes
+- Optimize rule conditions
+- Use views for complex joins
+
+**Can't create records**
+- Check createRule
+- Verify required fields
+- Ensure user is authenticated
+
+**File uploads failing**
+- Check maxSize and mimeTypes
+- Verify file field options
+- Check user has create permissions
+
+## Related Topics
+
+- [Authentication](authentication.md) - User management
+- [API Rules & Filters](api_rules_filters.md) - Security rules syntax
+- [Working with Relations](working_with_relations.md) - Field relationships
+- [Files Handling](files_handling.md) - File uploads and storage
+- [Schema Templates](../templates/schema_templates.md) - Pre-built schemas