Granite ORM

Because .import is a class-level method, it bypasses the standard instance lifecycle hooks. If your model requires a callback to set a primary key (e.g., a UUID), you must manually invoke the callback on each instance before importing.

Warning: Do not manually run callbacks before a standard .save call, as this will cause the callbacks to execute twice.

# Example: Manually triggering before_create for a collection of items
items = [
  Item.new(item_name: "item1"),
  Item.new(item_name: "item2"),
]

# 1. Manually run the callback to ensure item_id is generated
items.each(&.before_create)

# 2. Perform the bulk import
Item.import(items)

# For a single record:
item = Item.new(item_name: "item5")
item.before_create
item.save

Granite models implement JSON::Serializable and YAML::Serializable by default. You can convert model instances to/from JSON or YAML using the #to_json/#to_yaml and .from_json/.from_yaml methods.

# Example usage (conceptual)
json_data = my_model.to_json
new_model = MyModel.from_json(json_data)

To run migration commands from the command line, create an executable script (e.g., bin/micrate). You must require micrate and the specific database driver you are using (e.g., pg for PostgreSQL). You must also configure Micrate::DB.connection_url using your database connection string, typically sourced from the DATABASE_URL environment variable.

#! /usr/bin/env crystal
#
# To build a standalone command line client, require the
# driver you wish to use and use `Micrate::Cli`.
#

require "micrate"
require "pg"

Micrate::DB.connection_url = ENV["DATABASE_URL"]
Micrate::Cli.run

You can register multiple database connections globally using Granite::Connections << adapter_object. Once registered, models can specify which connection to use by calling the connection method with the name assigned during registration.

Note that you are responsible for supplying the connection URL (e.g., via environment variables) when initializing the adapter.

Granite::Connections << Granite::Adapter::Mysql.new(name: "legacy_db", url: "LEGACY_DB_URL")
Granite::Connections << Granite::Adapter::Pg.new(name: "new_db", url: "NEW_DB_URL")

class Foo < Granite::Base
  connection legacy_db
end

class Bar < Granite::Base
  connection new_db
end

To use Granite, add it to your project's shard.yml dependencies along with the driver for your chosen database. Granite is designed to work with the Amber framework but is compatible with Kemal or any other Crystal framework.

Supported database adapters include Mysql, Pg, and Sqlite.

dependencies:
  granite:
    github: amberframework/granite

  # Pick your database
  mysql:
    github: crystal-lang/crystal-mysql

  sqlite3:
    github: crystal-lang/crystal-sqlite3

  pg:
    github: will/crystal-pg

By default, crystal docs excludes Granite's methods, constants, and properties. To include them in your generated documentation, use the granite_docs flag:

crystal docs -D granite_docs

Granite recommends explicitly creating a model for join tables rather than using hidden tables. To implement a many-to-many relationship (e.g., Users and Rooms), create a third model (e.g., Participant) that belongs_to both entities.

Setup Steps

1. Create the join model (e.g., Participant) with belongs_to associations for both sides.
2. Add has_many associations to the primary models pointing to the join model.
3. Ensure the join table in the database contains foreign keys for both related entities and appropriate indexes.

class User < Granite::Base
  has_many :participants, class_name: Participant
end

class Participant < Granite::Base
  table participants
  belongs_to :user
  belongs_to :room
end

class Room < Granite::Base
  table rooms
  has_many :participants, class_name: Participant
end