code_order.rdoc

doc/code_order.rdoc
Last Update: 2017-02-09 12:56:18 -0800

Code Order

In Sequel, the order in which code is executed 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.

The exception to this is global extensions that integrate with Database-specific extensions, where the Database-specific extension should be loaded first (such as some of the pg_* extensions). In those cases, the global extensions should be loaded after the Database-specific extensions.

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 configration 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

Disconnect If Using Forking Webserver with Code Preloading

If you are using a forking webserver such as unicorn or passenger, with a feature that loads your Sequel code before forking connections (code preloading), then you must disconnect your database connections before forking. If you don't do this, you can end up with child processes sharing database connections and all sorts of weird behavior. Sequel will automatically reconnect on an as needed basis in the child processes, so you only need to do the following in the parent process:

DB.disconnect