Repository navigation
Caligrafer Data Commands
The data commands of Caligrafer work on the
database and the files the framework keeps for speed: sql runs a script, migrate runs and writes migrations,
platform install creates the framework tables, cache clear empties the cache, and env compiles .env.
/caligrafy-quill:db add an isbn column to books
The db skill finds the database of .env (the Docker mysql container or a local MySQL), writes a migration with
migrate make, runs it, and shows the tables. It also runs create_db.sql scripts and fixes [ERROR 2003] and
"table doesn't exist" errors.
Check before you say OK: php caligrafer.php migrate status shows the new migration as ran, and
php caligrafer.php doctor --only database has no FAIL.
A new project's tables, then a change to a table that holds data:
docker compose exec dev-box php caligrafer.php platform install
docker compose exec dev-box php caligrafer.php sql application/models/Bookshelf/create_db.sql
docker compose exec dev-box php caligrafer.php migrate make add_books_isbn
# write the ALTER TABLE in application/migrations/<YmdHis>_add_books_isbn.sql, then:
docker compose exec dev-box php caligrafer.php migrate(without Docker, drop docker compose exec dev-box). Every command here reads the database of .env
(DB_ACTIVATE=true and the DB_* settings), or of another file with --env <file>.
Usage: php caligrafer.php sql <file.sql>
php caligrafer.php sql application/models/Bookshelf/create_db.sql
php caligrafer.php sql application/models/Bookshelf/create_db.sql --env .env.testing application/models/Bookshelf/create_db.sql run on caligrafy
- It removes the
/* ... */comments and the lines that start with--, splits the rest on;and runs each statement. - A failure prints
<file> could not be run: <reason>and exits with1; the statements before it stay applied. - Without
DB_ACTIVATE=true:The database is not active: set DB_ACTIVATE=true and the DB_* settings in .env. - Use it for the tables of a new database, and for a script the deploy step refused to run again because it drops or deletes data. A change to a table that holds data is a migration.
Usage: php caligrafer.php migrate [status | make <name>] [--env <file>]
Runs the migrations of application/migrations that never ran on this database
php caligrafer.php migrate make add_books_isbn # writes application/migrations/<YmdHis>_add_books_isbn.sql
php caligrafer.php migrate # runs the ones that never ran, in order
php caligrafer.php migrate status # ran, pending or changed
php caligrafer.php migrate --env .env.testing # on the database of another settings file (2.19.1)make <name> needs no database. The name is lower-cased, and anything but letters and digits becomes _. The file
starts with two comment lines:
-- add_books_isbn
-- Runs once (php caligrafer.php migrate, and at every deploy). Never edit it after it ran: write a new one.migrate runs, in number order, every file that never ran on this database, and records it in
caligrafy_migrations (its name, its sha256 and when):
OK 20261107232335_add_books_isbn.sql
1 migration(s) run on caligrafy
With nothing to run: Nothing to migrate: caligrafy is up to date. A file edited after it ran is not run again:
WARN <file>: changed after it ran, not run again (write a new migration for the change).
status prints one line per file:
ran 20261107232335_add_books_isbn.sql (2026-11-07 23:23:35)
pending 20261108090000_add_loans_due_on.sql
| State | Means |
|---|---|
ran |
it ran on this database, and the file is what ran |
pending |
it never ran: the next migrate runs it |
changed |
it ran, and the file was edited since: it never runs again |
- A file is named
<number>_<name>.sql(up to 14 digits); any other.sqlfile in the folder stops the command with the name it expects. Two files with the same number stop it too. - The statements of a file are split on
;outside quotes and comments. A file stops at its first failing statement, which the error names (<file>, statement 2: ...): it is not recorded, and what ran before it stays (MySQL commits aCREATEorALTERat once). Keep one change per file, or write it so that it can run again. - Forward only: undo a change with a new migration.
-
--env <file>can come anywhere aftermigrate. Errors go to standard error, with exit code1. - The deploy step runs the pending ones at each start in production.
Learn more in Migrations and
Caligrafy\Migrations.
Usage: php caligrafer.php platform install
Creates the framework tables (tokens, audit log, job runs, notifications, jobs, cache, migrations, Snap) from framework/settings/platform.sql
Framework tables ready: caligrafy_tokens, caligrafy_audit, caligrafy_job_runs, the notifications tables, caligrafy_jobs, caligrafy_cache, caligrafy_migrations and Snap's tables
It runs framework/settings/platform.sql, which creates each table only when it is missing: safe to run again, and
needed after an update that adds tables. quickstart and the deploy step run it. On failure:
The framework tables could not be created: <reason> and Check DB_ACTIVATE and the DB_* settings in .env (php caligrafer.php doctor --only database),
exit code 1.
Usage: php caligrafer.php cache clear
Empties the cache (Caligrafy\Cache, CACHE_STORE in .env), the compiled views and the class map
Cache (database) emptied; 2 compiled view and class map file(s) removed
- The cache of
Caligrafy\Cachein its store (CACHE_STORE: thecaligrafy_cachetable by default withDB_ACTIVATE=true, else private files). With the file store it says how many values it removed (Cache (file) emptied: 3 value(s); ...). - The compiled Pug views and the class map of this user, in the temporary folder.
- Run it after copying files that keep their old modification times (
rsync -a,cp -p): a view can look older than its compiled copy (G117). - The web server and the command line are different users: with
CACHE_STORE=fileeach has its own folder, and the command line empties only its own (G119).
Learn more in Caching.
Usage: php caligrafer.php env <cache | clear>
php caligrafer.php env cache # .env compiled to .env.php
php caligrafer.php env clear # .env.php removed: pages read .env again .env compiled to .env.php: pages read it without parsing .env (php caligrafer.php env clear removes it)
-
.env.phpis a PHP array thatindex.phpincludes (OPcache keeps it) instead of parsing.envon every request. It holds the sha1 of the.envit was compiled from, and is used only while.envstill has that content: edit.envand pages read it again at once. - It is written next to
.envwith the same permissions (and owner, when run as root), through a temporary file. - It holds the same secrets as
.envand is in.gitignore: never commit it. -
env cachewith no.envprintsenv cache: no .env to compile, or .env.php could not be writtenand exits with1. - The deploy step runs it at every start in production
(
Deployer::cacheEnv()).
-
Editing a migration after it ran (G120): nothing happens,
statussayschangedanddoctorwarns. Restore it and write a new one. -
A
;inside a string of acreate_db.sql:sqland the deploy step split a script on every;, quotes included (migrations split outside quotes). Put such values in a migration, or avoid the;. -
create_db.sqlthat drops a table: the deploy step runs a changed script again, but never one that drops or deletes (G68). Keep scripts safe to run twice (CREATE TABLE IF NOT EXISTS, addedALTER TABLE ... ADDlines). -
migrate "" --env .env.testing: the empty word was needed before 2.19.1; writemigrate --env .env.testing. -
A changed view still shows the old page after copying files (G117):
cache clear. -
.env.phpin git: it holds your secrets. The project's.gitignoreleaves it out; keep it that way.
Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.
Why Caligrafy: the benefits, the measurements, and what it is not yet
-
Quickstart with Claude: describe it, approve it, ship it
or the Quickstart: the same three steps by hand, in 5 minutes
- How Caligrafy works: the ideas in 5 minutes
- Your first capability: build a feature, page included
-
Capabilities in depth
-
#[Capability]: every option - Scheduled jobs: capabilities on a timer
- Notifications: web push and email
- Background jobs: capabilities run later
- Migrations: database changes, in order
- The cache
-
Testing your app
- Dependency injection
- Validation rules
-
Web pages
- Views and page components
- Design styles: another look, one setting
- Declarative routes: every request, in one line
-
Route::page·Route::form·Route::auth·Route::webhook·Route::download·Route::redirect·Route::action·Route::snap· capability routes - How to export a list as CSV
- Controllers: moving one to a declared route · how to, step by step
- Forms and helpers
-
Vue apps
-
Mobile and tablet
-
REST API
-
AI agents
-
Snap Cards and the assistant
- Payments: Stripe and crypto
- Face detection and face login
- OpenAI: chat and images · Assistants
- Open models: Llama, Mistral...
- Chatbots with Watson
- Machine learning in the browser
- Metadata and social cards · search and analytics
-
Putting it online: the production image, the database at every start
-
API reference: every class and method
-
Routing ·
Route·AuthRoutes· pages ·Controller· capabilities -
Data ·
Model·Query· sign-in · jobs ·Notify· payments · AI -
Interfaces · Snap ·
Snap\Cards·Snap\Conversation· testing · tooling · helper functions
-
Routing ·
-
Caligrafer: every command
- Project · build · data · agents · jobs and tests · maintenance · deploy
- Installation, configuration and Caligrafer
- Routing · Request · Controllers · Views
- Vue: flow of information · routes · validations
- Security and upgrading
- Release notes: 2.26 · 2.25 · 2.24 · 2.23 · 2.22 · 2.21 · 2.20 · 2.19 · 2.18 · 2.17 · 2.16 · 2.15 · 2.14 · 2.13 · 2.12 · 2.11 · 2.10 · 2.9 · 2.8 · 2.7 · 2.6 · 2.5 · 2.4 · 2.3 · 2.1 · October 2026 · changelog
- Testing Caligrafy (contributors)