Validations & Callbacks

Defining Validations

Use validates inside your model class to declare rules for each field. Validations run automatically before create and save operations.

class User < Model
  validates("email", { "presence": true, "uniqueness": true })
  validates("name", { "presence": true, "min_length": 2 })
  validates("age", { "numericality": true, "min": 0, "max": 150 })
  validates("password", { "min_length": 8 })
end

Validation Options

Each option controls a specific check on the field value:

Validation Results

Model.create() always returns an instance of the class. On validation or database failure, the returned instance is not persisted and its _errors field holds an array of { "field", "message" } entries. On success, _errors is nil.

user = User.create({ "email": "" })
if user._errors
  for error in user._errors
    print(error["field"] + ": " + error["message"])
  end
else
  print("Created user: " + user._key)
end

Atomic Uniqueness

uniqueness: true issues a SELECT … LIMIT 1 before the write, but that check is best-effort: two concurrent User.create({ "email": "x" }) calls can both pass the SELECT and both insert. To make uniqueness atomic, declare a unique index on the column at deploy time and let the database enforce it. Soli detects the resulting 409 from Model.create, instance.save, instance.update, Model.upsert, and Model.find_or_create_by, and turns it into the same _errors entry the SELECT path produces (field: "has already been taken"), so callers handle the race identically.

# Run once at deploy time (e.g. in a migration):
solidb.create_index("users", "users_email_unique", ["email"], { "unique": true })

Custom Methods on Models

Define instance methods directly in your model class to encapsulate business logic. Use this to access the current instance's fields.

class User < Model
  def is_admin -> Bool
    this.role == "admin"
  end

  def full_name -> String
    this.first_name + " " + this.last_name
  end
end

user = User.find("user123")
if user.is_admin
  print("Welcome, admin " + user.full_name())
end

Callbacks

Callbacks let you hook into the lifecycle of a model record. Declare them at the class level with the name of the instance method to call.

class User < Model
  before_save("normalize_email")
  after_create("send_welcome_email")
  before_update("log_changes")
  after_delete("cleanup_related")

  def normalize_email
    this.email = this.email.downcase
  end

  def send_welcome_email
    # Send email logic
  end
end

Available Callbacks

Firing order per persistence method

Both class-level methods (Model.create, Model.update) and instance-level mutators run the matching callbacks. Rails-style: _save callbacks fire on every persistence path, plus the more specific event for the operation. After-callbacks only fire when the persist call succeeds — if the native method returns false (validation or DB error) the after-callbacks are skipped and the instance carries _errors.

Vetoing persistence from a before_* callback

Returning false from any before_* callback aborts the operation. The native DB write is skipped, after-callbacks don't run, and the instance picks up an _errors entry of the form [{ "message": "before_<event> callback returned false; persistence aborted" }]. Callers receive false (or, for Model.create / Model.update, the instance with _errors populated) so they can branch on the result identically to a validation failure.

class Audited < Model
  before_save("can_save")

  def can_save
    return false if User.current.is_nil?  # returns false → save() / update() aborts
  end
end

The veto fires at the first false — subsequent before-callbacks in the chain don't run. Use this for authorization gates, integrity checks, or any "deny by default" pattern. Mutating-only callbacks (the common case) just don't return false and run end-to-end as before.

Complete Example

class User < Model
  validates("email", { "presence": true, "uniqueness": true, "format": "^[^@]+@[^@]+$" })
  validates("name", { "presence": true, "min_length": 2, "max_length": 100 })
  validates("age", { "numericality": true, "min": 0, "max": 150 })
  validates("password", { "min_length": 8 })
  validates("role", { "custom": "validate_role" })

  before_save("normalize_email")
  after_create("send_welcome_email")
  before_delete("cleanup_related")

  def normalize_email
    this.email = this.email.downcase
  end

  def send_welcome_email
    # Send welcome email to new users
  end

  def cleanup_related
    # Remove associated data before deletion
  end

  def validate_role
    valid_roles = ["admin", "user", "moderator"]
    if !valid_roles.includes?(this.role)
      return "must be one of: admin, user, moderator"
    end
  end

  def is_admin -> Bool
    this.role == "admin"
  end

  def full_name -> String
    this.first_name + " " + this.last_name
  end
end

# Creating a user with validation
user = User.create({
  "email": "[email protected]",
  "name": "Alice",
  "age": 30,
  "password": "securepass",
  "role": "admin"
})

if !user._errors
  print(user.email)       # => "[email protected]" (normalized by before_save)
  print(user.is_admin)    # => true
  print(user.full_name()) # => "Alice "
end

Next Steps