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 database

  • Supports 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.

  1. Datasource Configuration: The datasource must be configured in /config/app.cfm

  2. Database Privileges: The database user must have CREATE DATABASE privileges

  3. Network Access: The database server must be accessible

  4. 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:

  1. Database server is not running

  2. Wrong server/port configuration

  3. Invalid credentials

  4. Network/firewall issues

  5. For PostgreSQL: pg_hba.conf authentication issues

Configuration Detection

The command automatically detects datasource configuration from:

  1. Environment-specific settings: /config/[environment]/settings.cfm

  2. General settings: /config/settings.cfm

  3. 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)

Last updated

Was this helpful?