<!-- README.md -->
<!-- version: 1.0 -->

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
<!-- markdown-toc end -->

# advotracker - database handling

`advotracker` will make use of Diesel to handle SQL access functions.
Diesel will requires Rust 1.24 or later.

# Diesel Setup

First of all, add the required dependencies to your projects Cargo.toml

```bash
[dependencies]
diesel = { version = "1.4.4", features = ["sqlite" "chrono"] }
dotenv = "0.15.0"
```

## CLI helper

Diesel provides a separete CLI tool to help manage the project.
This CLI should be installed on your system

```bash
cargo install diesel_cli
cargo install diesel_cli --no-default-features --features sqlite3
```

## Database location

We do uses `sqlite` for now. Use your distro package for sqlite3.

Now direct diesel to the correct database instance. We can create an
environment variable `DATABASE_URL`, that will point to the instance.
For the test setup, we take advantage of an .env file:

```.env
DATABASE_URL=sqlite://username:password@localhost/advotracker
#DATABASE_URL=postgres://username:password@localhost/advotracker
```

## Setup

When managing the database schema, it will evolve over the time.
Diesel takes that into account and supports a bundles called `Migrations`.
They allow us define states that can be applied (up.sql) or reverted (down.sql).
Applying and immediately reverting a migration should leave your database schema unchanged.

```bash
diesel setup
diesel migration generate advotracker
```

The call will create the needed structure with as a subfolder `migrations`,
holding a timstamp based subfolder with the migration name and to empty files.
You'll see output that looks something like this:

```bash
Creating migrations/20200625133000_advotracker/up.sql
Creating migrations/20200625133000_advotracker/down.sql
```

We can apply our new migration:

```bash
diesel migration run
```

To test out, that our sql scripts are working out as expected try the `redo`
function. This will drop the given schema and create a new one using the
adopted files in the migration path.

```bash
diesel migration run
```

Further infomation can be optained from [Diesel's project page][^1].

---

[Logo-CC_BY]: https://i.creativecommons.org/l/by/4.0/88x31.png "Creative Common Logo"
[License-CC_BY]: https://creativecommons.org/licenses/by/4.0/legalcode "Creative Common License"
This work is licensed under a [Creative Common License 4.0][License-CC_BY]

![Creative Common Logo][Logo-CC_BY]

© 2020 Ralf Zerres, Networkx GmbH

---

Foodnotes

[^1]: Diesel Guides:  https://diesel.rs/guides/getting-started/