Create a new database based on your datasource configuration.
The wheels db create command creates a new database using the connection information from your configured datasource. If the datasource doesn't exist, the command offers an interactive wizard to create it for you, supporting MySQL, PostgreSQL, SQL Server, Oracle, H2, and SQLite databases.
Automatic .env file reading: Reads actual database credentials from .env.{environment} files using generic DB_* variable names
Interactive datasource creation: Prompts for credentials when datasource doesn't exist
Environment validation: Checks if environment exists before prompting for credentials
Examples:
Create database using default datasource:
Characteristics:
Embedded database - no server required
Database file created automatically on first connection
Only prompts for database name and optional credentials
No host/port configuration needed
Example Commands:
Characteristics:
Lightweight file-based database - serverless and zero-configuration
Database file created immediately (unlike H2's lazy creation)
Creates database file with metadata table: wheels_metadata
Database stored at: ./db/database_name.db
Example Commands:
Output Example:
Common Issues:
"Could not delete existing database file": The database file is locked. Stop the server (box server stop) and close any database tools.
"File permission error": Ensure write permissions on the application root directory.
"Database file was not created": Check disk space and directory permissions.
Characteristics:
Creates database with UTF8MB4 character set
Uses utf8mb4_unicode_ci collation
Connects to information_schema system database
Supports MySQL 5.x, MySQL 8.0+, and MariaDB drivers
Example Commands:
Output Example:
Characteristics:
Creates database with UTF8 encoding
Uses en_US.UTF-8 locale settings
Terminates active connections before dropping (when using --force)
Connects to postgres system database
Example Commands:
Special Notes:
When using --force, the command automatically terminates active connections before dropping the database
Check pg_hba.conf if you encounter authentication issues
Characteristics:
Creates database with default settings
Connects to master system database
Supports Microsoft SQL Server JDBC driver
Default port: 1433
Example Commands:
Characteristics:
Creates a USER/schema (Oracle's equivalent of a database)
Grants CONNECT and RESOURCE privileges automatically
Connects using SID (e.g., FREE, ORCL, XE)
Supports Oracle 12c+ with Container Database (CDB) architecture
Example Commands:
Oracle JDBC Driver Installation:
If you see "Driver not found" error, you need to manually install the Oracle JDBC driver:
Download the driver from
Download ojdbc11.jar or ojdbc8.jar
Place the JAR file in CommandBox's JRE library directory:
Common Oracle Errors:
"Invalid Oracle identifier": Database name contains hyphens. Use underscores instead.
"ORA-65096: common user must start with C##": Either use C##MYAPP as the database name or grant additional privileges to the connecting user.
"ORA-28014: cannot drop administrative user": Don't use system usernames (SYS, SYSTEM, etc.).
If the specified datasource doesn't exist, the command will prompt you to create it interactively:
The datasource will be saved to both /config/app.cfm and CFConfig.json.
⚠️ Note: This command depends on configuration values. Please verify your database configuration before executing it.
Datasource Configuration: The datasource can be configured in /config/app.cfm or created interactively
Database Privileges: The database user must have CREATE DATABASE privileges (CREATE USER for Oracle, not applicable for H2/SQLite)
Network Access: The database server must be accessible (not applicable for H2/SQLite file-based databases)
No datasource was specified and none could be found in your Wheels configuration. Use the datasource= parameter or set dataSourceName in settings.
The specified datasource doesn't exist in your server configuration. The command will prompt you to create it interactively.
Oracle JDBC driver is not installed in CommandBox.
Fix: See the section above for detailed installation instructions.
The database already exists. Use --force flag to drop and recreate it:
The database user doesn't have permission to create databases. Grant CREATE privileges to the user.
Common causes:
Database server is not running
Wrong server/port configuration
Invalid credentials
Network/firewall issues
For Oracle errors, see the section for detailed information on:
"Invalid Oracle identifier": Use underscores instead of hyphens
"ORA-65096: common user must start with C##": Use C## prefix or grant privileges
"ORA-28014: cannot drop administrative user": Don't use system usernames (SYS, SYSTEM, etc.)
For SQLite errors, see the section for detailed information on:
"Could not delete existing database file": Database is locked. Stop server and close database tools
"File permission error": Check write permissions on application root
"Database file was not created": Verify disk space and permissions
The command intelligently detects datasource configuration from multiple sources:
.env.{environment} file (highest priority - NEW!)
Reads actual credential values using generic DB_* variable names
Example: DB_HOST=localhost, DB_USER=sa,
Database driver type (MySQL, PostgreSQL, MSSQL, Oracle, H2)
Connection details:
Host and port
Database name
All database types now use consistent DB_* variable names in .env files:
This makes it easy to switch database types without changing variable names.
- Drop an existing database
- Create and setup database
- Run migrations after creating database
wheels db create [--datasource=<name>] [--environment=<env>] [--database=<dbname>] [--dbtype=<type>] [--force]Smart error handling: Single, clear error messages without duplication
Post-creation setup: Automatically creates environment files and writes datasource to app.cfm after successful database creation
dbtype
string
Auto-detected
Database type: h2, sqlite, mysql, postgres, mssql, oracle. If not specified, the command will prompt you to select a type when creating a new datasource.
force
boolean
false
Drop the existing database if it already exists and recreate it. Without this flag, the command will error if the database already exists.
Ideal for development and testing
JDBC Driver included with Lucee/CommandBox
Automatically creates db directory if it doesn't exist
No username/password required (file-based authentication)
No host/port configuration needed
JDBC driver: org.sqlite.JDBC (org.xerial.sqlite-jdbc bundle v3.47.1.0)
Creates auxiliary files during operation:
database.db-wal (Write-Ahead Log)
database.db-shm (Shared Memory)
database.db-journal (Rollback Journal)
Use absolute paths - paths are stored absolutely in configuration
Ideal for development, testing, prototyping, and portable applications
Limitations: Single writer, not recommended for high-concurrency production
Default port: 3306
JDBC Driver included with Lucee/CommandBox
Default port: 5432
JDBC Driver included with Lucee/CommandBox
Default username: sa
JDBC Driver included with Lucee/CommandBox
Uses _ORACLE_SCRIPT session variable for non-C## users
Important: Database names cannot contain hyphens (use underscores)
Default port: 1521
Default SID: FREE (Oracle XE)
Requires manual JDBC driver installation (see below)
Windows: path\to\CommandBox\jre\lib\
Mac/Linux: /usr/local/lib/CommandBox/jre/lib/
Restart CommandBox completely:
Important: Close ALL CommandBox instances (don't just reload)
This ensures the JDBC driver is properly loaded
Verify installation:
You should see: [OK] Driver found: oracle.jdbc.OracleDriver
MySQL, PostgreSQL, MSSQL, H2, and SQLite drivers are included with CommandBox/Lucee by default
Oracle requires manual driver installation - see Oracle Database section for details
File Permissions (SQLite/H2 only): Write permissions required in application root directory
For Oracle: TNS listener not running or incorrect SID
DB_PASSWORD=MyPass123!Solves the issue where app.cfm contains unresolved placeholders like ##this.env.DB_HOST##
Datasource definitions in /config/app.cfm
Falls back to parsing connection strings if .env file doesn't exist
Maintains backward compatibility
Environment-specific settings: /config/[environment]/settings.cfm
Detects datasource name from set(dataSourceName="...")
General settings: /config/settings.cfm
Global datasource configuration
Username and password
Oracle SID (if applicable)
datasource
string
Current datasource
Specify which datasource to use. If not provided, uses the default datasource from your Wheels configuration.
environment
string
Current environment
Specify the environment to use. Defaults to the current environment (development if not set).
database
string
wheels_dev
Specify the database name to create. Note for Oracle: Database names cannot contain hyphens. Use underscores instead (e.g., myapp_dev not myapp-dev).
wheels db create datasource=myOracleDS# Use specific datasource
wheels db create --datasource=myapp_dev
# Specify environment
wheels db create --environment=testing
# Custom database name
wheels db create --database=myapp_production
# Specify database type
wheels db create --dbtype=postgres --database=myapp_dev
# Force recreation
wheels db create --forcewheels db create# Using existing datasource
wheels db create datasource=myapp_dev
# Specify environment
wheels db create --environment=testing
# Custom database name
wheels db create --database=myapp_v2
# Force recreation (drop and recreate)
wheels db create --force# Basic H2 database
wheels db create --dbtype=h2 --database=myapp_dev
# With specific environment
wheels db create --dbtype=h2 --database=myapp_test --environment=testing
# Force recreate
wheels db create --dbtype=h2 --database=myapp_dev --force# Basic SQLite database
wheels db create --dbtype=sqlite --database=myapp_dev
# Force recreate SQLite database
wheels db create --dbtype=sqlite --database=myapp_dev --force
# With specific environment
wheels db create --dbtype=sqlite --database=myapp_test --environment=testing[OK] SQLite JDBC driver loaded
[OK] Database connection established
[OK] Database schema initialized
[OK] Database file created: D:\MyApp\db\myapp_dev.db
[OK] File size: 16384 bytes
SQLite database created successfully!# Basic MySQL database
wheels db create --dbtype=mysql --database=myapp_dev
# With specific environment
wheels db create --dbtype=mysql --database=myapp_production --environment=production
# With custom datasource name
wheels db create --dbtype=mysql --database=myapp_test --datasource=test_db --environment=testing
# Force recreate
wheels db create --dbtype=mysql --database=myapp_dev --force==================================================================
Database Creation Process
==================================================================
Datasource: myapp_dev
Environment: development
------------------------------------------------------------------
Database Type: MySQL
Database Name: myapp_dev
------------------------------------------------------------------
>> Initializing MySQL database creation...
[OK] Driver found: com.mysql.cj.jdbc.Driver
[OK] Connected successfully to MySQL server!
>> Creating MySQL database 'myapp_dev'...
[OK] Database 'myapp_dev' created successfully!
>> Verifying database creation...
[OK] Database 'myapp_dev' verified successfully!
------------------------------------------------------------------
[OK] MySQL database creation completed successfully!# Basic PostgreSQL database
wheels db create --dbtype=postgres --database=myapp_dev
# With specific environment
wheels db create --dbtype=postgres --database=myapp_staging --environment=staging
# Force recreate (automatically terminates active connections)
wheels db create --dbtype=postgres --database=myapp_dev --force
# Custom datasource
wheels db create --dbtype=postgres --database=myapp_prod --datasource=prod_db --environment=production# Basic SQL Server database
wheels db create --dbtype=mssql --database=myapp_dev
# With specific environment
wheels db create --dbtype=mssql --database=myapp_production --environment=production
# With custom datasource
wheels db create --dbtype=mssql --database=MyAppDB --datasource=production_ds
# Force recreate
wheels db create --dbtype=mssql --database=myapp_dev --force# Basic Oracle database (creates user/schema)
wheels db create --dbtype=oracle --database=myapp_dev
# With specific environment
wheels db create --dbtype=oracle --database=myapp_prod --environment=production
# Force recreate (drops and recreates user)
wheels db create --dbtype=oracle --database=myapp_dev --force
# IMPORTANT: Use underscores, not hyphens
wheels db create --dbtype=oracle --database=myapp_test # ✓ Correct
# wheels db create --dbtype=oracle --database=myapp-test # ✗ Wrong! Will failDatasource 'myapp_dev' not found in server configuration.
Would you like to create this datasource now? [y/n]: y
=== Interactive Datasource Creation ===
Select database type:
1. MySQL
2. PostgreSQL
3. SQL Server (MSSQL)
4. Oracle
5. H2
6. SQLite
Select database type [1-6]: 1
Selected: MySQL
Enter connection details:
Host [localhost]:
Port [3306]:
Database name [wheels_dev]: myapp_dev
Username [root]:
Password: ****
Review datasource configuration:
Datasource Name: myapp_dev
Database Type: MySQL
Host: localhost
Port: 3306
Database: myapp_dev
Username: root
Connection String: jdbc:mysql://localhost:3306/myapp_dev
Create this datasource? [y/n]: ywheels db create --forceDB_TYPE=mssql # Database type
DB_HOST=localhost # Host (not MSSQL_HOST)
DB_PORT=1433 # Port (not MSSQL_PORT)
DB_DATABASE=wheels_dev # Database name (not MSSQL_DATABASE)
DB_USER=sa # Username (not MSSQL_USER)
DB_PASSWORD=Pass123! # Password (not MSSQL_PASSWORD)
DB_DATASOURCE=wheels_dev⚠️ Note: This command depends on configuration values. Please verify your database configuration before executing it.
Drop an existing database.
The wheels db drop command permanently deletes a database. This is a destructive operation that cannot be undone. By default, it requires confirmation unless the --force flag is used.
Examples:
Drop database with confirmation:
Drop without confirmation:
Drop file-based SQLite database:
Output:
If server is running, it will automatically stop and retry:
Confirmation Required: By default, you must type "yes" to confirm
Production Warning: Extra warning when dropping production databases
Clear Messaging: Shows database name and environment before dropping
Uses DROP DATABASE IF EXISTS statement
Connects to information_schema to execute command
Automatically handles active connections
Terminates existing connections before dropping
Uses DROP DATABASE IF EXISTS statement
Connects to postgres system database
Sets database to single-user mode to close connections
Uses DROP DATABASE IF EXISTS statement
Connects to master system database
Drops USER/schema (Oracle's equivalent of a database)
Uses DROP USER ... CASCADE to remove all objects
Supports Oracle 12c+ with Container Database (CDB) architecture
Uses _ORACLE_SCRIPT
Deletes database files (.mv.db, .lock.db, .trace.db)
Shows which files were deleted
No server connection required
File-based deletion - removes database and auxiliary files
Deletes main database file (.db extension)
Automatically deletes auxiliary files:
.db-wal (Write-Ahead Log)
This operation is irreversible! Always ensure you have backups before dropping a database.
Always backup first:
Use --force carefully: Only in scripts where you're certain
Double-check environment: Especially important for production
The database doesn't exist. No action needed.
The database user doesn't have permission to drop databases. Grant DROP privileges to the user.
Some databases prevent dropping while connections are active. The command attempts to close connections automatically.
Database name contains invalid characters. Oracle usernames can only contain letters, numbers, and underscores.
Fix: Use underscores instead of hyphens:
The Oracle user/schema doesn't exist. No action needed.
Attempting to drop an Oracle system user. System users like SYS, SYSTEM, ADMIN, XDB cannot be dropped.
Fix: Verify you're targeting the correct database. System users are protected and cannot be removed.
The SQLite database file cannot be deleted because it's currently in use.
Fix:
The command will automatically attempt to:
Detect if the server is running
Stop the server
Retry deletion up to 5 times
Wait 1 second between retries
If the error persists:
Close any database tools (DB Browser for SQLite, etc.)
Check if another process has the file open
Wait a few seconds and try again
The SQLite database file doesn't exist at the expected location.
This is normal if:
The database was already dropped
The database was never created
A different database path is configured
No action needed.
The database file remains locked even after stopping the server.
Fix:
Wait 10-30 seconds for Windows to release the file handle
Close any open database management tools
Check Task Manager for lingering processes
Try the command again
- Create a new database
- Drop and recreate database
- Backup before dropping
wheels db drop [--datasource=<name>] [--environment=<env>] [--database=<dbname>] [--force]force
boolean
false
Skip the confirmation prompt. Useful for scripting.
Important: Database names cannot contain hyphens (use underscores)
Cannot drop system users (SYS, SYSTEM, ADMIN, XDB, etc.)
.db-shm (Shared Memory)
.db-journal (Rollback Journal)
Handles file locking automatically:
Detects if application server is running
Stops server automatically if file is locked
Retries deletion up to 5 times with 1-second delays
Provides clear error messages if deletion fails
Recommendation: Stop server before dropping: box server stop
No network connection required (file-based)
Clean output with minimal messages
datasource
string
Current datasource
Specify which datasource's database to drop. If not provided, uses the default datasource from your Wheels configuration.
environment
string
Current environment
Specify the environment to use. Defaults to the current environment.
database
string
wheels_dev
Specify the database name to drop. Note for Oracle: Database names cannot contain hyphens. Use underscores instead (e.g., myapp_dev not myapp-dev).
# Use specific datasource
wheels db drop --datasource=myapp_dev
# Specify environment
wheels db drop --environment=testing
# Custom database name
wheels db drop --database=myapp_test
# Force drop without confirmation
wheels db drop --forcewheels db drop
# Will prompt: Are you sure you want to drop the database 'myapp_dev'? Type 'yes' to confirm:wheels db drop --forcewheels db drop --datasource=myapp_test --environment=testing --force# Using existing datasource
wheels db drop --datasource=myapp_dev
# With confirmation prompt
wheels db drop --datasource=sqlite_app[WARN] WARNING: This will permanently drop the database!
Are you sure you want to drop the database 'D:\MyApp\db\myapp_dev.db'? Type 'yes' to confirm: yes
[OK] SQLite database dropped successfully![WARN] Server is running - stopping it to release database lock...
[OK] SQLite database dropped successfully!wheels db dump --output=backup-before-drop.sql
wheels db drop# Wrong
wheels db drop --database=my-app-dev
# Correct
wheels db drop --database=my_app_dev# Stop the server first
box server stop
# Wait a moment for file handles to release
# Then try again
wheels db drop