Documentation
¶
Overview ¶
Package project provides comprehensive ClickHouse project management capabilities including project initialization, configuration management, and schema compilation with import directive support.
Project Management ¶
The project package enables structured management of ClickHouse schemas through a standardized project layout and configuration system. It provides idempotent project initialization that creates the necessary directory structure and configuration files while preserving existing content.
Key Features ¶
- Project initialization with standard directory layout
- Multi-environment configuration support
- Schema compilation with recursive import processing
- Template-based project bootstrapping
- Integration with the ClickHouse DDL parser
- Docker-based ClickHouse management for migration testing
Project Structure ¶
A housekeeper project follows this standard layout:
project-root/ ├── housekeeper.yaml # Environment configuration ├── db/ │ ├── main.sql # Main schema entrypoint │ ├── migrations/ │ │ └── dev/ # Development migrations │ └── schemas/ # Organized schema files
Import System ¶
The schema compilation system supports recursive imports using special comment directives:
-- housekeeper:import path/to/schema.sql
Import paths are resolved relative to the current file's directory, enabling modular schema organization and reusability across environments.
Usage Example ¶
// Initialize a new project
proj := project.New(project.ProjectParams{
Dir: "/path/to/my/project",
Formatter: format.New(format.Defaults),
})
err := proj.Initialize(project.InitOptions{})
if err != nil {
log.Fatal("Failed to initialize project:", err)
}
// Create a project instance for the directory
proj := project.New(project.ProjectParams{
Dir: "/path/to/my/project",
Formatter: format.New(format.Defaults),
})
// Load configuration and compile schema
cfg, err := config.LoadConfigFile("housekeeper.yaml")
if err != nil {
log.Fatal("Failed to load config:", err)
}
var buf bytes.Buffer
if err := schema.Compile(cfg.Entrypoint, &buf); err != nil {
log.Fatal("Failed to compile schema:", err)
}
sql, err := parser.ParseString(buf.String())
if err != nil {
log.Fatal("Failed to parse schema:", err)
}
// Process the parsed DDL statements
for _, stmt := range sql.Statements {
if stmt.CreateTable != nil {
fmt.Printf("Found table: %s\n", stmt.CreateTable.Name)
}
}
// Use Docker for migration testing
dm := project.NewDockerManager()
defer dm.Stop(ctx)
if err := dm.Start(ctx); err != nil {
log.Fatal("Failed to start ClickHouse:", err)
}
// Apply migrations and test schema
dsn := dm.GetDSN() // localhost:9000
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type InitOptions ¶
type InitOptions struct {
// Cluster specifies the ClickHouse cluster name to use in configuration
// If empty, the default cluster name will be used
Cluster string
}
InitOptions contains options for project initialization
type Project ¶
type Project struct {
RootDir string
// contains filtered or unexported fields
}
Project represents a ClickHouse schema management project. The project operates within the specified root directory.
func New ¶
func New(p ProjectParams) *Project
New creates a new Project instance for managing ClickHouse schema projects. Takes the root directory path where the project is located.
Example:
// Create a project for a specific directory
proj := project.New("/path/to/my/project")
// Initialize a new project structure
err := proj.Initialize(project.InitOptions{})
if err != nil {
log.Fatal(err)
}
// Get migrations directory path
migrationsDir := proj.MigrationsDir()
fmt.Printf("Migrations directory: %s\n", migrationsDir)
func (*Project) BootstrapFromSchema ¶
BootstrapFromSchema creates project files from a parsed SQL schema. This method is used by the bootstrap command to extract schema from an existing ClickHouse instance and organize it into a project structure.
The function is idempotent - existing files are preserved to avoid overwriting user modifications.
Parameters:
- sql: The parsed SQL containing DDL statements to organize into project structure
Returns an error if schema generation or file operations fail.
func (*Project) Initialize ¶
func (p *Project) Initialize(options InitOptions) error
Initialize sets up a new project directory structure. This method is idempotent - it will only create missing files and directories, preserving any existing content. It creates the standard housekeeper project structure including db/, migrations/, and schema directories along with configuration files in the project's root directory.
Example:
// Create and initialize a new project
proj := project.New(project.ProjectParams{
Dir: "/path/to/my/project",
Formatter: format.New(format.Defaults),
})
err := proj.Initialize(project.InitOptions{})
if err != nil {
log.Fatal("Failed to initialize project:", err)
}
// Initialize with custom cluster
proj := project.New(project.ProjectParams{
Dir: "/path/to/my/project",
Formatter: format.New(format.Defaults),
})
err := proj.Initialize(project.InitOptions{
Cluster: "production",
})
if err != nil {
log.Fatal("Failed to initialize project:", err)
}
Source Files