gator

gator is a small CLI RSS aggregator and reader. It uses Postgres for storage, Goose for migrations, and SQLC to generate type-safe Go database bindings.

This README explains how to install, configure, and run the CLI locally for development and how to install the compiled gator binary for everyday use.

Quick links

• Migrations: sql/schema
• Queries: sql/queries

Requirements

• Go (see go.mod): Go 1.26.1 is used in this repo. Any recent Go version should work.
• PostgreSQL (local or remote) — you need a database to store feeds, posts and users.
• Optional utilities: goose (migrations), sqlc (SQL->Go generator), and jq (handy for extracting JSON fields).

Install developer tools

Install goose (migrations) and sqlc (SQL->Go generator):

go install github.com/pressly/goose/v3/cmd/goose@latest
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest

You can verify them with:

goose -version
sqlc version

Setup Postgres

Create a database for development (example):

# create DB (Linux/macOS)
createdb gator
# or inside psql:
# CREATE DATABASE gator;

Create a config file at ~/.gatorconfig.json with your connection string (include ?sslmode=disable for local Postgres):

{
  "db_url": "postgres://postgres:postgres@localhost:5432/gator?sslmode=disable"
}

You can test the connection with psql:

psql "$(jq -r .db_url ~/.gatorconfig.json)"

Apply database migrations

Run the Goose migrations (from the repo root):

cd sql/schema
DB_URL="$(jq -r .db_url ~/.gatorconfig.json)"
goose postgres "$DB_URL" up

To reset for tests you can run:

goose postgres "$DB_URL" down
goose postgres "$DB_URL" up

Generate DB bindings (sqlc)

If you change SQL files, regenerate Go bindings:

sqlc generate

Build / Install the CLI

For development you can run with go run:

go run . <command>

To build a local binary:

go build -o gator .
# then run `./gator ...` or move it into your PATH

To install the CLI from GitHub (after pushing), run:

go install github.com/simonproyt/gator@latest

After go install the binary will be placed in your GOBIN (or $GOPATH/bin).

Common commands

Usage examples (development):

# create a user named lane
go run . register lane

# login as lane (saves to ~/.gatorconfig.json)
go run . login lane

# add a feed (adds and auto-follows)
go run . addfeed "Boot.dev Blog" "https://www.boot.dev/blog/index.xml"

# follow an existing feed URL
go run . follow "https://www.boot.dev/blog/index.xml"

# unfollow
go run . unfollow "https://www.boot.dev/blog/index.xml"

# list feeds
go run . feeds

# list users
go run . users

# list feeds you follow
go run . following

# browse recent posts (default 2)
go run . browse [limit]

# aggregator (runs forever, fetching feeds every 1m)
go run . agg 1m

# reset database (dangerous: drops users and cascades)
go run . reset

Notes:

• agg is a long-running collector; stop with Ctrl+C.
• reset deletes users (and their feeds/follows) — use only for local development.

Pushing to GitHub

When you're ready to publish your code:

git remote add origin https://github.com/simonproyt/gator.git
git push -u origin main

Then others can install with:

go install github.com/simonproyt/gator@latest

Replace simonproyt with your GitHub username if you fork or move the repo.

Troubleshooting

• If the CLI fails to connect, ensure db_url in ~/.gatorconfig.json is correct and Postgres is running.
• For local Postgres use ?sslmode=disable in the connection string.
• If SQLC or Goose commands fail, ensure you've installed them with go install and that $GOBIN or $GOPATH/bin is on your PATH.

Contributing

Contributions welcome — open a PR. Please run sqlc generate after changing SQL files and add migrations under sql/schema.

---

Generated by the gator development helper.