PostgreSQL と PostgREST のラボ：ブラウザーで学ぶデータベースと REST API

このラボは、各生徒に専用の PostgreSQL データベースと専用の PostgREST を渡します。PostgREST は、データベースのすべてのテーブルを REST API にします。2つの隣にあるターミナルには psql と curl があり、生徒は SQL でテーブルを作り、HTTP でそれを読み書きします。

compose ファイル1つでできており、自分のマシンでも動きます。

生徒が学ぶこと

テーブルを作ること、そしてサービス名でデータベースに接続すること。本番環境でサービス同士が互いを見つけるのと同じ方法です。curl を使い、絞り込みや並べ替えも含めて REST API で行を読み書きすること。再起動で残るものと残らないもの：データベースは名前付きボリュームにファイルを置くので、ノートは次回もそのまま残りますが、ボリューム以外に書いたファイルはラボが停止すると消えます。pg_dump でバックアップし、そのファイルから復元すること。

ブラウザーで動かす

まず自分で試してみてください。データベースユーザー shop のパスワードは shop です。

  1. コンテナーのページを開く. バーの「つくる」を開き、「コンテナーを実行」を選びます。ページは誰でも開けて、Git ラボと SQL ラボはアカウントなしで起動できます。ほかのラボには無料アカウントが必要です。アカウントを作成してサインインし、「起動」を押します。
  2. ラボを探す. 「サンプルラボ」のカードにすべてのサンプルが並んでいます。Web API 付きのデータベースを探します。
  3. 「起動」を押す. 「起動」はそのまま1回の操作で実行します。「先にファイルを編集」は compose ファイルを開くので、起動する前に変更できます。
  4. 開く. ラボのページの「ブラウザーで」で「すべてのテーブルに付く Web API」を押し、テーブルを作ったらアドレスに /notes を付けます。ターミナルでは、psql -h db -U shop でデータベースが開き、curl http://api:3000/notes で API を呼び出せます。

GitHub のコード

ラボ全体が、公開リポジトリにある compose ファイル1つです。リポジトリには、このラボのために書かれた授業の内容も、手順ごとに載っています。自分のマシンでも docker compose up で動きます。フォークして自分のものにしてください。

このラボの基本レッスン

API Basics と API Basics 2 は、このラボで進める小さなレッスンで、各手順に説明と、生徒のターミナルにコマンドを入力する「実行」ボタンが付いています。API Basics ではテーブルを作り、メモを1件入れ、curl で Web 越しに読み、POST リクエストで1件追加します。API Basics 2 ではメモを変更し、1件削除し、API が返すステータスコードを読み取ります。

無料の個人アカウントには、ホームにある Basics モジュールで配布されます。どの学校もライブラリの Basics フォルダから自分のモジュールにコピーでき、新しい学校ではサンプルモジュールの Lab Basics (Sample) に入っています。どちらも意図的に小さくしてあり、ラボで進めるレッスンとは何かを教員に見せるためのもので、残りはラボが担います。変更したい場合は、どちらかを自分のモジュールにコピーしてください。

課題として出す

クラスに出すには、リポジトリから自分のラボを作ります。

  1. ラボを作る. モジュールで課題を追加し、「コンテナーラボ」のカードを選んでから「GitHub リポジトリ」を選びます。https://github.com/mitsurutech/lab-sample とブランチ main を指定します。compose ファイルは既定の compose.yaml です。変更したい場合は、先にリポジトリをフォークしてください。
  2. 公開して試す. 「公開」すると、確認したコミットに固定されるので、あとでリポジトリを変更しても、すでに出したラボは変わりません。まず自分のコピーを起動してください。
  3. 配布する. ほかの課題と同じように配布します。期限を付けることもでき、課題には何をするか、何を提出するかを書いておきます。
  4. 提出物を採点する. 生徒のコピーを開いて提出された内容を確認し、採点します。足りない場合は理由を書いて差し戻します。

よくある質問

PostgREST とは何ですか？
Postgres データベースを読み取り、各テーブルを REST エンドポイントにする小さなサーバーです。生徒は自分で書かなくても、データベースが Web API の裏でどう動くかを見られます。ラボは、生徒ごとに専用の Postgres の隣でこれを動かします。
データはセッションをまたいで保存されますか？
はい。データベースは名前付きボリューム pgdata にファイルを置き、プラットフォームがそれを保存します。これは生徒のホームフォルダーも同じです。ボリューム以外のものは、本番環境のコンテナーと同じく、ラボが停止すると消えます。
このラボで、生徒はデータベースと API にどう接続しますか？
ターミナルで psql -h db -U shop を実行するとデータベースが開き、パスワードは shop です。テーブルを作ったあとは curl http://api:3000/notes で notes を読めます。どちらも、本番でサービス同士が見つけ合うのと同じように、サービス名で接続します。