Hack@Brown Database Starter Kit - Setup Guide

This guide will walk you through setting up your database backend step-by-step.

Before You Start

Make sure you have:

Node.js installed (version 18 or higher)
A text editor (VS Code recommended)
Terminal/command line access

Choose Your Database

This starter kit includes three options:

MongoDB - For flexible, document-based data
PostgreSQL - For advanced SQL features and JSONB support
MySQL - For traditional relational databases

Not sure? Start with PostgreSQL - it's the most versatile.

Setup Instructions (Pick ONE database)

PostgreSQL Setup

Step 1: Create Your Project Folder

# Navigate to where you want your project
cd ~/Documents

# Create and enter your project folder
mkdir my-hack-brown-project
cd my-hack-brown-project

Step 2: Copy Starter Files

# Create the folder structure
mkdir -p database config models routes controllers middleware scripts

# Copy files from the postgresql/ folder in this starter kit:
# - Copy postgresql/database.js → your-project/config/
# - Copy postgresql/userModel.js → your-project/models/
# - Copy postgresql/projectModel.js → your-project/models/
# - Copy postgresql/schema.sql → your-project/database/
# - Copy postgresql/seed.sql → your-project/database/
# - Copy postgresql/testConnection.js → your-project/scripts/
# - Copy postgresql/package.json → your-project/
# - Copy postgresql/.env.example → your-project/
# - Copy postgresql/.gitignore → your-project/

Step 3: Install Dependencies

npm install

Step 4: Set Up Your Database

Option A: Cloud Database (Recommended - No Docker needed)

Go to https://supabase.com
Click "Start your project"
Create a free account
Click "New project"
Fill in project details (remember your password!)
Wait for database to be ready (1-2 minutes)
Click "Connect" → "Node.js"
Copy the connection string

Then in your project:

# Copy the example env file
cp .env.example .env

# Open .env in your text editor and paste your connection string
# It should look like:
# DATABASE_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres

Option B: Local Database with Docker

# Start PostgreSQL in Docker
docker run -d \
  --name postgres-hackatbrown \
  -e POSTGRES_PASSWORD=hackatbrown123 \
  -e POSTGRES_DB=hackatbrown \
  -e POSTGRES_USER=hackatbrown \
  -p 5432:5432 \
  postgres:15

# Create .env file
echo "DATABASE_URL=postgresql://hackatbrown:hackatbrown123@localhost:5432/hackatbrown" > .env
echo "PORT=3000" >> .env

Step 5: Test Your Connection

npm run test-connection

You should see:

[+] PostgreSQL Connected Successfully!
[Database icon] Database: hackatbrown (or your database name)

If you see an error, check:

Is your .env file in the project root?
Did you copy the connection string correctly?
For cloud: Is your database still starting up? Wait a minute and try again.

Step 6: Create Tables and Add Sample Data

npm run db:setup

This command will:

Create 3 tables (users, projects, project_collaborators)
Add indexes for performance
Insert 5 sample users
Insert 8 sample projects

Step 7: Start Your Server

npm start

You should see:

Server running on port 3000
[+] PostgreSQL Connected Successfully!

Step 8: Test It Works!

Open your browser and visit:

http://localhost:3000/api/users - See all users
http://localhost:3000/api/projects - See all projects

You should see JSON data!

MySQL Setup

Follow the same steps as PostgreSQL, but:

Use the mysql/ folder files instead
For cloud, use https://planetscale.com instead of Supabase
Docker command is different:

docker run -d \
  --name mysql-hackatbrown \
  -e MYSQL_ROOT_PASSWORD=hackatbrown123 \
  -e MYSQL_DATABASE=hackatbrown \
  -e MYSQL_USER=hackatbrown \
  -e MYSQL_PASSWORD=hackatbrown123 \
  -p 3306:3306 \
  mysql:8.0

MongoDB Setup

Step 1: Create Your Project Folder

# Navigate to where you want your project
cd ~/Documents

# Create and enter your project folder
mkdir my-hack-brown-project
cd my-hack-brown-project

Step 2: Copy Starter Files

# Create the folder structure
mkdir -p config models routes controllers middleware scripts

# Copy files from the mongodb/ folder in this starter kit:
# - Copy mongodb/database.js → your-project/config/
# - Copy mongodb/userModel.js → your-project/models/
# - Copy mongodb/projectModel.js → your-project/models/
# - Copy mongodb/package.json → your-project/
# - Copy mongodb/.env.example → your-project/
# - Copy mongodb/.gitignore → your-project/

Step 3: Install Dependencies

npm install

Step 4: Set Up Your Database

Option A: Cloud Database (Recommended - No Docker needed)

Go to https://mongodb.com/cloud/atlas
Click "Try Free" or "Sign In"
Create a free account
Click "Build a Database"
Choose "M0 FREE" tier
Select a cloud provider and region (closest to you)
Click "Create"
Create a database user:
- Username: hackatbrown
- Password: Create a secure password (save it!)
- Click "Create User"
Add your IP address:
- Click "Add My Current IP Address"
- Or for development, add 0.0.0.0/0 (allows all IPs)
- Click "Finish and Close"
Click "Connect" → "Drivers"
Copy the connection string

Then in your project:

# Copy the example env file
cp .env.example .env

# Open .env in your text editor and paste your connection string
# Replace <password> with your actual password
# It should look like:
# DATABASE_URL=mongodb+srv://hackatbrown:<password>@cluster0.xxxxx.mongodb.net/hackatbrown?retryWrites=true&w=majority

Option B: Local Database with Docker

# Start MongoDB in Docker
docker run -d \
  --name mongo-hackatbrown \
  -e MONGO_INITDB_ROOT_USERNAME=hackatbrown \
  -e MONGO_INITDB_ROOT_PASSWORD=hackatbrown123 \
  -p 27017:27017 \
  mongo:latest

# Create .env file
echo "DATABASE_URL=mongodb://hackatbrown:hackatbrown123@localhost:27017/hackatbrown?authSource=admin" > .env
echo "PORT=3000" >> .env

Step 5: Test Your Connection

npm run test-connection

You should see:

[+] MongoDB Connected Successfully!
Database: hackatbrown

If you see an error, check:

Is your .env file in the project root?
Did you copy the connection string correctly?
For cloud: Did you whitelist your IP address?
For cloud: Did you replace <password> with your actual password?

Step 6: Seed Sample Data (Optional)

npm run db:seed

This command will:

Insert 5 sample users
Insert 8 sample projects

Step 7: Start Your Server

npm start

You should see:

Server running on port 3000
[+] MongoDB Connected Successfully!

Step 8: Test It Works!

Open your browser and visit:

http://localhost:3000/api/users - See all users
http://localhost:3000/api/projects - See all projects

You should see JSON data!

Understanding the Project Structure

After setup, your project looks like this:

my-hack-brown-project/
├── .env                      # YOUR database connection (never commit!)
├── .env.example              # Template (safe to commit)
├── .gitignore                # Tells git what not to upload
├── package.json              # Lists dependencies and scripts
│
├── database/
│   ├── schema.sql           # Creates tables (run once)
│   └── seed.sql             # Adds sample data (run once)
│
├── config/
│   └── database.js          # Database connection setup
│
├── models/
│   ├── userModel.js         # User database operations
│   └── projectModel.js      # Project database operations
│
├── scripts/
│   └── testConnection.js    # Test if database works
│
└── (you'll add these next:)
    ├── routes/              # API endpoints
    ├── controllers/         # Business logic
    ├── middleware/          # Error handling
    └── server.js            # Main app file

What Each File Does

database.js (in config/)

Connects to your database
Provides a query() function to run SQL
Handles connection pooling for performance

userModel.js (in models/)

Functions to work with users
getAllUsers() - Get all users
getUserById(id) - Get one user
createUser(data) - Add a new user
updateUser(id, data) - Change user info
deleteUser(id) - Remove a user
searchUsers(query) - Find users

projectModel.js (in models/)

Similar to userModel but for projects
Includes advanced features like search and filtering

Common Commands

# Install dependencies
npm install

# Test database connection
npm run test-connection

# Set up database (creates tables and adds data)
npm run db:setup

# Reset database (WARNING: deletes all data!)
npm run db:reset

# Start the server
npm start

# Start with auto-restart on file changes (if you have nodemon)
npm run dev

Next Steps

Now that your database is running:

Test the API - Open http://localhost:3000/api/users in your browser
Read the starter guide - Open PostgreSQL_Starter.md or MySQL_Starter.md for:
- All available API endpoints
- How to query the database
- Security best practices
- Deployment instructions
Build your routes - Create route files to define your API endpoints
Build your frontend - Connect React/Vue/etc to your API

Getting Help

Connection problems?

Run npm run test-connection to diagnose
Check your .env file is in the project root
Verify DATABASE_URL is correct
For cloud databases, check if IP whitelist is set to allow all (0.0.0.0/0)

Tables not created?

Make sure npm run db:setup completed without errors
Check that schema.sql and seed.sql are in database/ folder
Verify your database user has permission to create tables

Port 3000 already in use?

Edit .env and change PORT=3000 to PORT=3001
Or stop the other process using port 3000

Still stuck?

Check the troubleshooting section in your database's starter guide
Search the error message online
Ask a mentor at Hack@Brown!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Hack@Brown Database Starter Kit - Setup Guide

Before You Start

Choose Your Database

Setup Instructions (Pick ONE database)

PostgreSQL Setup

MySQL Setup

MongoDB Setup

Understanding the Project Structure

What Each File Does

database.js (in config/)

userModel.js (in models/)

projectModel.js (in models/)

Common Commands

Next Steps

Getting Help

FilesExpand file tree

setup_guide.md

Latest commit

History

setup_guide.md

File metadata and controls

Hack@Brown Database Starter Kit - Setup Guide

Before You Start

Choose Your Database

Setup Instructions (Pick ONE database)

PostgreSQL Setup

MySQL Setup

MongoDB Setup

Understanding the Project Structure

What Each File Does

database.js (in config/)

userModel.js (in models/)

projectModel.js (in models/)

Common Commands

Next Steps

Getting Help