Documentation Index
Fetch the complete documentation index at: https://mintlify.com/cgwire/zou/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Zou provides comprehensive database management commands for initializing, migrating, and maintaining your PostgreSQL database.
Many database commands are destructive and cannot be undone. Always backup your database before running commands like clear-db or reset-db.
Initialization Commands
init-db
Create database tables. The database itself must already exist (created through PostgreSQL client).
Output:
Creating database and tables...
Database and tables created.
is-db-ready
Check if the database is properly initialized.
Output (initialized):
Output (not initialized):
Database is not initialized. Run 'zou init-db' and 'zou init-data'.
init-data
Generate the minimal dataset required to run Kitsu (task statuses, asset types, etc.).
Use case: Must be run after init-db to populate default data.
Migration Commands
upgrade-db
Upgrade the database schema to the latest version. This command also sends anonymized statistics (user count, preview count) to telemetry services unless disabled.
Disable telemetry:
zou upgrade-db --no-telemetry
migrate-db
Development only. Do not use in production.
zou migrate-db --message "Add new column to tasks table"
--message TEXT - Description of the migration (optional)
Use case: Plugin development or Zou core development.
downgrade-db
Development only. This operation can cause data loss.
# Downgrade to previous revision
zou downgrade-db
# Downgrade to specific revision
zou downgrade-db --revision abc123def456
--revision TEXT - Migration hash or relative identifier (default: -1 for previous revision)
Examples:
# Go back one revision
zou downgrade-db --revision -1
# Go back two revisions
zou downgrade-db --revision -2
# Go to specific revision hash
zou downgrade-db --revision 3f4a8b2c1d5e
stamp-db
Set the database schema revision without running migrations. Used to mark the database as being at a specific migration version.
# Stamp to current revision
zou stamp-db
# Stamp to specific revision
zou stamp-db --revision abc123def456
--revision TEXT - Migration revision hash (optional)
Use case: Fixing migration tracking issues or manual schema synchronization.
reset-migrations
Reset the database schema revision to the base (first) revision.
This does not modify the database structure, only the migration tracking.
Destructive Commands
The following commands permanently delete data. Always create backups before running these commands.
clear-db
Drop all tables from the database.
Output:
Deleting database and tables...
Database and tables deleted.
This command deletes ALL data including:
- All projects and productions
- All users and permissions
- All tasks and comments
- All preview files metadata
- All system configuration
This operation cannot be undone!
reset-db
Drop all tables and recreate them. This is equivalent to running clear-db followed by init-db.
Output:
Deleting database and tables...
Database and tables deleted.
Database and tables created.
This permanently deletes all data and recreates an empty database structure.
Cache Management
clear-memory-cache
Clear the Redis memory cache.
Use case:
- After configuration changes
- Troubleshooting caching issues
- Force refresh of cached data
Data Maintenance
remove-old-data
Remove old events, notifications, and login logs. By default, removes data older than 90 days.
# Remove data older than 90 days (default)
zou remove-old-data
# Remove data older than 30 days
zou remove-old-data --days 30
# Remove data older than 180 days
zou remove-old-data --days 180
--days INTEGER - Number of days to keep (default: 90)
Use case: Regular database maintenance to reduce database size and improve performance.
clean-tasks-data
Reset task model data including retake count, WIP start date, and end date for a specific project.
zou clean-tasks-data --project-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
--project-id TEXT - Project ID (required)
Use case: Fixing data inconsistencies or resetting task statistics.
dump-database
Dump the database and optionally save it to configured object storage.
# Dump database locally
zou dump-database
# Dump and store in object storage
zou dump-database --store
--store - Upload dump to object storage (optional flag)
Use case: Regular backups and disaster recovery preparation.
reset-breakdown-data
Reset breakdown statistics for all open projects.
Use case: Recalculating asset/shot relationships and statistics.
Common Workflows
First-Time Setup
# 1. Create database tables
zou init-db
# 2. Initialize default data
zou init-data
# 3. Verify setup
zou is-db-ready
Upgrading Zou
# 1. Backup database
zou dump-database --store
# 2. Upgrade schema
zou upgrade-db
# 3. Verify
zou is-db-ready
Development Reset
# Complete reset for development
zou reset-db
zou init-data
Regular Maintenance
# Monthly maintenance routine
zou remove-old-data --days 90
zou clean-auth-tokens
zou clear-memory-cache
Troubleshooting
Migration Issues
If migrations fail or get out of sync:
# Check current revision
zou is-db-ready
# Stamp to correct revision (if needed)
zou stamp-db --revision <correct_revision>
# Try upgrade again
zou upgrade-db
Database Connection Issues
Ensure your environment variables are set correctly:
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=zoudb
export DB_USERNAME=zou
export DB_PASSWORD=yourpassword
Next Steps