0.5.0
Marten 0.5 is here! This major version adds substantial enhancements to the framework like the ability to leverage pre-fetched relations in query sets, model scopes, enum fields for models and schemas, raw SQL predicates, and more!
Requirements and compatibility
- Crystal: 1.11, 1.12, and 1.13.
- Databases:
- MariaDB 10.4 and higher.
- MySQL 8.0.11 and higher.
- PostgreSQL 12 and higher.
- SQLite 3.27.0 and higher.
New features
Relations pre-fetching
Marten now provides the ability to prefetch relations when using query sets through the use of the new #prefetch
method. When using #prefetch
, the records corresponding to the specified relationships will be prefetched in single batches and each record returned by the original query set will have the corresponding related objects already selected and populated.
For example:
posts_1 = Post.all.to_a
# hits the database to retrieve the related "tags" (many-to-many relation)
puts posts_1[0].tags.to_a
posts_2 = Post.all.prefetch(:tags).to_a
# doesn't hit the database since the related "tags" relation was already prefetched
puts posts_2[0].tags.to_a
Like the existing #join
method, this allows to alleviate N+1 issues commonly encountered when accessing related objects. However, unlike #join
(which can only be used with single-valued relationships), #prefetch
can be used with both single-valued relationships and multi-valued relationships (such as many-to-many relationships, reverse many-to-many relationships, and reverse many-to-one relationships).
Please refer to Pre-fetching relations to learn more about this new capability.
Model scopes
It is now possible to define scopes in model classes. Scopes allow to pre-define specific filtered query sets, which can be easily applied to model classes and model query sets.
Such scopes can be defined through the use of the #scope
macro, which expects a scope name (string literal or symbol) as first argument and requires a block where the query set filtering logic is defined:
class Post < Marten::Model
field :id, :big_int, primary_key: true, auto: true
field :title, :string, max_size: 255
field :is_published, :bool, default: false
field :created_at, :date_time
scope :published { filter(is_published: true) }
scope :unpublished { filter(is_published: false) }
scope :recent { filter(created_at__gt: 1.year.ago) }
end
Post.published # => Post::QuerySet [...]>
It is also possible to override the default scope through the use of the #default_scope
macro. This macro requires a block where the query set filtering logic is defined:
class Post < Marten::Model
field :id, :big_int, primary_key: true, auto: true
field :title, :string, max_size: 255
field :is_published, :bool, default: false
field :created_at, :date_time
default_scope { filter(is_published: true) }
end
Please refer to Scopes for more details on how to define scopes.
Enum field for models and schemas
It is now possible to define enum
fields in models and schemas. For models, such fields allow you to store valid enum values, with validation enforced at the database level. When validating data with schemas, they allow you to expect valid string values that match those of the configured enum.
For example:
enum Category
NEWS
BLOG
end
class Article < Marten::Model
field :id, :big_int, primary_key: true, auto: true
field :category, :enum, values: Category
end
article = Article.last!
article.category # => Category::BLOG
Raw SQL predicate filtering
Marten now provides the ability to filter query sets using raw SQL predicates through the use of the #filter
method. This is useful when you want to leverage the flexibility of SQL for specific conditions, but still want Marten to handle the column selection and query building for the rest of the query.
For example:
Author.filter("first_name = :first_name", first_name: "John")
Author.filter("first_name = ?", "John")
Author.filter { q("first_name = :first_name", first_name: "John") }
Please refer to Filtering with raw SQL predicates to learn more about this new capability.
Minor features
Models and databases
- A new
#pks
method was introduced for query sets to make it easy to retrieve the primary key values of the model records targeted by a given current query set. - A
#count
method is now available on model classes and provides the same functionality as the#count
query set method. - A new
#bulk_create
method was introduced to make it easy to insert multiple model instances into the database in a single query (which can be useful when dealing with large amounts of data that need to be inserted into the database). - A new
#average
method was introduced to allow computing the average values of a specific model field at the database level for the records targeted by a specific query set. - A new
#sum
method was introduced to allow computing the sum of the values of a specific model field at the database level for the records targeted by a specific query set. - It is now possible to compute the minimum and maximum values of a specific field at the database level for the records targeted by a query set through the use of the
#minimum
and#maximum
methods. - The
in
query set predicate now supports filtering on arrays of model records directly. - Query sets now provide a
#to_sql
method allowing to retrieve the corresponding SQL representation. - Query sets can now be combined using the AND and OR binary operators. This can be achieved through the use of the & and
|
query set methods. - Invalid record exceptions (instances of
Marten::DB::Errors::InvalidRecord
) now provide more details regarding the actual errors of the associated record. - Creations of records from many-to-one reverse relation query sets are now scoped to the related record. See Many-to-one relationships for more details.
- A new
#build
method was introduced to make it possible to initialize new model instances from query sets.
Handlers and HTTP
- The
#render
helper method and the generic handlers that involve template renderings now automatically insert the request object in the template context. - The
Marten::Handlers::RecordDetail
,Marten::Handlers::RecordUpdate
, andMarten::Handlers::RecordDelete
generic handlers now provide the ability to specify a custom query set instead of a model class. This can be achieved through the use of the#queryset
macro. - A new middleware was introduced to make it easy to override the method of incoming requests based on the value of a specific request parameter or header: the method override middleware. This mechanism is useful for overriding HTTP methods in HTML forms that natively support GET and POST methods only. A dedicated set of settings is also available to easily customize the behavior of this middleware.
- The value of the max-age directive used for the Cache-Control header that is set by the assets serving middleware can now be configured in the
assets.max_age
setting. - Subclasses of the
Marten::Handlers::Template
generic handler now support a#content_type
class method that allows configuring the content type of the response (unless specified, the content type will default totext/html
).
Templates
- Enum values can now be used in templates. Please refer to Using enums in contexts to learn more about this capability.
- Support for the
nil
,true
, andfalse
literals was added to the Marten templating language. Please refer to Literal values for more details on supported literals. - The
assign
template tag now supports anunless assigned
suffix which allows to specify that the assignment must happen only if no variable with the same name is already present in the template context. - The
include
template tag now supportsisolated
andcontextual
suffixes that allow specifying whether the included templates should have access to the outer context variables. Unless specified, the default behavior is controlled by the newtemplates.isolated_inclusions
setting. - A new
capture
template tag was introduced to make it possible to easily assign the output of a block of code to a new variable. - The output of the
csrf_token
template tag can now be outputted to a variable by leveraging theas
keyword. - The
loop
variable, which is available when using thefor
template tag, now supportseven?
andodd?
attributes. - A new
csrf_input
template tag was introduced to make it easier to insert the CSRF token into HTML forms. This new tag allows the generation of a hidden form input containing the CSRF token computed for the current request. - A new
escape
template tag was introduced to allow disabling/enabling auto-escaping within a block. - A new
unless
template tag was introduced to provide an alternative way of writing conditional template blocks.
Development
- The
collectassets
management command now provides the ability to fingerprint collected assets and generate a corresponding JSON manifest. Please refer to Asset manifests and fingerprinting to learn more about this capability. - The built-in authentication application (which can be generated either through the use of the
new
management command or theauth
generator) now uses POST requests when signing out users. - A
play
management command was introduced to make it easy to start a Crystal playground server initialized for the current project and open it in the default browser. - The
new
management command can now generate project/app structures that use the development version of Marten when the--edge
(or-e
) option is used. - A new
trailing_slash
setting was introduced to configure whether an HTTP permanent redirect (301) should be issued when an incoming URL that does not match any of the configured routes either ends with a slash or does not. - A new
--open
option was added to theserve
management command to make it possible to automatically open the development server in the default browser. - New projects created through the use of the
new
management command now have the debug log level enabled in development (seelog_level
).
Security
- It is now possible to configure that the CSRF token must be persisted in the session store. This can be achieved by setting the
use_session
setting totrue
.
Backward incompatible changes
Handlers and HTTP
- Handlers making use of the
Marten::Handlers::Schema
generic handler (or schemas inheriting from it, such asMarten::Handlers::RecordCreate
orMarten::Handlers::RecordUpdate
) will now return a 422 Unprocessable Content response instead of a 200 OK response when processing an invalid schema. While this won't have any incidence on end users, this change may make some specs fail if you were testing the response code of handlers that process invalid schema data. The way to fix this will be to replace200
by422
in the impacted specs.