{"title":"Jennifer","description":"","section":"guides/models","version":"v1.5","path":"guides/models/jennifer","canonical_url":"https://amberframework.org/docs/v1.5/guides/models/jennifer","markdown_url":"https://amberframework.org/docs/v1.5/guides/models/jennifer.md","inherited":true,"content_markdown":"# Jennifer\n\n## What is Jennifer?\n\n**Jennifer** is an ActiveRecord-like ORM for Crystal with a custom DSL for queries and migrations.\n\n{% hint style=\"info\" %}\nThis section is based on [Jennifer Docs](https://github.com/imdrasil/jennifer.cr/blob/master/docs/index.md). Also see [Amber Jennifer Example App](https://github.com/eliasjpr/amber-jennnifer-app-example).\n{% endhint %}\n\n## Installing Jennifer for Amber\nBy default, Amber applications ship with \n[Granite](https://docs.amberframework.org/granite) a lightweight ORM for Crystal applications. To begin using Jennifer in your Amber application you will need to follow a few steps to get up and running.\n\n### Generate a normal amber app\nBegin by generating a new amber project (if you have not already).\n\n```bash\namber new {project}\ncd project\n```\n\n### Update your project shard.yml\nOnce your Amber project is created, you will need to update your `shard.yml` file to include Jennifer as a dependency.\n\nAdd the following code snippet to your application's `shard.yml` file:\n\n```yaml\n# Jennifer is an ORM\njennifer:\n  github: imdrasil/jennifer.cr\n\n# SAM is a CLI utility for running migrations, creating or dropping tables\nsam:\n  github: imdrasil/sam.cr\n\n```\n\nIn addition to the Jennifer dependency, you may have noticed we included an additional shard called `sam`. The `sam` shard is simple command line utility for running common database tasks such as creating migrations, adding, or dropping tables. While technically optional it is recommended. \n\nOnce you've added the required dependencies, you will need to decide what database you would like to use with your Amber application. By default, Jennifer ships with SQLite support, however, should you want to use PostgreSQL or MySQL, you will need to add in a compatible database adapter to your `shard.yml` file. \n\n```yaml\n# snipped shards \n\n# Your choice of database adapter\n\n# PostgreSQL\npg:\n\tgithub: will/crystal-pg\n\tversion: \"= 0.21.0\"\n\n# MySQL\ncrystal-mysql:\n\tgithub: crystal-lang/crystal-mysql\n\tversion: \"= 0.11.0\"\n```\n\nYou can read about the Crystal community adapters below:\n\n* [MySQL](https://github.com/crystal-lang/crystal-mysql) \n* [PostgreSQL](https://github.com/will/crystal-pg).\n\nOnce you have updated your dependencies and chosen an appropriate adapter (if any), proceed to update your project's shards by running:\n\n```bash\nshards update\n```\n\nThis command will begin installing Jennifer and its associated dependencies into your Amber project.\n\n### Setup your database information\nOnce Jennifer is up an running as a dependency in your project, you will need to create a new database configuration. Inside of your project's `config` directory create a new file called `config/database.yml` and fill in the code snippet below:\n\n```yaml\ndefaults : &defaults\n  host: localhost\n  adapter: postgres\n  user: <add-your-database-user>\n  password: <add-your-database-password>\n  migration_files_path: db/migrations # this is the default location for all migrations\n\ndevelopment:\n  db: blog_development\n  <<: *defaults\n\ntest:\n  db: blog_test\n  <<: *defaults\n```\n\nThe `config/database.yml` describes the various databases Jennifer will use in your project's different environments.\n\n### Add A Jennifer Initializer to Configuration\nWith your `config/database.yml` in place, we need to inform Amber about Jennifer and tell the framework how we would like to configure the ORM. To begin, you will need to create a `config/jennifer.cr` file in your project's `config` directory. Below is a basic setup for Jennifer and you are also encourage to [see an example Amber Jennifer App] for more inspiration.\n\n```crystal\nrequire \"amber\"\nrequire \"colorize\"\n\nJennifer::Config.read(\"config/database.yml\", Amber.env.to_s)\n\nJennifer::Config.configure do |conf|\n  conf.logger = Logger.new(STDOUT)\n\n  conf.logger.formatter = Logger::Formatter.new do |severity, datetime, progname, message, io|\n    io << datetime.colorize(:cyan) << \": \\n\" << message.colorize(:light_magenta)\n  end\n  conf.logger.level = Logger::DEBUG\nend\n```\n\n{% hint style=\"info\" %}\nNote that we pass the `AMBER_ENV` to `Jennifer::Config.read` this will allow Jennifer to use the correct database settings for the environment.\n{% endhint %}\n\n### Create a sam.cr in {project/src}\nAs mentioned previously, Jennifer uses Sam for running tasks pertinent to ORM operations. Sam is a Make-like utility which allows to specify tasks like Ruby's Rake do using plain Crystal. For how to use [Sam](https://github.com/imdrasil/sam.cr) visit the Github repository [https://github.com/imdrasil/sam.cr](https://github.com/imdrasil/sam.cr)\n\nCreate a new `sam.cr` file inside your project's `src` directory. \n\n```crystal\n# src/sam.cr\nrequire \"jennifer\"\nrequire \"jennifer/adapter/postgres\"\n\nrequire \"../config/jennifer\"\nrequire \"../db/migrations/*\"\nrequire \"sam\"\nrequire \"jennifer/sam\"\nload_dependencies \"jennifer\"\nSam.help\n```\n\nThis file operationalizes `sam` to begin running tasks. You can run `crystal sam.cr -- help` to get a list of available tasks once the file is added.\n\n### Including Jennifer in Server Bootstrap \nThe final step in configuration is to include Jennifer in your `src/{project}.cr` file. This should be done before you load your application configurations (or at least models). \n\n```crystal\nrequire \"jennifer\"\nrequire \"jennifer/adapter/postgres\"\n\nrequire \"amber\"\nrequire \"./controllers/**\"\nrequire \"./mailers/**\"\nrequire \"./models/**\"\nrequire \"./views/**\"\nrequire \"../config/*\"\n\nAmber::Server.instance.run\n```\n\nYou're all set with the configuration. Next using Jennifer Migrations and Models."}