Skip to main content

Synopsis

Create a new ChameleonDB project with schema files and configuration.

Description

Initializes a ChameleonDB project by creating:
  • .chameleon.yml - Main configuration file
  • .chameleon/ - Admin directory (config, state, journal, backups)
  • schemas/ - Directory for schema files
  • schemas/example.cham - Example schema to get started
  • README.md - Getting started guide
If a project name is provided, creates a new directory. Otherwise, initializes in the current directory.

Arguments

string
Project name. Creates a new directory with this name.If omitted, initializes in the current directory.

Examples

Initialize in New Directory

Output:

Initialize in Current Directory

Output:

Created Files

.chameleon.yml

Main configuration file:

schemas/example.cham

Starter schema with blog example:

.chameleon/ Structure

Behavior

Already Initialized

If .chameleon.yml already exists:
Error:

Directory Creation

When creating a new project directory:
  • Creates my-app/ directory
  • Sets up all files inside
  • Reports error if directory already exists with .chameleon.yml

After Initialization

1. Set Database Connection

Or edit .chameleon.yml:

2. Edit Schema

Modify schemas/example.cham or create new schema files:

3. Run First Migration

This will:
  • Auto-initialize Schema Vault
  • Register schema as v001
  • Apply migration to database
  • Set vault to readonly mode (default)
Protects mode upgrades from readonly to standard/privileged/emergency.

Version Control

Commit to Git:
  • .chameleon.yml
  • schemas/
  • README.md
Add to .gitignore:
The Schema Vault (.chameleon/vault/) should generally be ignored in version control, as it’s auto-generated during migrations. However, some teams may choose to commit it for additional auditability.

Troubleshooting

Permission Denied

Or ensure you have write permissions in the target directory.

Cannot Create Directory

Ensure parent directory exists:

See Also