Sequel Extensions¶ ↑
Sequel has an official extension system, for adding global, Database, and Dataset extensions.
Global Extensions¶ ↑
Global extensions can add or modify the behavior of any part of
Sequel. Technically, they are not limited to affecting
Sequel, as they can also modify code outside of
Sequel (e.g. the blank extension). However, extensions that modify things outside of
Sequel generally do so only for backwards compatibility.
Global extensions are loaded via
All this does is require the relevent extension from
sequel/extensions/named_timezones somewhere in the ruby path. Global extensions are just a simpler, consistent way to require code that modifies
Database Extensions¶ ↑
Database extensions should add or modify the behavior of a single
Sequel::Database instance. They are loaded via
The first thing that this does is load the relevent extension globally. However, Database extensions should be structured in a way that loading the relevent extension globally just adds a module with the related behavior, it doesn’t modify any other state. After loading the extension globally, it modifies the related
Sequel::Database object to modify it’s behavior, usually by extending it with a module.
If you want a Database extension loaded into all future Database instances, you can use
Sequel::Database instances created afterward will then automatically have the server_block extension loaded.
Dataset Extensions¶ ↑
Dataset extensions should add or modify the behavior of a single
Sequel::Dataset instance. They are loaded via
Sequel::Dataset#extension returns a modifies copy of the dataset that includes the extension (similar to how most dataset query methods work):
ds = DB[:a].extension(:columns_introspection)
The first thing loading a Dataset extension does is load the relevent extension globally. Similar to Database extensions, loading a Dataset extension globally should not affect state other than maybe adding a module. After loading the extension globally, it returned a modified copy of the
Sequel::Dataset with the extension loaded into it.
If you want to load an extension into all future datasets for a given
Sequel::Database instance, you can also load it as a Database extension:
Likewise, if you want to load an extension into all future datasets for all future databases, you can load it via
Creating Global Extensions¶ ↑
If you want to create a global extension, you just need to store your code so that you can require it via
sequel/extensions/extension_name. Then users can load it via:
It is recommended you only create a global extension if what you want to do would not work as a Database or Dataset extension.
Creating Database Extensions¶ ↑
Creating Database extensions is similar to global extensions in terms of creating the file. However, somewhere in the file, you need to call
Sequel::Database.register_extension. Usually you would call this with the module that will be added to the related
Sequel::Database instance when the extension is loaded. For example, the server_block extension uses something like:
The first argument is the name of the extension as a symbol, and the second is the module.
In some cases, just extending the
Sequel::Database instance with a module is not sufficient. So
Sequel::Database.register_extension also accepts a proc instead of a second argument. This proc is called with the
Sequel::Database instance, and can then run any related code:
Creating Dataset Extensions¶ ↑
Creating Dataset extensions is very similar to creating Database extensions, but instead of calling
Sequel::Database.register_extension, you call
Sequel::Dataset.register_extension. In general, you would call this with the module that will be added to the related
Sequel::Dataset instance when the extension is loaded. For example, the columns_introspection extension uses something like:
The first argument is the name of the extension as a symbol, and the second is the module. When you call the
Sequel::Dataset.register_extension method with a module, it in turn calls
Sequel::Database.register_extension and adds a Database extension that loads this Dataset extension into all future Datasets created from the Database.
You can also call
Sequel::Dataset.register_extension with a proc:
Note that if you use a proc, a corresponding Database extension will not be created automatically (you can still call
Sequel::Database.register_extension manually in this case).