Houseplant

https://houseplant.readthedocs.io/en/latest/
Admin
Houseplant is a CLI tool that helps you manage database migrations for ClickHouse.
Tokens:1,461
Snippets:32
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Houseplant from source

Source: https://houseplant.readthedocs.io/en/latest/install.html

Use this command to install the package in editable mode after cloning the repository.

```bash
$ pip install -e .
```

--------------------------------

### Example migration file path

Source: https://houseplant.readthedocs.io/en/latest/usage.html

The resulting file path after generating a migration.

```text
ch/migrations/20240320123456_create_users_table.yml
```

--------------------------------

### Install Houseplant via pip

Source: https://houseplant.readthedocs.io/en/latest/install.html

Use this command to install the package directly from the Python Package Index.

```bash
$ pip install houseplant
```

--------------------------------

### Set environment for commands

Source: https://houseplant.readthedocs.io/en/latest/usage.html

Example of running a command with a specific environment variable.

```bash
$ HOUSEPLANT_ENV=production houseplant migrate
```

--------------------------------

### Initialize a Houseplant project

Source: https://houseplant.readthedocs.io/en/latest/usage.html

Creates the necessary directory structure for migrations and schema files.

```bash
$ houseplant init
```

--------------------------------

### Project directory structure

Source: https://houseplant.readthedocs.io/en/latest/usage.html

The file structure generated after running the init command.

```text
ch/
├── migrations/
└── schema.sql
```

--------------------------------

### Manage ClickHouse migrations via CLI

Source: https://houseplant.readthedocs.io/en/latest/index.html

Common commands for initializing a project, generating migrations, and executing migration operations.

```bash
$ houseplant init
✨ Project initialized successfully!

$ houseplant generate "add events"
✨ Generated migration: ch/migrations/20240101000000_add_events.yml

$ houseplant migrate:status
Database: june_development

┏━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Status ┃ Migration ID   ┃ Migration Name ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│   up   │ 20240101000000 │ add events     │
└────────┴────────────────┴────────────────┘

$ houseplant migrate
✓ Applied migration 20241121003230_add_events.yml

$ houseplant migrate:up VERSION=20241121003230
✓ Applied migration 20241121003230_add_events.yml

$ houseplant migrate:down VERSION=20241121003230
✓ Rolled back migration 20241121003230_add_events.yml
```

--------------------------------

### Clone Houseplant from GitHub

Source: https://houseplant.readthedocs.io/en/latest/install.html

Use this command to clone the source code repository to your local machine.

```bash
$ git clone git://github.com/juneHQ/houseplant
```

--------------------------------

### Apply migrations

Source: https://houseplant.readthedocs.io/en/latest/usage.html

Commands to run pending migrations, optionally targeting a specific version.

```bash
$ houseplant migrate:up
```

```bash
$ houseplant migrate:up VERSION=20240320123456
```

--------------------------------

### Migration file structure

Source: https://houseplant.readthedocs.io/en/latest/usage.html

YAML format for defining migration steps across different environments.

```yaml
version: "20240320123456"
name: create_users_table
table: users

development: &development
  up: |
    CREATE TABLE {table} (
      id UInt64,
      name String
    ) ENGINE = MergeTree()
    ORDER BY id
  down: |
    DROP TABLE {table}

test:
  <<: *development

production:
  up: |
    CREATE TABLE ON CLUSTER '{cluster}' {table} (
      id UInt64,
      name String
    ) ENGINE = ReplicatedMergeTree()
    ORDER BY id
  down: |
    DROP TABLE ON CLUSTER '{cluster}' {table}
```

--------------------------------

### Load schema

Source: https://houseplant.readthedocs.io/en/latest/usage.html

Loads existing schema migrations into the database without applying them.

```bash
$ houseplant db:schema:load
```

--------------------------------

### Generate a new migration

Source: https://houseplant.readthedocs.io/en/latest/usage.html

Creates a new migration file with a timestamp prefix.

```bash
$ houseplant generate "create users table"
```

--------------------------------

### Check migration status

Source: https://houseplant.readthedocs.io/en/latest/usage.html

Displays applied and pending migrations.

```bash
$ houseplant migrate:status
```

--------------------------------

### Rollback migrations

Source: https://houseplant.readthedocs.io/en/latest/usage.html

Commands to revert migrations, optionally targeting a specific version.

```bash
$ houseplant migrate:down
```

```bash
$ houseplant migrate:down VERSION=20240320123456
```
Tokens:
Raw