You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: guides/models/README.md
+4-3
Original file line number
Diff line number
Diff line change
@@ -1,16 +1,17 @@
1
1
# Models
2
2
3
-
Amber is independent of your choice of model architectures. We \(Core members\) have built the ORM **Granite**. We also think **Jennifer** built by [Roman Kalnytskyi](https://github.com/imdrasil) is a good option.
3
+
The default ORM for Amber is [**Granite**](https://github.com/amberframework/granite), a lightweight Crystal ORM with adapters for MySQL, PostgreSQL and SQLite. Although Granite is the default configuration, the Amber framework supports alternate ORMs such as [**Jennifer**](https://github.com/imdrasil/jennifer.cr) built by [Roman Kalnytskyi](https://github.com/imdrasil) is a good option.
4
4
5
5
## Granite
6
6
7
-
Granite provides a light weight ORM that is focused on taking the results of your query and mapping them to your model. It does not try to shield you from the SQL that lies underneath the mapping. It provides a couple conveniences like `save` and `destroy` for simple INSERT, UPDATE and DELETE statements. It provides `find`, `find_by` and `all` to query the database. It also has basic one-to-many relationships with `belong_to` and `has_many`.
7
+
Granite provides a light weight ORM that is focused on taking the results of your query and mapping them to your model. It does not try to shield you from the SQL that lies underneath the mapping. Out of the box, Granite provides the several common search, read and write methods for your models such as `save`, `find_by`, `destroy`, _etc_, that map onto standard SQL INSERT, UPDATE and DELETE statements. Granite also supports basic one-to-many relationships with `belong_to` and `has_many` macros that will be familiar to developers experienced with ActiveRecord.
Jennifer provides an more full featured ORM with a full featured DSL for queries and follows the ActiveRecord pattern found in Rails. If you are looking for a full featured ORM, Jennifer may be your choice of ORM.
14
+
Jennifer is a full featured ORM with a dedicate DSL that follows the ActiveRecord pattern found in Rails closely. If you are looking for a more full featured ORM Jennifer is a great choice.
Copy file name to clipboardExpand all lines: guides/models/jennifer/README.md
+51-13
Original file line number
Diff line number
Diff line change
@@ -2,49 +2,82 @@
2
2
3
3
## What is Jennifer?
4
4
5
-
**Jennifer** is an ActiveRecord pattern for Crystal with great query DSL and migration mechanism.
5
+
**Jennifer** is an ActiveRecord-like ORM for Crystal with a custom DSL for queries and migrations.
6
6
7
7
{% hint style="info" %}
8
8
This 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).
9
9
{% endhint %}
10
10
11
11
## Installing Jennifer for Amber
12
+
By default, Amber applications ship with
13
+
[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.
12
14
13
15
### Generate a normal amber app
16
+
Begin by generating a new amber project (if you have not already).
14
17
15
-
```text
18
+
```bash
16
19
amber new {project}
20
+
cd project
17
21
```
18
22
19
23
### Update your project shard.yml
24
+
Once your Amber project is created, you will need to update your `shard.yml` file to include Jennifer as a dependency.
20
25
21
-
Add this to your application's
26
+
Add the following code snippet to your application's`shard.yml` file:
22
27
23
28
```yaml
24
-
#Add the following dependencies
29
+
#Jennifer is an ORM
25
30
jennifer:
26
31
github: imdrasil/jennifer.cr
27
32
33
+
# SAM is a CLI utility for running migrations, creating or dropping tables
28
34
sam:
29
35
github: imdrasil/sam.cr
36
+
37
+
```
38
+
39
+
In 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.
40
+
41
+
Once 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.
42
+
43
+
```yaml
44
+
# snipped shards
45
+
46
+
# Your choice of database adapter
47
+
48
+
# PostgreSQL
49
+
pg:
50
+
github: will/crystal-pg
51
+
version: "= 0.21.0"
52
+
53
+
# MySQL
54
+
crystal-mysql:
55
+
github: crystal-lang/crystal-mysql
56
+
version: "= 0.11.0"
30
57
```
31
58
32
-
> Choose one of existing adapters for your db: [mysql](https://github.com/crystal-lang/crystal-mysql) or [postgres](https://github.com/will/crystal-pg).
59
+
You can read about the Crystal community adapters below:
Once you have updated your dependencies and chosen an appropriate adapter (if any), proceed to update your project's shards by running:
65
+
66
+
```bash
37
67
shards update
38
68
```
39
69
70
+
This command will begin installing Jennifer and its associated dependencies into your Amber project.
71
+
40
72
### Setup your database information
73
+
Once 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:
41
74
42
75
```yaml
43
76
defaults : &defaults
44
77
host: localhost
45
78
adapter: postgres
46
-
user: root
47
-
password: somepassword
79
+
user: <add-your-database-user>
80
+
password: <add-your-database-password>
48
81
migration_files_path: db/migrations # this is the default location for all migrations
49
82
50
83
development:
@@ -56,7 +89,10 @@ test:
56
89
<<: *defaults
57
90
```
58
91
59
-
### Create a **jennifer.c**r under the **/config** directory
92
+
The `config/database.yml` describes the various databases Jennifer will use in your project's different environments.
93
+
94
+
### Add A Jennifer Initializer to Configuration
95
+
With 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.
60
96
61
97
```ruby
62
98
require "amber"
@@ -79,8 +115,9 @@ Note that we pass the `AMBER_ENV` to `Jennifer::Config.read` this will allow Jen
79
115
{% endhint %}
80
116
81
117
### Create a sam.cr in {project/src}
118
+
As 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)
82
119
83
-
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)
120
+
Create a new `sam.cr` file inside your project's `src` directory.
84
121
85
122
```ruby
86
123
# src/sam.cr
@@ -95,9 +132,10 @@ load_dependencies "jennifer"
95
132
Sam.help
96
133
```
97
134
98
-
### Edit your src/{project}.cr file
135
+
This 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.
99
136
100
-
This should be done before you load your application configurations \(or at least models\). With Amber this is very easy.
137
+
### Including Jennifer in Server Bootstrap
138
+
The 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).
0 commit comments