Introduction

So far in this series, we’ve explored how the Wheels CLI in 3.x helps you inspect your application, manage configuration, and control environments safely. Now we’re moving into something even more foundational: database lifecycle management.

Your application might have clean code and perfectly aligned environments — but without a properly provisioned database, nothing works. In a Wheels application, the database is not just storage. It powers:

• Migrations
• Application data
• Session handling
• Background jobs
• Automated tests
• API responses

It’s core infrastructure. And whether you’re:

• Setting up a new project
• Onboarding a teammate
• Preparing a staging server
• Resetting a development database
• Cleaning up after automated CI tests

You’ll eventually need to create or drop a database. Traditionally, this meant:

• Logging into the database server manually
• Running raw SQL commands
• Managing permissions
• Double-checking you weren’t targeting production
• Repeating the same setup steps across environments

It was manual. It was inconsistent. And sometimes — risky.

Wheels CLI simplifies this by using your existing environment and datasource configuration to manage database provisioning directly from your project root safely.

That’s where these two powerful commands come in:

wheels db create
wheels db drop

Simple in appearance. Powerful in impact.

Why Database CLI Commands Matter

Traditionally, creating or dropping databases meant:

• Logging into SQL Server / MySQL / PostgreSQL manually
• Running SQL scripts
• Managing permissions
• Copying credentials
• Risking mistakes

In team environments, this creates friction:

• “What’s the correct database name?”
• “Which server do I connect to?”
• “Is this staging or production?”
• “Did I just drop the wrong database?”

The Wheels CLI eliminates this confusion by using your existing environment configuration. It knows:

• Your datasource
• Your database name
• Your environment
• Your credentials

And it acts accordingly.

wheels db create

Create a Database Instantly wheels db create

This command creates the configured database for your active environment. It reads:

• Environment settings
• Datasource configuration
• Database name
• Connection credentials

Then it provisions the database automatically.

When to Use db create New Project Setup:

wheels environment show
wheels db create

Your local database is ready — no manual SQL required.

Onboarding a Team Member: Instead of sending setup documentation with SQL instructions:

“Just run wheels db create.”

It standardizes project setup.

Automated Test Environments: In CI pipelines:

wheels db create

The database is created dynamically for testing. After tests complete, it can be dropped cleanly.

What Happens Behind the Scenes: The command:

1. Connects to your DB server
2. Checks whether the database exists
3. Creates it if missing
4. Validates permissions
5. Confirms success

It respects your current environment.

That means: If you are in development → It creates the development DB. If you are in staging → It creates the staging DB.

No cross-environment confusion.

wheels db drop

Drops the configured database. This command permanently deletes a database. This is a destructive operation that cannot be undone.

wheels db drop

This command drops the database for the active environment.

Used carefully, it’s extremely powerful. Used recklessly, it’s dangerous.

That’s why environment awareness is critical.

When to Use db drop Resetting Development: Need a clean slate?

wheels db drop
wheels db create

Now you have a fresh database. Perfect for schema resets or major refactors.

Rebuilding After Migration Changes: If migrations changed significantly:

wheels db drop
wheels db create
wheels db migrate latest

You’re back to a fully rebuilt database.

CI/CD Cleanup: In automated pipelines:

wheels db drop

Removes temporary test databases after completion.

Safety First: Environment Awareness Before running db drop, always confirm your environment:

wheels environment show

Dropping a production database accidentally is catastrophic. That’s why best practice is:

1. Confirm environment
2. Validate settings
3. Then execute database commands

Example Safe Workflow

Step 1 – Confirm Environment wheels environment show

Step 2 – Validate Environment wheels environment validate

Step 3 – Drop (if safe) wheels db drop

Step 4 – Recreate wheels db create

This structured process prevents irreversible mistakes.

Real-World Development Scenarios

Scenario 1: Local Development Reset You’ve been experimenting with schema changes. Your database is messy. Instead of manually cleaning tables:

wheels db drop
wheels db create

Clean slate. Fresh start. Zero manual SQL.

Scenario 2: Staging Server Preparation Before pushing new features:

wheels environment switch staging
wheels db create

Ensures staging DB exists and matches configuration.

Scenario 3: Automated Testing Your CI workflow:

wheels environment set testing
wheels db create
wheels test run
wheels db drop

Fully automated lifecycle. No manual intervention.

How These Commands Improve Team Workflows

They:

• Standardize database setup
• Reduce onboarding friction
• Eliminate manual SQL steps
• Prevent configuration mismatches
• Support automated pipelines
• Encourage safe environment practices

In modern development, repeatability matters. These commands make database setup repeatable.

The Bigger Philosophy

Earlier CLI tools focused on scaffolding code. Wheels 3.x CLI is evolving into:

• An environment manager
• A configuration validator
• A deployment assistant
• A database lifecycle controller

Applications aren’t just code. They are infrastructure + configuration + environments + data. Managing databases via CLI is a natural evolution.

Important Best Practices

Before using database commands:

• Always confirm environment
• Never drop production unless intentional
• Use validation commands
• Automate in CI when possible
• Keep credentials secure

Treat database commands with respect. They’re powerful by design.

Conclusion

The new database commands in Wheels CLI 3.x simplify one of the most critical parts of application management.

wheels db create → Instantly provision databases wheels db drop → Cleanly remove databases

Together, they:

• Speed up development
• Simplify onboarding
• Enable automation
• Support safe workflows
• Reduce manual SQL tasks

If scaffolding commands help you build faster…

Environment commands help you deploy safer…

These database commands help you reset, rebuild, and automate smarter. And in modern development, controlled data management is everything.

Stay tuned — more Wheels CLI deep dives are coming.

Learn more here: https://youtu.be/HYXg5CtxrYQ