Skip to content

Enhance initial-setup README with additional Docker & PGAdmin instructions #305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+36 −28
Open

Enhance initial-setup README with additional Docker & PGAdmin instructions #305

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 36 additions & 28 deletions bootcamp/materials/1-dimensional-data-modeling/README.md
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Quality

The code quality in this pull request is strong, focusing on enhancing the documentation with clear, concise steps for utilizing Docker and PGAdmin. The use of markdown for formatting and instructive comments makes the steps easy to follow.

Changes

  • Enhanced README with detailed instructions for setting up Postgres and PGAdmin using Docker.
  • Added visual aids (image) and step-by-step descriptions to avoid user confusion.
  • Segregated Docker setup instructions emphasizing best practices.

Creator Fairness

The changes made by the author are well-considered and add significant value to the documentation, focusing on user experience enhancement. The contributions are clear, fair, and complement the existing documentation without redundancy.

Merge Recommendation

This pull request should be merged as it provides well-drafted, detailed documentation improvements that will aid developers in setting up their environment consistently and correctly.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the review, Zach!
I've rebased my branch to bring in the latest change where there was a significant refactor and the readme became much clearer (good work, Rahul). I reviewed both versions and determined re-ordering how to install PostgreSQL, plus reincorporating some of my original doc tweaks will ensure new developers have a painless experience.

Original file line number Diff line number Diff line change
Expand Up @@ -40,27 +40,7 @@ cd data-engineer-handbook/bootcamp/materials/1-dimensional-data-modeling

### Step 2️⃣: Start PostgreSQL

#### 🧩 Option A: Local Installation (Manual Setup)

1. Install PostgreSQL
- [Mac – use Homebrew](https://brew.sh/)
- [Windows – official installer](https://www.postgresql.org/download/)

2. Restore the sample database:

```bash
pg_restore -c --if-exists -U <your-username> -d postgres data.dump
```

If that fails, try:

```bash
pg_restore -U [username] -d [db_name] -h [host] -p [port] data.dump
```

---

#### 🐳 Option B: Docker (Simplest & Preferred)
#### 🐳 Option A: Docker (Simplest & Preferred)

1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
2. Copy the env template:
Expand All @@ -69,6 +49,8 @@ pg_restore -U [username] -d [db_name] -h [host] -p [port] data.dump
cp example.env .env
```

> The `.env` file stores credentials used by PostgreSQL and PGAdmin
3. Start PostgreSQL & PGAdmin in containers:

```bash
Expand All @@ -93,6 +75,26 @@ docker compose stop

---

#### 🧩 Option B: Local Installation (Manual Setup)

1. Install PostgreSQL
- [Mac – use Homebrew](https://brew.sh/)
- [Windows – official installer](https://www.postgresql.org/download/)

2. Restore the sample database:

```bash
pg_restore -c --if-exists -U <your-username> -d postgres data.dump
```

If that fails, try:

```bash
pg_restore -U [username] -d [db_name] -h [host] -p [port] data.dump
```

---

### Step 3️⃣: Connect to PostgreSQL

Choose any GUI tool you like. Here’s how:
Expand All @@ -102,14 +104,20 @@ Choose any GUI tool you like. Here’s how:
1. Go to [http://localhost:5050](http://localhost:5050)
2. Log in using the credentials from your `.env` file
3. Create a new server:
- **Name**: Name of your choice
- **Host**: `my-postgres-container`
- **Port**: `5432`
- **Database**: `postgres`
- **Username**: `postgres`
- **Password**: `postgres`
- ✅ Save Password
1. `Dashboard` ➜ `Quick Links` ➜ `Add New Server`
2. Under the `General` tab: give it a friendly `Name`, e.g. `Data-Engineer-Handbook-DB`
3. `Connection` tab: Copy in credentials from `.env`, where the defaults are:
- **Name**: Name of your choice
- **Host**: `my-postgres-container`
- **Port**: `5432`
- **Database**: `postgres`
- **Username**: `postgres`
- **Password**: `postgres`
- ✅ Save Password
4. Click **Save** — and you’re connected!
5. Expand `Servers` › *`your-server`* › `Databases` › `postgres`
- The database must be highlighted to be able to open the `Query Tool`
- Further expanding `postgres` › `Schemas` › `public` › `Tables` should show the expected content

---

Expand Down