Defining Models
In CouchbaseOrm, models are defined as Ruby classes that inherit from CouchbaseOrm::Base
. Each model represents a document type in Couchbase Server and encapsulates the data and behavior of the objects in your application.
3.1. Creating a Model
To create a model, define a new class that inherits from CouchbaseOrm::Base
. For example, let's create a User
model:
class User < CouchbaseOrm::Base
end
By convention, CouchbaseOrm uses the underscored, pluralized name of the class as the document type in Couchbase Server. In this case, the document type for the User
model would be users
.
3.2. Attribute Types
CouchbaseOrm supports various attribute types to define the structure and types of your model's data. You can specify the attributes of your model using the attribute
method.
Here's an example of defining attributes in the User
model:
class User < CouchbaseOrm::Base
attribute :email, :string
attribute :name, :string
attribute :age, :integer
attribute :height, :float
attribute :is_active, :boolean
attribute :birth_date, :date
attribute :created_at, :datetime
attribute :updated_at, :datetime
attribute :appointment_time, :time
attribute :hobbies, :array, type: :string
attribute :metadata, type: Hash
attribute :avatar, :binary
attribute :created_at, :datetime
attribute :updated_at, :datetime
end
In this example, we define several attributes for the User
model, each with a specific type. The supported attribute types in CouchbaseOrm include:
-
:string
: Represents a string value. -
:integer
: Represents an integer value. -
:float
: Represents a floating-point value. -
:boolean
: Represents a boolean value. -
:date
: Represents a date value. -
:datetime
: Represents a date and time value. -
:time
: Represents a time value. -
:array
: Represents an array of values. -
:binary
: Represents a binary data value. -
Hash
: Represents a hash (dictionary) of key-value pairs.
CouchbaseOrm automatically handles the serialization and deserialization of these attribute types when storing and retrieving documents from Couchbase Server.
3.3. Attribute Options
In addition to specifying the attribute type, you can also provide additional options to customize the behavior of the attributes. Some commonly used options include:
default
: Specifies a default value for the attribute if no value is provided.
Here's an example of using attribute options:
class User < CouchbaseOrm::Base
attribute :name, :string, default: 'Unknown'
end
In this example, the name
attribute has a default value of 'Unknown'
.
3.4. Timestamps
CouchbaseOrm provides built-in support for timestamp attributes. By default, if you define attributes named created_at
and updated_at
with the :datetime
type, CouchbaseOrm will automatically populate these attributes with the current date and time when a document is created or updated. To enable this feature, add the created_at
and updated_at
attributes to your model.The fields are automatically updated when the document is saved.document.save
class User < CouchbaseOrm::Base
attribute :created_at, :datetime
attribute :updated_at, :datetime
end
With these timestamp attributes defined, CouchbaseOrm will manage them automatically whenever a document is persisted or updated.
3.5. Callbacks
CouchbaseOrm supports lifecycle callbacks that allow you to execute code at certain points in a document's lifecycle. Callbacks can be used to perform actions before or after specific events, such as saving or updating a document.
Here are some commonly used callbacks:
before_create
: Runs before a new document is created.after_create
: Runs after a new document is created.before_save
: Runs before a document is saved (either created or updated).after_save
: Runs after a document is saved (either created or updated).before_update
: Runs before an existing document is updated.after_update
: Runs after an existing document is updated.before_destroy
: Runs before a document is destroyed.after_destroy
: Runs after a document is destroyed.
To define a callback, use the corresponding callback method and provide a block or method name to be executed. For example:
class Document < CouchbaseOrm::Base
attribute :title, :string
attribute :content, :string
before_create :before_create_callback
after_create :after_create_callback
before_save :before_save_callback
after_save :after_save_callback
before_update :before_update_callback
after_update :after_update_callback
before_destroy :before_destroy_callback
after_destroy :after_destroy_callback
private
def before_create_callback
puts "Running before_create callback for #{title}"
end
def after_create_callback
puts "Running after_create callback for #{title}"
end
def before_save_callback
puts "Running before_save callback for #{title}"
end
def after_save_callback
puts "Running after_save callback for #{title}"
end
def before_update_callback
puts "Running before_update callback for #{title}"
end
def after_update_callback
puts "Running after_update callback for #{title}"
end
def before_destroy_callback
puts "Running before_destroy callback for #{title}"
end
def after_destroy_callback
puts "Running after_destroy callback for #{title}"
end
end
In this example, the Document
model defines several callbacks that are triggered at different points in the document's lifecycle. The callback methods are implemented as private instance methods within the model class.
Callbacks allow you to encapsulate logic related to the document lifecycle and maintain a clean and organized codebase.
3.6. Validations
CouchbaseOrm includes built-in validation capabilities to ensure the integrity and validity of your data before persisting it to Couchbase Server. Validations help you enforce business rules and constraints on your models.
To define validations, use the validates
method followed by the attribute name and the desired validation rules. For example:
class Book < CouchbaseOrm::Base
attribute :title, :string
attribute :author, :string
attribute :pages, :integer
attribute :genre, :string
attribute :email, :string
validates_presence_of :title
validates :author, presence: true
validates :pages, numericality: { greater_than: 0 }
validates :genre, inclusion: { in: %w[Fiction Non-Fiction] }
validates :author, format: { with: /\A[a-zA-Z]+\z/, message: 'only allows letters' }
validates :pages, length: { maximum: 500 }
validates :genre, exclusion: { in: %w[Science-Fiction] }
validates :email, format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i }
validate :custom_validation
private
...
end
In this example, we define several validations for the User
model:
- The
name
attribute must be present. - The
email
attribute must match a specific format (a valid email address). - The
age
attribute must be a number greater than or equal to 18.
CouchbaseOrm provides a wide range of built-in validation helpers, such as:
presence
: Ensures that the attribute is not blank.validates_presence_of
: An alias forpresence
.
format
: Validates the attribute value against a regular expression.length
: Validates the length of the attribute value.numericality
: Validates that the attribute value is a valid number.inclusion
: Ensures that the attribute value is included in a given set.exclusion
: Ensures that the attribute value is not included in a given set.
You can also define custom validation methods by adding methods to your model class and using the validate
method to trigger them. For example:
class Book < CouchbaseOrm::Base
attribute :title, :string
...
validate :custom_validation
private
def custom_validation
puts 'Running custom validation...'
if title&.include?('Funny')
errors.add(:title, 'should not contain the word "Funny"')
else
# print the title
puts "Title: #{title}"
puts 'Custom validation passed'
end
end
end
In this example, the custom_validation
method is called during the validation process, and if some_condition
is met, an error is added to the model's errors
collection.
Validations are automatically run when saving a document. If any validations fail, the save operation will be aborted, and the model's errors
collection will contain the validation error messages.
By leveraging validations, you can ensure the quality and consistency of your data before it is persisted to Couchbase Server.
With the model definition covered, including attributes, callbacks, and validations, you're ready to start querying and persisting data using CouchbaseOrm. In the next section, we'll explore the querying capabilities of CouchbaseOrm and how to retrieve data from Couchbase Server efficiently.