A simple CLI to keep MongoDB Atlas clusters alive by pinging them
npm install mongo-pingerbash
npx mongo-pinger setup
`
That's it! The interactive wizard will:
1. Ask for your preferred schedule (weekly/monthly/custom)
2. Let you pick the day and time
3. Generate a GitHub Actions workflow
4. Optionally commit and push to git
5. Show you exactly what to do next
$3
After setup, you'll have:
`
your-repo/
βββ .github/
βββ workflows/
βββ ping.yml # Auto-generated, ready to use
`
---
π Configuration
$3
The only manual step:
1. Go to your GitHub repo
2. Settings β Secrets and variables β Actions
3. Click "New repository secret"
4. Name: DATABASE_URI
5. Value: Your MongoDB connection string
`
mongodb+srv://username:password@cluster.mongodb.net/database
`
$3
`bash
git add .github/workflows/ping.yml
git commit -m "Add MongoDB pinger workflow"
git push
`
$3
- Go to the Actions tab in your GitHub repo
- Click "MongoDB Pinger"
- Click "Run workflow" to test manually
- β
You should see "MongoDB ping successful"
---
βοΈ Scheduling Options
The setup wizard supports three modes:
$3
Pick any day of the week. Perfect for free-tier clusters.
Example: Every Sunday at midnight UTC
`
Cron: 0 0 0
`
$3
Pick a day of the month (1-31). Great for low-traffic apps.
Example: 1st of every month at midnight UTC
`
Cron: 0 0 1
`
$3
Enter any valid cron expression for advanced scheduling.
Examples:
- 0 /12 - Every 12 hours
- 0 0 1-5 - Weekdays only at midnight
- /30 * - Every 30 minutes (overkill!)
Use crontab.guru to build custom expressions.
---
Testing Locally
Test your MongoDB connection before pushing:
`bash
With environment variable
DATABASE_URI='mongodb+srv://user:pass@cluster.mongodb.net/db' npx mongo-pinger
Or create a .env file
echo "DATABASE_URI=your_connection_string" > .env
npx mongo-pinger
`
Expected output:
`
β
MongoDB ping successful
`
---
π§ How It Works
1. GitHub Actions triggers on schedule (or manually)
2. Installs mongo-pinger from npm
3. Connects to your MongoDB cluster using mongoose
4. Pings the database with db.admin().ping()
5. Logs success or failure
6. Disconnects cleanly
The ping is lightweightβjust verifies the connection. No data is modified.
---
π Monitoring
$3
1. Go to your repo's Actions tab
2. Click "MongoDB Pinger" workflow
3. See all past runs with timestamps and results
$3
Settings β Notifications β GitHub Actions
- Get emails when pings fail
- Stay informed without checking manually
$3
The setup wizard shows you when the next ping will happen in UTC time.
---
π οΈ Advanced Usage
$3
Just run setup again:
`bash
npx mongo-pinger setup
`
Choose "Yes" when asked to overwrite the existing workflow.
$3
Besides the schedule, you can always run manually:
- GitHub Actions tab β MongoDB Pinger β Run workflow
$3
Create separate workflows for each database:
`bash
Rename the workflow in .github/workflows/
ping-production.yml # Uses DATABASE_URI_PROD
ping-staging.yml # Uses DATABASE_URI_STAGING
`
Then add multiple secrets with different names.
---
π Troubleshooting
$3
- β
Check the secret name is exactly DATABASE_URI (case-sensitive)
- β
Verify you added it in Settings β Secrets β Actions
- β
Make sure you're on the default branch (main or master)
$3
- β
Test connection locally first: DATABASE_URI='...' npx mongo-pinger
- β
Verify your connection string is correct
- β
Check MongoDB Atlas Network Access:
- Add 0.0.0.0/0 to whitelist GitHub Actions IPs
- Or enable "Allow access from anywhere"
$3
- β° GitHub Actions can delay 5-15 minutes during high load
- π
First scheduled run may not happen immediately after setup
- π€ Repos inactive for 60+ days have schedules disabled
- Fix: Make a commit to re-enable
$3
- π The new version uses npx mongo-pinger@latest (no build needed)
- π¦ If using an old workflow, run npx mongo-pinger setup again
---
π€ Contributing
Contributions are welcome! Here's how:
1. Fork the repo
2. Create a feature branch: git checkout -b feature/amazing
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing
5. Open a Pull Request
$3
`bash
Clone and install
git clone https://github.com/lankyjo/mongo-pinger.git
cd mongo-pinger
npm install
Build TypeScript
npm run build
Run locally
npm start
Run setup wizard
npm run setup
``