serverpod-generate

name: serverpod-generate description: Use when Serverpod models are changed and code generation is needed. Also covers migrations and server startup verification.

Serverpod Code Generation Skill

When to Run Generation

Run serverpod generate after:

• Creating a new model YAML file
• Modifying fields in an existing model
• Adding or changing indexes
• Modifying relations between models

Model File Location

Models are defined in YAML files at:

rmotly_server/lib/src/models/*.yaml

Model Definition Syntax

Basic Model

# lib/src/models/control.yaml
class: Control
table: controls
fields:
  name: String
  controlType: String
  config: String
  position: int
  createdAt: DateTime
  updatedAt: DateTime

With Relations

# lib/src/models/control.yaml
class: Control
table: controls
fields:
  userId: int, relation(parent=users)
  name: String
  controlType: String
  actionId: int?, relation(parent=actions)
  config: String
  position: int
  createdAt: DateTime
  updatedAt: DateTime

With Indexes

class: Event
table: events
fields:
  userId: int, relation(parent=users)
  sourceType: String
  sourceId: String
  eventType: String
  payload: String?
  timestamp: DateTime
indexes:
  event_user_idx:
    fields: userId
    type: btree
  event_timestamp_idx:
    fields: timestamp
    type: btree

Field Types

Optional Fields

Add ? suffix for nullable fields:

fields:
  description: String?    # Optional
  payload: String?        # Optional
  actionId: int?          # Optional foreign key

Generation Commands

Basic Generation

cd rmotly_server
serverpod generate

This generates:

• Model classes in lib/src/generated/
• Client code in rmotly_client/
• Protocol files

Full Workflow After Model Changes

# 1. Navigate to server directory
cd rmotly_server

# 2. Generate code
serverpod generate

# 3. If database schema changed, create migration
serverpod create-migration

# 4. Apply migrations to database
serverpod apply-migrations

# 5. Verify server starts correctly
dart bin/main.dart

Database Migrations

Create Migration

After changing model fields that affect the database:

cd rmotly_server
serverpod create-migration

This creates a migration file in migrations/ directory.

Apply Migrations

serverpod apply-migrations

Migration Options

# Apply migrations (default)
serverpod apply-migrations

# Repair migration state (if needed)
serverpod repair-migrations

# List pending migrations
serverpod list-migrations

Verification Steps

After running generation:

1. Check Generated Files

# Verify model was generated
ls rmotly_server/lib/src/generated/

# Verify client was updated
ls rmotly_client/lib/src/protocol/

2. Start Server

cd rmotly_server
dart bin/main.dart

Expected output:

Server starting...
Serverpod listening on port 8080

3. Run Server Tests

cd rmotly_server
dart test

4. Update Flutter App Dependencies

cd rmotly_app
flutter pub get

Troubleshooting

Generation Errors

"Could not find model file"

• Check YAML file is in lib/src/models/
• Verify YAML syntax is correct

"Invalid field type"

• Check field type is supported
• Ensure proper relation syntax

Migration Errors

"Migration already applied"

• Don't modify existing migrations
• Create new migration for changes

"Database connection failed"

• Check PostgreSQL is running
• Verify config/development.yaml credentials

Server Won't Start

# Check database is accessible
psql -U rmotly_user -d rmotly -h localhost

# Check Redis is running
redis-cli ping

# Check port is not in use
lsof -i :8080

Common Model Patterns

User Model with Auth

class: User
table: users
fields:
  email: String
  displayName: String?
  fcmToken: String?
  createdAt: DateTime
  updatedAt: DateTime
indexes:
  user_email_idx:
    fields: email
    unique: true

Event Logging Model

class: Event
table: events
fields:
  userId: int, relation(parent=users)
  sourceType: String
  sourceId: String
  eventType: String
  payload: String?
  actionResult: String?
  timestamp: DateTime
indexes:
  event_user_time_idx:
    fields: userId, timestamp

Many-to-Many Relation

# Junction table for many-to-many
class: ControlAction
table: control_actions
fields:
  controlId: int, relation(parent=controls)
  actionId: int, relation(parent=actions)
indexes:
  control_action_unique_idx:
    fields: controlId, actionId
    unique: true

Quick Reference

# Generate code
cd rmotly_server && serverpod generate

# Create migration
serverpod create-migration

# Apply migrations
serverpod apply-migrations

# Start server
dart bin/main.dart

# Run tests
dart test