Two environments,
one machine.

The Foundation

Before installing anything, you need two tools that everything else depends on: Homebrew and a basic understanding of the Terminal.

The Terminal — the black window that does everything

The Terminal is just a text-based way to talk to your Mac. Instead of clicking, you type a command and press Enter. That's it. Here are the only five commands you need to know:

Installing Homebrew

Homebrew is a package manager — think of it as an App Store for the Terminal. Most developer tools are installed through it. Open the Terminal and paste this:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the prompts. It will ask for your Mac password. When it's done, verify it works:

brew --version

You should see something like Homebrew 4.x.x. That means it's ready.

Running SQL directly on your files

DuckDB is a database engine that runs directly inside VS Code — no server, no setup, no running process in the background. You point it at a file, and you can query it with SQL immediately. It is extremely fast and handles files up to several gigabytes without issues.

Installing the extension

1. Open the Extensions panel in VS Code

   Press Cmd + Shift + X or click the Extensions icon in the left sidebar.

2. Search for "DuckDB" and install the Charlie Jonas version

   It shows 12,000+ installs and version 0.0.27. Click Install.

3. Reload VS Code when prompted

   A small reload button will appear after installation. Click it.

Creating a database and loading data

A DuckDB database is just a single file on your Mac with the extension .db. You create it by connecting to a filename that doesn't exist yet — DuckDB creates it automatically.

1. Open your project folder in VS Code

   Use File → Open Folder and navigate to your project directory.

2. Select your database

   Press Cmd + Shift + P, type DuckDB: Select Database, then choose Attach Existing and navigate to your .db file. If you don't have one yet, choose Create New Database.

3. Load a CSV file into the database

   Create a new file called queries.sql and paste this, adjusting the file path and table name:

-- Load a CSV file into a new table called "retailers"
CREATE TABLE retailers AS
SELECT * FROM read_csv_auto('/absolute/path/to/your/file.csv');

-- Check what was loaded
SELECT * FROM retailers LIMIT 5;

To run the query, place your cursor anywhere inside it and press Cmd + Shift + P → DuckDB: Run Statement at Cursor. A results panel will open with your data.

{
    "key": "shift+enter",
    "command": "duckdb.runStatementAtCursor",
    "when": "editorTextFocus && editorLangId == 'sql'"
}

Visual dashboards on your machine

Metabase is a dashboarding tool — it turns your data into charts and interactive reports without writing any code. It runs in a web browser, but the server runs locally on your Mac inside Docker.

What is Docker?

Think of Docker as a way to run a fully self-contained mini-computer inside your Mac. That mini-computer has its own operating system, its own programs, and its own file system. Metabase runs inside one of these containers, completely isolated from the rest of your Mac. You start it with one command and stop it with one command.

Make sure Docker Desktop is running before proceeding — you should see the Docker icon in your menu bar.

Starting Metabase

Replace /Users/yourname/your-project-folder with the actual path to your project folder on your Mac:

docker run -d \
  -p 3000:3000 \
  -v /Users/yourname/your-project-folder:/data \
  --name metabase \
  metabase/metabase

This command tells Docker to start Metabase, make it available on port 3000, and map your local project folder to /data inside the container.

1. Open Metabase in your browser

   Navigate to http://localhost:3000. The first start takes about 60 seconds.

2. Create your admin account

   Fill in your name, email, and a password. This is just for local access — it doesn't connect to anything external.

3. Connect your DuckDB database

   When asked to add a database, select DuckDB. For the database path, enter /data/go_explore.db — this is the path inside the container, not on your Mac.

4. Start exploring

   Metabase will scan your tables. You can now build charts and dashboards by clicking through the interface — no SQL required, though you can use it if you prefer.

Accessing the shared team project

BigQuery is Google's cloud database service. Your team's data lives there, and multiple people can query it simultaneously from anywhere. The simplest way to access it is directly in the browser.

https://console.cloud.google.com/bigquery?project=mystical-proj-500509

Bookmark this URL. Once you open it, you will see the project's datasets and tables in the left panel. Click on any table to preview its contents, or click Query to open a SQL editor.

Connecting from your Mac directly

Instead of using the browser, you can query BigQuery directly from your Mac — through the Terminal, through a Python script, or through a Jupyter Notebook. This requires installing Google's command-line tools and authenticating once.

Step 1 — Install the Google Cloud SDK

The Google Cloud SDK is a collection of command-line tools for working with Google Cloud services. Install it via Homebrew:

brew install google-cloud-sdk

Step 2 — Log in

This command opens a browser window where you log in with your Google account. After logging in, close the browser — your Terminal is now authenticated.

gcloud auth application-default login

Step 3 — Set the project

Tell gcloud which project you want to work with:

gcloud config set project mystical-proj-500509

Step 4 — Install the Python package

This package lets Python talk to BigQuery:

pip3 install google-cloud-bigquery --break-system-packages

Step 5 — Run your first query

Verify everything works with this test query:

python3 -c "
from google.cloud import bigquery
client = bigquery.Client(project='mystical-proj-500509')
result = client.query("""
    SELECT Country, COUNT(*) AS stores
    FROM go_explore_project.retailers
    GROUP BY Country
    ORDER BY stores DESC
    LIMIT 5
""")
for row in result:
    print(row)
"

You should see the top 5 countries by store count printed in your Terminal. If this works, your connection is fully set up.

Interactive analysis in a Notebook

A Jupyter Notebook lets you write code in small blocks called cells and run each one individually. Results appear directly below the cell — tables, charts, numbers. It is the most comfortable way to explore data interactively.

Installing the required packages

pip3 install jupyter pandas --break-system-packages

Starting a Notebook in VS Code

Create a new file with the extension .ipynb in VS Code. It will open as a Notebook automatically. Each cell can contain Python code. Press Shift + Enter to run a cell and move to the next one.

Querying BigQuery from a Notebook

Paste this into the first cell and run it. After that, every cell can contain a pure SQL query:

from google.cloud import bigquery

client = bigquery.Client(project='mystical-proj-500509')

def bq(sql):
    """Run a BigQuery SQL query and return a table."""
    return client.query(sql).to_dataframe()

bq("""
    SELECT
        r.Country,
        SUM(s.Quantity * s.Unit_sale_price) AS Total_Revenue
    FROM go_explore_project.daily_sales AS s
    JOIN go_explore_project.retailers AS r
        ON s.Retailer_code = r.Retailer_code
    GROUP BY r.Country
    ORDER BY Total_Revenue DESC
""")

The result appears as a formatted table directly below the cell. You are now running SQL against the shared team dataset from your own machine, with results rendered locally.