Skip to content

Commit 2743a07

Browse files
authored
docs: Update ash_sqlite starting guide to clarify modifications in all files and fix the iex testing commands (#160)
1 parent 676c915 commit 2743a07

File tree

1 file changed

+84
-25
lines changed

1 file changed

+84
-25
lines changed

documentation/tutorials/getting-started-with-ash-sqlite.md

Lines changed: 84 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,10 @@ In this guide we will:
1212

1313
## Requirements
1414

15-
- A working SQLite installation, with a sufficiently permissive user
16-
- If you would like to follow along, you will need to add begin with [the Ash getting started guide](https://hexdocs.pm/ash/get-started.html)
15+
### Ash getting started guide
16+
If you would like to follow along, you will need to add begin with [the Ash getting started guide](https://hexdocs.pm/ash/get-started.html)
17+
### SQLite
18+
A working [SQLite](https://sqlite.org/) installation. Verify installation with `sqlite --version`
1719

1820
## Steps
1921

@@ -115,10 +117,12 @@ config :helpdesk, Helpdesk.Repo,
115117
pool_size: 10
116118
```
117119

118-
And finally, add the repo to your application
120+
add the repo to your application
119121

120122
```elixir
121-
# in lib/helpdesk/application.ex
123+
124+
125+
# in lib/helpdesk/application.ex (when the file is already exists)
122126

123127
def start(_type, _args) do
124128
children = [
@@ -130,6 +134,27 @@ And finally, add the repo to your application
130134
...
131135
```
132136

137+
If the application file does not exist you can create a new one
138+
139+
```elixir
140+
# in lib/helpdesk/application.ex (new file)
141+
142+
defmodule Helpdesk.Application do
143+
@moduledoc false
144+
145+
use Application
146+
147+
def start(_type, _args) do
148+
children = [
149+
Helpdesk.Repo
150+
]
151+
152+
opts = [strategy: :one_for_one, name: Helpdesk.Supervisor]
153+
Supervisor.start_link(children, opts)
154+
end
155+
end
156+
```
157+
133158
### Add AshSqlite to our resources
134159

135160
Now we can add the data layer to our resources. The basic configuration for a resource requires the `d:AshSqlite.sqlite|table` and the `d:AshSqlite.sqlite|repo`.
@@ -160,6 +185,21 @@ Now we can add the data layer to our resources. The basic configuration for a re
160185
end
161186
```
162187

188+
189+
And finaly link the application in your
190+
191+
```elixir
192+
# in mix.exs
193+
...
194+
def application do
195+
[
196+
mod: {Helpdesk.Application, []},
197+
...
198+
]
199+
end
200+
...
201+
```
202+
163203
### Create the database and tables
164204

165205
First, we'll create the database with `mix ash_sqlite.create`.
@@ -187,44 +227,58 @@ mix ash_sqlite.migrate
187227

188228
### Try it out
189229

190-
And now we're ready to try it out! Run the following in iex:
230+
And now we're ready to try it out! Start iex with:
231+
232+
```bash
233+
iex -S mix
234+
```
191235

192236
Lets create some data. We'll make a representative and give them some open and some closed tickets.
193237

194238
```elixir
195-
require Ash.Query
239+
#### Create the Representative
196240

197241
representative = (
198242
Helpdesk.Support.Representative
199243
|> Ash.Changeset.for_create(:create, %{name: "Joe Armstrong"})
200-
|> Helpdesk.Support.create!()
244+
|> Ash.create!()
201245
)
202246

203-
for i <- 0..5 do
247+
248+
#### Create 5 Tickets, Assign representative, and Close Odd Ones
249+
250+
for i <- 1..5 do
251+
# 1) open the ticket
204252
ticket =
205253
Helpdesk.Support.Ticket
206254
|> Ash.Changeset.for_create(:open, %{subject: "Issue #{i}"})
207-
|> Helpdesk.Support.create!()
255+
|> Ash.create!()
256+
257+
# 2) assign the representative
258+
ticket =
259+
ticket
208260
|> Ash.Changeset.for_update(:assign, %{representative_id: representative.id})
209-
|> Helpdesk.Support.update!()
261+
|> Ash.update!()
210262

211-
if rem(i, 2) == 0 do
263+
# 3) close if odd
264+
if rem(i, 2) == 1 do
212265
ticket
213-
|> Ash.Changeset.for_update(:close)
214-
|> Helpdesk.Support.update!()
266+
|> Ash.Changeset.for_update(:close, %{})
267+
|> Ash.update!()
215268
end
216269
end
217-
```
270+
271+
``
272+
218273

219274
And now we can read that data. You should see some debug logs that show the sql queries AshSqlite is generating.
220275

221276
```elixir
222277
require Ash.Query
223278

224-
# Show the tickets where the subject equals "foobar"
225279
Helpdesk.Support.Ticket
226-
|> Ash.Query.filter(subject == "foobar")
227-
|> Helpdesk.Support.read!()
280+
|> Ash.Query.filter(contains(subject, "2"))
281+
|> Ash.read!()
228282
```
229283

230284
```elixir
@@ -233,7 +287,7 @@ require Ash.Query
233287
# Show the tickets that are closed and their subject does not equal "barbaz"
234288
Helpdesk.Support.Ticket
235289
|> Ash.Query.filter(status == :closed and not(subject == "barbaz"))
236-
|> Helpdesk.Support.read!()
290+
|> Ash.read!()
237291
```
238292

239293
And, naturally, now that we are storing this in sqlite, this database is persisted even if we stop/start our application. The nice thing, however, is that this was the _exact_ same code that we ran against our resources when they were backed by ETS.
@@ -243,9 +297,14 @@ And, naturally, now that we are storing this in sqlite, this database is persist
243297
Simple calculation for Ticket which adds a concatenation of state and subject:
244298

245299
```
246-
calculations do
247-
calculate :status_subject, :string,
248-
expr("#{status}: #{subject}")
300+
# in lib/helpdesk/support/ticket.ex
301+
defmodule Helpdesk.Support.Ticket do
302+
...
303+
calculations do
304+
calculate :status_subject, :string,
305+
expr("#{status}: #{subject}")
306+
end
307+
249308
end
250309
```
251310

@@ -254,14 +313,14 @@ Testing of this feature can be done via iex:
254313
```
255314
Ash.Query
256315
Helpdesk.Support.Ticket
257-
|> Ash.Query.filter(status == :open)
258-
|> Ash.Query.load(:status_subject)
259-
|> Ash.read!()
316+
|> Ash.Query.filter(status == :open)
317+
|> Ash.Query.load(:status_subject)
318+
|> Ash.read!()
260319
```
261320

262321
### Aggregates
263322

264-
As stated in [what-is-ash-sqlite](https://hexdocs.pm/ash_sqlite/getting-started-with-ash-sqlite.html#steps),
323+
As stated in [what-is-ash-sqlite](https://hexdocs.pm/ash_sqlite/getting-started-with-ash-sqlite.html#steps),
265324
**The main feature missing is Aggregate support.**.
266325

267326
In order to use these consider using [ash_postgres](https://github.com/ash-project/ash_postgres) or

0 commit comments

Comments
 (0)