Marten 0.5.0 release notes

July 13, 2024.

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, and Marten::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 to text/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, and false 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 an unless 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 supports isolated and contextual 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 new templates.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 the as keyword.
• The loop variable, which is available when using the for template tag, now supports even? and odd? 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 the auth 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 the serve 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 (see log_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 to true.

Backward incompatible changes

Handlers and HTTP

• Handlers making use of the Marten::Handlers::Schema generic handler (or schemas inheriting from it, such as Marten::Handlers::RecordCreate or Marten::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 replace 200 by 422 in the impacted specs.