Fields reference

Complete guide to all field types available in PocketBase collections

Fields define the structure and validation rules for data in your PocketBase collections. Each field type is optimized for specific data formats and use cases.

Common field properties

All field types share these core properties:

type Field interface {
    Name   string  // Unique field name (used in API)
    Id     string  // Stable identifier (auto-generated)
    System bool    // System fields cannot be renamed/removed
    Hidden bool    // Hidden fields are excluded from API responses
}

Additional common properties

Most fields also support:

• Presentable - Hints the dashboard to use this field in record previews
• Required - Makes the field value mandatory (non-empty)

Field IDs are automatically generated when you add fields to a collection. They ensure stability even if you rename the field.

Text field

Stores string values with optional validation constraints.

&core.TextField{
    Name:     "title",
    Required: true,
    Min:      3,
    Max:      200,
    Pattern:  "^[a-zA-Z0-9 ]+$",
}

Properties

• Min - Minimum character length (0 = no limit)
• Max - Maximum character length (0 = default 5000)
• Pattern - Regular expression for validation
• AutogeneratePattern - Regex pattern for generating random values
• PrimaryKey - Mark as collection primary key (only for id field)

Special modifiers

// Autogenerate with prefix
record.Set("slug:autogenerate", "post-")  // "post-abc123xyz"

Examples

Username

&core.TextField{
    Name:     "username",
    Required: true,
    Min:      3,
    Max:      30,
    Pattern:  "^[a-zA-Z0-9_]+$",
}

Slug

&core.TextField{
    Name:                "slug",
    Required:            true,
    Pattern:             "^[a-z0-9-]+$",
    AutogeneratePattern: "[a-z0-9]{10}",
}

Short description

&core.TextField{
    Name: "tagline",
    Max:  140,
}

Number field

Stores numeric values (stored as float64 internally).

&core.NumberField{
    Name:     "price",
    Required: true,
    Min:      core.Float64(0),
    Max:      core.Float64(999999.99),
}

Properties

• Min - Minimum value (nil = no limit)
• Max - Maximum value (nil = no limit)
• OnlyInt - Restrict to integer values only
• Required - Require non-zero value

Special modifiers

// Increment/decrement
record.Set("views+", 1)      // Add 1 to current value
record.Set("stock-", 5)      // Subtract 5 from current value

Examples

Price

&core.NumberField{
    Name:     "price",
    Required: true,
    Min:      core.Float64(0),
    Max:      core.Float64(1000000),
}

Quantity (integer)

&core.NumberField{
    Name:     "quantity",
    Required: true,
    Min:      core.Float64(0),
    OnlyInt:  true,
}

Rating

&core.NumberField{
    Name: "rating",
    Min:  core.Float64(0),
    Max:  core.Float64(5),
}

Email field

Stores and validates email addresses.

&core.EmailField{
    Name:          "email",
    Required:      true,
    OnlyDomains:   []string{"company.com"},
    ExceptDomains: []string{"spam.com"},
}

Properties

• OnlyDomains - Whitelist of allowed email domains
• ExceptDomains - Blacklist of forbidden email domains
• Required - Require non-empty email

You can only use either OnlyDomains or ExceptDomains, not both.

Examples

Basic email

&core.EmailField{
    Name:     "contact_email",
    Required: true,
}

Corporate only

&core.EmailField{
    Name:        "work_email",
    Required:    true,
    OnlyDomains: []string{"company.com", "subsidiary.com"},
}

Block disposable

&core.EmailField{
    Name:          "email",
    Required:      true,
    ExceptDomains: []string{"tempmail.com", "throwaway.email"},
}

URL field

Stores and validates URLs.

&core.URLField{
    Name:         "website",
    Required:     true,
    OnlyDomains:  []string{"example.com"},
    ExceptDomains: []string{"blocked.com"},
}

Properties

• OnlyDomains - Whitelist of allowed domains
• ExceptDomains - Blacklist of forbidden domains
• Required - Require non-empty URL

Bool field

Stores true/false values.

&core.BoolField{
    Name: "published",
}

Properties

Only the common properties (Name, Required is not applicable as false is a valid value).

Date field

Stores date and time values.

&core.DateField{
    Name:     "published_at",
    Required: true,
    Min:      "2024-01-01 00:00:00.000Z",
    Max:      "2025-12-31 23:59:59.999Z",
}

Properties

• Min - Minimum date (RFC 3339 format)
• Max - Maximum date (RFC 3339 format)
• Required - Require non-empty date

Autodate field

Automatically sets date on create and/or update.

&core.AutodateField{
    Name:     "created",
    OnCreate: true,
    OnUpdate: false,
}

Properties

• OnCreate - Set date when record is created
• OnUpdate - Update date when record is modified

Examples

Created timestamp

&core.AutodateField{
    Name:     "created_at",
    OnCreate: true,
    OnUpdate: false,
}

Updated timestamp

&core.AutodateField{
    Name:     "updated_at",
    OnCreate: true,
    OnUpdate: true,
}

Select field

Stores single or multiple predefined values.

&core.SelectField{
    Name:      "status",
    Required:  true,
    Values:    []string{"draft", "published", "archived"},
    MaxSelect: 1,
}

Properties

• Values - List of allowed values
• MaxSelect - Max selections (1 = single, >1 = multiple)
• Required - Require at least one selection

Examples

Single select

&core.SelectField{
    Name:      "status",
    Required:  true,
    Values:    []string{"active", "inactive", "pending"},
    MaxSelect: 1,
}

Multiple select

&core.SelectField{
    Name:      "tags",
    Values:    []string{"tech", "business", "lifestyle", "travel"},
    MaxSelect: 3,
}

JSON field

Stores arbitrary JSON data.

&core.JSONField{
    Name:     "metadata",
    MaxSize:  2097152, // 2MB
}

Properties

• MaxSize - Maximum JSON size in bytes (default 2MB)
• Required - Require non-empty JSON

Example

&core.JSONField{
    Name:    "settings",
    MaxSize: 1048576, // 1MB
}

// Usage
record.Set("settings", map[string]any{
    "theme": "dark",
    "notifications": true,
    "language": "en",
})

Editor field

Stores rich text HTML content.

&core.EditorField{
    Name:             "content",
    Required:         true,
    ConvertURLs:      true,
    ExceptDomains:    []string{"malicious.com"},
    OnlyDomains:      []string{"trusted.com"},
}

Properties

• ConvertURLs - Auto-convert plain text URLs to links
• OnlyDomains - Whitelist of allowed domains in content
• ExceptDomains - Blacklist of forbidden domains
• Required - Require non-empty content

File field

Handles file uploads with validation.

&core.FileField{
    Name:      "attachments",
    MaxSelect: 5,
    MaxSize:   5242880, // 5MB per file
    MimeTypes: []string{"image/jpeg", "image/png", "application/pdf"},
    Thumbs:    []string{"100x100", "300x300", "0x500"},
    Protected: false,
}

Properties

• MaxSelect - Max files (1 = single, >1 = multiple)
• MaxSize - Max size per file in bytes (default 5MB)
• MimeTypes - Allowed MIME types (empty = all)
• Thumbs - Thumbnail sizes for images
• Protected - Require token to access files
• Required - Require at least one file

Thumbnail formats

• 100x300 - Crop to 100x300 from center
• 100x300t - Crop to 100x300 from top
• 100x300b - Crop to 100x300 from bottom
• 100x300f - Fit inside 100x300 (no crop)
• 0x300 - Resize to 300px height, preserve aspect ratio
• 100x0 - Resize to 100px width, preserve aspect ratio

Special modifiers

// Append files
record.Set("images+", []*filesystem.File{newImage})

// Prepend files
record.Set("+images", []*filesystem.File{newImage})

// Remove files
record.Set("images-", "old_image.jpg")

Examples

Profile picture

&core.FileField{
    Name:      "avatar",
    MaxSelect: 1,
    MaxSize:   2097152, // 2MB
    MimeTypes: []string{"image/jpeg", "image/png", "image/webp"},
    Thumbs:    []string{"100x100", "300x300"},
}

Documents

&core.FileField{
    Name:      "documents",
    MaxSelect: 10,
    MaxSize:   10485760, // 10MB
    MimeTypes: []string{
        "application/pdf",
        "application/msword",
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    },
    Protected: true,
}

Product images

&core.FileField{
    Name:      "images",
    Required:  true,
    MaxSelect: 5,
    MaxSize:   5242880, // 5MB
    MimeTypes: []string{"image/jpeg", "image/png"},
    Thumbs:    []string{"100x100", "400x400", "1200x0"},
}

Relation field

Links to records in other collections.

&core.RelationField{
    Name:          "author",
    Required:      true,
    CollectionId:  "users_collection_id",
    MaxSelect:     1,
    MinSelect:     1,
    CascadeDelete: false,
}

Properties

• CollectionId - ID of the related collection (required)
• MaxSelect - Max related records (1 = single, >1 = multiple)
• MinSelect - Min required relations
• CascadeDelete - Delete record if all relations are deleted
• Required - Require at least one relation

CollectionId cannot be changed after the field is created. You must delete and recreate the field to change the target collection.

Special modifiers

// Append relations
record.Set("tags+", []string{"tag1_id", "tag2_id"})

// Prepend relations
record.Set("+tags", []string{"tag1_id"})

// Remove relations
record.Set("tags-", "tag1_id")

Examples

Single relation

&core.RelationField{
    Name:         "category",
    Required:     true,
    CollectionId: categoryCollectionId,
    MaxSelect:    1,
}

Multiple relations

&core.RelationField{
    Name:         "tags",
    CollectionId: tagsCollectionId,
    MaxSelect:    10,
    MinSelect:    1,
}

Self-referencing

&core.RelationField{
    Name:         "parent",
    CollectionId: collection.Id, // Same collection
    MaxSelect:    1,
}

Password field

Stores hashed passwords (auth collections only).

&core.PasswordField{
    Name:     "password",
    System:   true,
    Hidden:   true,
    Required: true,
    Min:      8,
    Max:      100,
    Pattern:  "", // Optional pattern for validation
}

Properties

• Min - Minimum password length
• Max - Maximum password length
• Pattern - Regex pattern for validation
• Required - Require non-empty password

Passwords are automatically hashed using bcrypt before storage. The plain text password is never stored.

Working with fields

Adding fields to collections

collection.Fields.Add(
    &core.TextField{Name: "title"},
    &core.TextField{Name: "content"},
)

Adding at specific position

// Insert at index 1
collection.Fields.AddAt(1,
    &core.TextField{Name: "subtitle"},
)

Removing fields

collection.Fields.RemoveByName("old_field")
collection.Fields.RemoveById("field_id")

Getting fields

field := collection.Fields.GetByName("title")
field := collection.Fields.GetById("field_id")

// Get all field names
names := collection.Fields.FieldNames()

// Get as map
fieldsMap := collection.Fields.AsMap()

Field validation

Fields are validated when you save the collection:

if err := app.Save(collection); err != nil {
    // Handle validation errors
    if validationErr, ok := err.(validation.Errors); ok {
        for field, fieldErr := range validationErr {
            fmt.Printf("Field %s: %v\n", field, fieldErr)
        }
    }
}

Helper functions

Common helper functions for working with field values:

// For pointer fields (Min, Max in NumberField)
core.Float64(42.5)    // Returns *float64
core.String("value")  // Returns *string

// For checking field types
if textField, ok := field.(*core.TextField); ok {
    // Work with text field
}

Best practices

Validation

• Set appropriate min/max constraints
• Use patterns for format validation
• Mark fields as required only when necessary
• Provide sensible default values

Naming

• Use camelCase or snake_case consistently
• Keep names descriptive but concise
• Avoid reserved names (id, created, updated)
• Use plural for multiple select fields

Performance

• Use indexes for frequently queried fields
• Limit relation depth (avoid deep nesting)
• Set appropriate MaxSize for files and JSON
• Use select fields instead of text for fixed values

Security

• Mark sensitive fields as Hidden
• Use Protected for private files
• Validate file MIME types
• Set appropriate size limits

Next steps

Base collections

Create your first collection

Auth collections

Add user authentication

Validation

Advanced validation techniques

API rules

Secure your data