Documentation
¶
Overview ¶
Package cmd provides CLI commands for the housekeeper tool.
This package implements the command-line interface for housekeeper, providing commands for project management, schema operations, and database migrations. It supports both standalone operations and project-based workflows with comprehensive ClickHouse integration.
Available Commands ¶
The cmd package currently provides:
- init: Initialize a new housekeeper project structure
- bootstrap: Create a new project from an existing ClickHouse server
- schema dump: Extract schema from live ClickHouse instances
- schema compile: Compile and format project schema files
- diff: Compare schema with database and generate migrations (planned)
Command Structure ¶
Each command is implemented as a separate function that returns a *cli.Command, following the urfave/cli/v3 pattern. Commands are designed to be composable and testable, with proper error handling and comprehensive help text.
Global Options ¶
All commands support global flags:
- --dir, -d: Specify project directory (defaults to current directory)
- --help, -h: Display command help
- --version: Display version information
Example Usage ¶
Commands are registered in the main application and can be invoked from the command line:
housekeeper init # Initialize project housekeeper bootstrap --url localhost:9000 # Bootstrap from ClickHouse server housekeeper bootstrap --url host:9000 --cluster prod # Bootstrap with cluster support housekeeper schema dump --url localhost:9000 # Dump schema from ClickHouse housekeeper schema compile --env production # Compile project schema housekeeper diff --url host:9000 ... # Generate migrations (planned)
ClickHouse Integration ¶
The bootstrap and schema dump commands provide comprehensive ClickHouse integration:
- Flexible DSN parsing (host:port, clickhouse://, tcp://)
- Distributed cluster support with automatic ON CLUSTER injection
- Complete schema extraction (databases, tables, dictionaries, views)
- Professional SQL formatting with consistent styling
- Organized project structure generation for bootstrapped schemas
Each command provides comprehensive help and validation to ensure proper usage and clear error messages.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = fx.Module("cli", fx.Provide( fx.Annotate(bootstrap, fx.ResultTags(`group:"commands"`)), fx.Annotate(dev, fx.ResultTags(`group:"commands"`)), fx.Annotate(diff, fx.ResultTags(`group:"commands"`)), fx.Annotate(fmtCmd, fx.ResultTags(`group:"commands"`)), fx.Annotate(initCmd, fx.ResultTags(`group:"commands"`)), fx.Annotate(migrate, fx.ResultTags(`group:"commands"`)), fx.Annotate(rehash, fx.ResultTags(`group:"commands"`)), fx.Annotate(schema, fx.ResultTags(`group:"commands"`)), fx.Annotate(snapshot, fx.ResultTags(`group:"commands"`)), fx.Annotate(status, fx.ResultTags(`group:"commands"`)), ), fx.Invoke(Run), )
Functions ¶
func Run ¶
func Run(p Params)
Run creates and executes the main housekeeper CLI application with the given version and command-line arguments. This function serves as the main entry point for all CLI operations and handles global configuration.
The function creates a CLI application with:
- Global --dir flag for specifying project directory
- Project auto-detection based on housekeeper.yaml presence
- Command registration and routing
- Context propagation for cancellation support
Global Flags:
- --dir, -d: Project directory (defaults to current directory) Note: This flag is processed before CLI parsing to ensure the working directory is set before dependency injection occurs.
The application automatically detects housekeeper projects by looking for housekeeper.yaml in the specified directory. If found, it initializes the global currentProject variable for use by subcommands.
Example usage:
# Run in current directory (auto-detect project)
err := Run(ctx, "v1.0.0", []string{"housekeeper", "init"})
# Run in specific directory
err := Run(ctx, "v1.0.0", []string{"housekeeper", "--dir", "/path/to/project", "schema", "compile", "--env", "dev"})
Returns an error if command execution fails or if project detection encounters issues.
func TestableRehash ¶
TestableRehash creates a testable version of the rehash command for use in unit tests. This function exposes the same functionality as the main rehash command but allows for easier testing by accepting a project parameter directly.
Source Files
Directories