This is the repository of my lecture materials for databases course at
AGH University.  Jupyter notebooks are used for presenting, one per
topic, with topic sizes varying (some occupy exactly a single 1.5 h
lecture slot, some less or more).  Even though I give lectures in
polish, I try to make the materials reusable and prepare them in
english (except the notebook with organizational information, which is
course-specific anyway).  AGH students, please pardon me ¯\_(ツ)_/¯.

## Getting the files

Note: in the examples in this README, the `$' character precedes a
command to type in the terminal.  Some of the commands have their
sample output shown below.

You might have downloaded or viewed this README through a web browser.
It is, however, also possible (and more convenient!) to clone the
entire git repository with the necessary files, as shown below.

    $ git clone https://galaxy.agh.edu.pl/~wkosior/git.sh/db-lectures
    Cloning into 'db-lectures'...
    remote: Enumerating objects: 16, done.
    remote: Counting objects: 100% (16/16), done.
    remote: Compressing objects: 100% (12/12), done.
    remote: Total 16 (delta 4), reused 16 (delta 4), pack-reused 0
    Receiving objects: 100% (16/16), 17.90 KiB | 8.95 MiB/s, done.
    Resolving deltas: 100% (4/4), done.

Afterwards, you can update your checkout as make changes to the
lecture materials.

    $ cd /path/to/cloned/db-lectures
    $ git reset --hard # resets local file changes, not always needed
    HEAD is now at 5675f68 Initial commit.
    $ git pull
    remote: Enumerating objects: 12, done.
    remote: Counting objects: 100% (12/12), done.
    remote: Compressing objects: 100% (8/8), done.
    remote: Total 8 (delta 5), reused 0 (delta 0), pack-reused 0
    Unpacking objects: 100% (8/8), 3.49 KiB | 1.16 MiB/s, done.
    From https://galaxy.agh.edu.pl/~wkosior/git.sh/db-lectures
       5675f68..163170e  magister   -> origin/magister
    Updating 5675f68..163170e
    Fast-forward
     01-introduction-to-databases/set_students_2.sh |  11 ++-
     01-introduction-to-databases/set_students_3.sh |  11 ++-
     COPYING                                        | 123 +++++++++++++++++++++++++++++++++
     3 files changed, 143 insertions(+), 2 deletions(-)
     create mode 100644 COPYING

## Running the notebooks

Each topic has a single directory starting with a 2-digit number.
Topic's directory contains a single version-controlled notebook file
and possibly some other resources next to it.  The following are
needed to run the code in some or all of the notebooks (the list might
grow in the future).

- a web browser
- the Jupyter Notebook application
- the ipython-sql Python package
- the psycopg2 Python package
- a Postgres server
  - listening at IP address 127.0.0.1 (address at which a system sees
    itself)…
  - …at TCP port 25432,
  - with database `agh_it_northwind', and
  - with all privileges to this database granted to user `demo_user'
    authenticated with password `demo_pwd'
- the Wget program
- basic POSIX utilities (cat, sha256sum, etc.)
- (optionally) the xdg-open program to facilitate automatically
  opening your default web browser and image viewer

Tech-savvy users will want to install these by themselves, possibly
adapting the db connection URLs to their setup.  This is entirely
possible, just not documented here.

For others, there is a `run-jupyter.sh' shell script that can be run
under systems based on the Linux kernel.  It uses GNU Guix package
manager to spawn a container with Postgres, Wget and all the Python
stuff set up more or less like on my machines.  If possible, the
script shall open the Jupyter app in your web browser.  If GNU Guix is
missing on your system, the script will detect that and direct you to
install it.  If your version of Guix is too old (and, e.g., lacks
ipython-sql), it will use a time machine to travel into the future and
invoke a newer Guix for you 😉.

The drawback of this approach is that spinning up a container with
Guix can consume up to a few GBs of disk space.  It can also take a
few or more minutes on the first run.  Fortunately, subsequent
invocations of `run-jupyter.sh' are faster.

## Giving feedback

If you either encounter problems running the `run-jupyter.sh' script,
have issues with one of the notebooks or just want to make a
suggestion, please reach out to me at wkosior@agh.edu.pl.

## Other scripts here

At the root of the repository there are `clear-outputs.sh',
`make-noteless.sh', and `make-notes.sh' scripts that I wrote for my
own use.  You do not have to use them to merely view the lecture
materials nor to run the examples.  These scripts are also not
hardened against running on systems other than mine, you have been
warned.

- `clear-outputs.sh' clears cell outputs in notebook files.
- `make-noteless.sh' removes markdown cells starting with `_notes_'
  from notebooks and places the resulting .ipynb files next to their
  originals.  These noteless notebooks are what I use when presenting
  in front of the audience.
- `make-notes.sh' extracts notes from the aforementioned note cells,
  extracts headings from other markown cells and writes all these to
  .md files next to their .ipynb sources.

## Licensing

See the `COPYING' file.