code_order.rdoc

doc/code_order.rdoc
Last Update: 2024-05-11 10:53:18 -0700

Code Order

In Sequel, the order in which code is executed during initialization is important. This guide provides the recommended way to order your Sequel code. Some of these guidelines are not strictly necessary, but others are, and this guide will be specific about which are strictly necessary.

Require Sequel

This is sort of a no-brainer, but you need to require the library first. This is a strict requirement, none of the other code can be executed unless the library has been required first. Example:

require 'sequel'

Add Global Extensions

Global extensions are loaded with Sequel.extension, and affect other parts of Sequel or the general ruby environment. It’s not necessary to load them first, but it is a recommended practice. Example:

Sequel.extension :blank

Add Extensions Applied to All Databases/Datasets

If you want database or datasets extensions applied to all databases and datasets, you must use Sequel::Database.extension to load the extension before connecting to a database. If you connect to a database before using Sequel::Database.extension, it will not have that extension loaded. Example:

Sequel::Database.extension :columns_introspection

Connect to Databases

Connecting to a database is required before running any queries against that database, or creating any datasets or models. You cannot create model classes without having a database object created first. The convention for an application with a single Database instance is to store that instance in a constant named DB. Example:

DB = Sequel.connect('postgres://user:pass@host/database')

Add Extensions Specific to a Database or All Datasets in that Database

If you want specific databases to use specific extensions, or have all datasets in that database use a specific extension, you need to load that extension into the database after creating it using Sequel::Database#extension. Example:

DB.extension :pg_array

Configure Global Model Behavior

If you want to change the configuration for all model classes, you must do so before loading your model classes, as configuration is copied into the subclass when model subclasses are created. Example:

Sequel::Model.raise_on_save_failure = false

Add Global Model Plugins

If you want to load a plugin into all models classes, you must do so before loading your model classes, as plugin specific data may need to be copied into the subclass when model subclasses are created. Example:

Sequel::Model.plugin :prepared_statements

Load Model Classes

After you have established a database connection, and configured your global model configuration and global plugins, you can load your model classes. It’s recommended to have a separate file for each model class, unless the model classes are very simple. Example:

Dir['./models/*.rb'].each{|f| require f}

Finalize Associations and Freeze Model Classes and Database

After all the models have been setup, you can finalize the associations. This can speed up association reflection methods by doing a lookup in advance to find the associated class, and cache related association information in the association itself.

Additionally, in production and testing, you should freeze the model classes and Database instance, so that you can detect unsafe runtime modification of the configuration:

model_classes.each(&:finalize_associations)
model_classes.each(&:freeze)
DB.freeze

‘model_classes` is not a Sequel method, it indicates an array of model classes you defined. Instead of listing them manually, the `subclasses` plugin can be used to keep track of all model classes that have been setup in your application. Finalizing their associations and freezing them can easily be achieved through the plugin:

# Register the plugin before setting up the models
Sequel::Model.plugin :subclasses
# ... setup models
# Now finalize associations & freeze models by calling the plugin:
Sequel::Model.freeze_descendents