wheels db create
Create a new database based on your datasource configuration.
Synopsis
wheels db create [--datasource=<name>] [--environment=<env>] [--database=<dbname>] [--force]
Description
The wheels db create
command creates a new database using the connection information from your configured datasource. The datasource must already exist in your CFML server configuration - this command creates the database itself, not the datasource.
Options
datasource=
Specify which datasource to use. If not provided, uses the default datasource from your Wheels configuration.
wheels db create --datasource=myapp_dev
--environment=
Specify the environment to use. Defaults to the current environment (development if not set).
wheels db create --environment=testing
--database=
Specify the database name to create. Defaults to "wheels-dev" if not provided and not found in datasource configuration.
wheels db create --database=myapp_production
--force
Drop the existing database if it already exists and recreate it. Without this flag, the command will error if the database already exists.
wheels db create --force
Examples
Basic Usage
Create database using default datasource:
wheels db create
Specific Datasource
Create database for development:
wheels db create datasource=myapp_dev
Create database for testing:
wheels db create datasource=myapp_test --environment=testing
Custom Database Name
Create database with specific name:
wheels db create --database=myapp_v2
Force Recreation
Drop existing database and recreate:
wheels db create --force
Database-Specific Behavior
MySQL/MariaDB
Creates database with UTF8MB4 character set
Uses utf8mb4_unicode_ci collation
Connects without specifying a database initially
Supports MySQL 5.x, MySQL 8.0+, and MariaDB drivers
PostgreSQL
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
SQL Server
Creates database with default settings
Connects to
master
system databaseSupports Microsoft SQL Server JDBC driver
H2
Displays message that H2 databases are created automatically
No action needed - database file is created on first connection
Output Format
The command provides real-time, formatted output showing each step:
==================================================================
Database Creation Process
==================================================================
Datasource: myapp_dev
Environment: development
------------------------------------------------------------------
Database Type: MySQL
Database Name: myapp_development
------------------------------------------------------------------
>> Initializing MySQL database creation...
[OK] Driver found: com.mysql.cj.jdbc.Driver
[OK] Connected successfully to MySQL server!
>> Checking if database exists...
>> Creating MySQL database 'myapp_development'...
[OK] Database 'myapp_development' created successfully!
>> Verifying database creation...
[OK] Database 'myapp_development' verified successfully!
------------------------------------------------------------------
[OK] MySQL database creation completed successfully!
Prerequisites
⚠️ Note: This command depends on configuration values. Please verify your database configuration before executing it.
Datasource Configuration: The datasource must be configured in
/config/app.cfm
Database Privileges: The database user must have CREATE DATABASE privileges
Network Access: The database server must be accessible
JDBC Drivers: Appropriate JDBC drivers must be available in the classpath
Error Messages
"No datasource configured"
No datasource was specified and none could be found in your Wheels configuration. Use the datasource= parameter or set dataSourceName in settings.
"Datasource not found"
The specified datasource doesn't exist in your server configuration. Create it in your /config/app.cfm
first.
"Database already exists"
The database already exists. Use --force
flag to drop and recreate it:
wheels db create --force
"Access denied"
The database user doesn't have permission to create databases. Grant CREATE privileges to the user.
"Connection failed"
Common causes:
Database server is not running
Wrong server/port configuration
Invalid credentials
Network/firewall issues
For PostgreSQL: pg_hba.conf authentication issues
Configuration Detection
The command automatically detects datasource configuration from:
Environment-specific settings:
/config/[environment]/settings.cfm
General settings:
/config/settings.cfm
Datasource definitions:
/config/app.cfm
It extracts:
Database driver type
Connection string details
Host and port information
Username and password
Database name (if specified in connection string)
Related Commands
wheels db drop
- Drop an existing databasewheels db setup
- Create and setup databasewheels dbmigrate latest
- Run migrations after creating database
Last updated
Was this helpful?