clickhouse-users-cli 0.1.0__py3-none-any.whl

clickhouse_users_cli/__init__.py

@@ -0,0 +1,5 @@
+"""ClickHouse Users CLI — crie usuários com escopo mínimo (least privilege)."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

clickhouse_users_cli/app.py

@@ -0,0 +1,543 @@
+"""Fluxo interativo — cada função = 1 etapa, 1 widget ideal para o tipo de dado."""
+
+from __future__ import annotations
+
+import sys
+
+import questionary
+from rich.syntax import Syntax
+from rich.table import Table
+
+from clickhouse_users_cli.db import SYSTEM_DATABASES, ClickHouseAdmin, ConnectionInfo
+from clickhouse_users_cli.sql_builder import (
+    PROFILE_LABELS,
+    PROFILE_PRIVILEGES,
+    GrantScope,
+    UserSpec,
+    build_activate_user_sql,
+    build_all_statements,
+    build_deactivate_user_sql,
+    build_drop_user_sql,
+)
+from clickhouse_users_cli.style import APP_STYLE, banner, console, error, info, step, success
+from clickhouse_users_cli.validators import (
+    validate_at_least_one,
+    validate_host,
+    validate_new_password,
+    validate_port,
+    validate_required,
+    validate_username,
+)
+
+Q = questionary  # alias curto
+
+
+def _ask_or_abort(prompt):
+    """questionary retorna None no Ctrl+C — converte em saída limpa."""
+    answer = prompt.ask()
+    if answer is None:
+        console.print("\n[dim]Operação cancelada pelo usuário.[/]")
+        raise SystemExit(0)
+    return answer
+
+
+# ── Etapa 1: conexão ──────────────────────────────────────────────────────────
+
+def ask_connection() -> ConnectionInfo:
+    step("1/6 · Conexão com o ClickHouse", "Use uma conta admin (ex.: default). Nada é salvo em disco.")
+
+    host = _ask_or_abort(
+        Q.text("Host do servidor:", default="localhost", validate=validate_host, style=APP_STYLE, qmark="›")
+    ).strip()
+
+    protocol = _ask_or_abort(
+        Q.select(
+            "Protocolo:",
+            choices=[
+                Q.Choice("http — porta 8123 (rede local / sem TLS)", value=False),
+                Q.Choice("https — porta 8443 (TLS, recomendado)", value=True),
+            ],
+            default=False,
+            style=APP_STYLE, qmark="›",
+            instruction="(↑↓ navega · enter confirma)",
+        )
+    )
+    default_port = "8443" if protocol else "8123"
+
+    port = int(
+        _ask_or_abort(
+            Q.text(f"Porta HTTP(S) [{default_port}]:", default=default_port, validate=validate_port, style=APP_STYLE, qmark="›")
+        ).strip()
+        or default_port
+    )
+
+    admin_user = _ask_or_abort(
+        Q.text("Usuário admin:", default="default", validate=validate_required, style=APP_STYLE, qmark="›")
+    ).strip()
+
+    admin_pass = _ask_or_abort(Q.password("Senha do admin (enter = vazia):", style=APP_STYLE, qmark="›"))
+
+    return ConnectionInfo(host=host, port=port, secure=protocol, username=admin_user, password=admin_pass)
+
+
+def connect_with_retry(conn: ConnectionInfo) -> ClickHouseAdmin:
+    while True:
+        with console.status(f"[cyan]Conectando em {conn.protocol}://{conn.host}:{conn.port}…[/]", spinner="dots"):
+            try:
+                admin = ClickHouseAdmin(conn).connect()
+                success(f"Conectado como '{conn.username}' em {conn.host}:{conn.port}")
+                return admin
+            except RuntimeError as e:
+                error(str(e))
+        action = _ask_or_abort(
+            Q.select(
+                "Não foi possível conectar. O que fazer?",
+                choices=["Tentar de novo", "Editar credenciais", "Sair"],
+                style=APP_STYLE, qmark="›",
+            )
+        )
+        if action == "Tentar de novo":
+            continue
+        if action == "Editar credenciais":
+            return connect_with_retry(ask_connection())
+        raise SystemExit(1)
+
+
+# ── Etapa 2: perfil do novo usuário ───────────────────────────────────────────
+
+def ask_profile() -> str:
+    step("2/6 · Tipo de usuário", "O perfil define os privilégios padrão (least privilege primeiro).")
+    return _ask_or_abort(
+        Q.select(
+            "Que tipo de usuário criar?",
+            choices=[Q.Choice(PROFILE_LABELS[k], value=k) for k in ("readonly", "readwrite", "admin", "custom")],
+            default="readonly",
+            style=APP_STYLE, qmark="›",
+            instruction="(↑↓ navega · enter confirma)",
+        )
+    )
+
+
+# ── Etapa 3: credenciais do novo usuário ──────────────────────────────────────
+
+def ask_new_credentials() -> tuple[str, str]:
+    step("3/6 · Novo usuário", "Nome segue regra do ClickHouse: letras, números e _ .")
+    username = _ask_or_abort(
+        Q.text("Nome do novo usuário:", validate=validate_username, style=APP_STYLE, qmark="›")
+    ).strip()
+
+    while True:
+        pwd = _ask_or_abort(
+            Q.password("Senha do novo usuário (mín. 8 chars):", validate=validate_new_password, style=APP_STYLE, qmark="›")
+        )
+        confirm = _ask_or_abort(Q.password("Confirme a senha:", style=APP_STYLE, qmark="›"))
+        if pwd != confirm:
+            error("Senhas não conferem — tente de novo.")
+            continue
+        return username, pwd
+
+
+# ── Etapa 4: escopo (bancos → tabelas) ────────────────────────────────────────
+
+def ask_databases(admin: ClickHouseAdmin) -> list[str]:
+    step("4/6 · Escopo — bancos", "Espaço marca · A confirma · Ctrl+A inverte a seleção.")
+    with console.status("[cyan]Listando bancos…[/]", spinner="dots"):
+        try:
+            databases = admin.list_databases()
+        except Exception as e:
+            error(f"Falha ao listar bancos: {e}")
+            raise SystemExit(1)
+
+    if not databases:
+        error("Nenhum banco encontrado.")
+        raise SystemExit(1)
+
+    choices = [
+        Q.Choice(
+            title=f"{db}  (sistema)" if db in SYSTEM_DATABASES else db,
+            value=db,
+            # UX: sistema desmarcado por padrão para evitar GRANT acidental.
+            checked=db not in SYSTEM_DATABASES,
+        )
+        for db in databases
+    ]
+    selected = _ask_or_abort(
+        Q.checkbox(
+            "Em quais bancos o usuário terá acesso?",
+            choices=choices,
+            validate=validate_at_least_one,
+            style=APP_STYLE, qmark="›",
+            instruction="(espaço marca · enter confirma)",
+        )
+    )
+    return selected
+
+
+def ask_tables(admin: ClickHouseAdmin, databases: list[str]) -> list[GrantScope]:
+    step("4/6 · Escopo — tabelas", "Escolha '*' para o banco inteiro ou marque tabelas específicas.")
+    scopes: list[GrantScope] = []
+    for db in databases:
+        try:
+            tables = admin.list_tables(db)
+        except Exception as e:
+            error(f"Falha ao listar tabelas de '{db}': {e} — usando '{db}.*'.")
+            scopes.append(GrantScope(database=db, table=None))
+            continue
+
+        if not tables:
+            info(f"Banco '{db}' sem tabelas — será concedido '{db}.*'.")
+            scopes.append(GrantScope(database=db, table=None))
+            continue
+
+        choices = [Q.Choice(title=f"{db}.*  — todas as tabelas (atuais e futuras)", value="__ALL__")] + [
+            Q.Choice(title=f"{db}.{t}", value=t) for t in tables
+        ]
+        picked: list[str] = _ask_or_abort(
+            Q.checkbox(
+                f"Tabelas de '{db}':",
+                choices=choices,
+                validate=validate_at_least_one,
+                style=APP_STYLE, qmark="›",
+                instruction="(espaço marca · enter confirma)",
+            )
+        )
+        if "__ALL__" in picked:
+            scopes.append(GrantScope(database=db, table=None))
+        else:
+            scopes.extend(GrantScope(database=db, table=t) for t in picked)
+    return scopes
+
+
+# ── Etapa 5: privilégios + restrições ─────────────────────────────────────────
+
+PRIVILEGE_CHOICES = [
+    ("SELECT", "Ler dados"),
+    ("SHOW", "Ver bancos/tabelas/colunas"),
+    ("INSERT", "Inserir dados"),
+    ("CREATE", "Criar bancos/tabelas/views"),
+    ("ALTER", "Alterar estrutura/config"),
+    ("DROP", "Excluir bancos/tabelas — perigoso!"),
+    ("TRUNCATE", "Apagar todos os dados da tabela — perigoso!"),
+    ("OPTIMIZE", "Otimizar partições"),
+    ("KILL QUERY", "Cancelar queries em execução"),
+]
+
+
+def ask_privileges(profile: str) -> tuple[list[str], bool]:
+    """Retorna (privilégios, grant_option)."""
+    if profile != "custom":
+        grant_option = profile == "admin"
+        return list(PROFILE_PRIVILEGES[profile]), grant_option
+
+    step("5/6 · Privilégios personalizados", "Marque só o necessário — DROP/TRUNCATE exigem confirmação extra.")
+    privs: list[str] = _ask_or_abort(
+        Q.checkbox(
+            "Quais privilégios conceder?",
+            choices=[Q.Choice(f"{name:12} — {desc}", value=name) for name, desc in PRIVILEGE_CHOICES],
+            validate=validate_at_least_one,
+            style=APP_STYLE, qmark="›",
+        )
+    )
+    grant_option = False
+    if any(p in privs for p in ("DROP", "TRUNCATE")):
+        grant_option_confirm = _ask_or_abort(
+            Q.confirm("Você marcou privilégio destrutivo. Tem certeza?", default=False, style=APP_STYLE, qmark="›")
+        )
+        if not grant_option_confirm:
+            return ask_privileges("custom")
+    else:
+        grant_option = _ask_or_abort(
+            Q.confirm("Permitir repassar acessos (WITH GRANT OPTION)?", default=False, style=APP_STYLE, qmark="›")
+        )
+    return privs, grant_option
+
+
+def ask_host_restriction() -> list[str]:
+    step("5/6 · Restrição de origem", "De onde esse usuário poderá conectar?")
+    mode = _ask_or_abort(
+        Q.select(
+            "Permitir conexão de:",
+            choices=[
+                Q.Choice("Qualquer host — HOST ANY (padrão, mais simples)", value="any"),
+                Q.Choice("Somente localhost — HOST LOCALHOST", value="localhost"),
+                Q.Choice("IPs/hosts específicos — ex.: 10.0.0.5", value="custom"),
+            ],
+            default="any",
+            style=APP_STYLE, qmark="›",
+        )
+    )
+    if mode == "any":
+        return []
+    if mode == "localhost":
+        return ["LOCALHOST"]
+    raw = _ask_or_abort(
+        Q.text("Hosts/IPs (separados por vírgula):", validate=validate_required, style=APP_STYLE, qmark="›")
+    )
+    return [h.strip() for h in raw.split(",") if h.strip()]
+
+
+def ask_create_options() -> bool:
+    return _ask_or_abort(
+        Q.confirm("Usar IF NOT EXISTS (não falha se o usuário já existir)?", default=True, style=APP_STYLE, qmark="›")
+    )
+
+
+# ── Etapa 6: revisão + execução ───────────────────────────────────────────────
+
+def show_review(spec: UserSpec) -> None:
+    step("6/6 · Revisão", "Confira o resumo e o SQL exato que será executado.")
+    table = Table(title="Resumo do novo usuário", show_header=True, header_style="bold cyan")
+    table.add_column("Campo", style="dim")
+    table.add_column("Valor", style="bold")
+    table.add_row("Usuário", spec.username)
+    table.add_row("Privilégios", ", ".join(spec.privileges))
+    table.add_row("Escopo", ", ".join(s.on_clause() for s in spec.scopes))
+    table.add_row("Hosts", ", ".join(spec.hosts) if spec.hosts else "ANY (qualquer host)")
+    table.add_row("GRANT OPTION", "sim" if spec.grant_option else "não")
+    console.print(table)
+
+    console.print("[dim]SQL a executar:[/]")
+    from rich.panel import Panel as RichPanel
+
+    for sql in build_all_statements(spec):
+        console.print(RichPanel(Syntax(sql + ";", "sql", theme="monokai"), border_style="dim"))
+
+
+def confirm_and_execute(admin: ClickHouseAdmin, spec: UserSpec) -> None:
+    show_review(spec)
+    go = _ask_or_abort(Q.confirm(f"Criar usuário '{spec.username}' agora?", default=True, style=APP_STYLE, qmark="›"))
+    if not go:
+        console.print("[dim]Nada foi executado.[/]")
+        raise SystemExit(0)
+
+    statements = build_all_statements(spec)
+    with console.status("[cyan]Executando DDL…[/]", spinner="dots"):
+        try:
+            admin.execute_statements(statements)
+        except Exception as e:
+            error(f"Falha ao criar usuário: {e}")
+            info("Dica: verifique se sua conta admin tem permissão CREATE USER + GRANT.")
+            raise SystemExit(1)
+    success(f"Usuário '{spec.username}' criado com {len(statements)} comando(s).")
+    info("Teste: clickhouse-client --user " + spec.username + " --password '***' --query 'SHOW TABLES'")
+
+
+
+
+# ── Menu principal + listar/gerenciar ────────────────────────────────────────────
+
+def ask_main_action() -> str:
+    return _ask_or_abort(
+        Q.select(
+            "O que deseja fazer?",
+            choices=[
+                Q.Choice("Criar usuário — com privilégio mínimo", value="create"),
+                Q.Choice("Listar usuários — SHOW USERS + grants", value="list"),
+                Q.Choice("Gerenciar usuário — desativar / reativar / excluir", value="manage"),
+                Q.Choice("Sair", value="exit"),
+            ],
+            default="create",
+            style=APP_STYLE, qmark="›",
+            instruction="(↑↓ navega · enter confirma)",
+        )
+    )
+
+
+def _is_inactive(create_sql: str) -> bool:
+    return "HOST NONE" in (create_sql or "").upper()
+
+
+def show_user_details(admin: ClickHouseAdmin, username: str) -> tuple[str, list[str]]:
+    """Busca CREATE + GRANTS e exibe. Retorna (create_sql, grants)."""
+    try:
+        create_sql = admin.show_create_user(username)
+    except Exception as e:
+        error(f"Falha ao ver detalhes de '{username}': {e}")
+        create_sql = ""
+    try:
+        grants = admin.show_grants(username)
+    except Exception as e:
+        error(f"Falha ao ver grants de '{username}': {e}")
+        grants = []
+
+    table = Table(title=f"Usuário {username}", show_header=True, header_style="bold cyan")
+    table.add_column("Campo", style="dim")
+    table.add_column("Valor", style="bold")
+    status = "inativo (HOST NONE)" if _is_inactive(create_sql) else "ativo"
+    table.add_row("Status", status)
+    table.add_row("Grants", "\n".join(grants) if grants else "(nenhum grant explícito)")
+    console.print(table)
+
+    if create_sql:
+        console.print("[dim]Definição atual:[/]")
+        from rich.panel import Panel as RichPanel
+
+        console.print(RichPanel(Syntax(create_sql + ";", "sql", theme="monokai"), border_style="dim"))
+    return create_sql, grants
+
+
+def flow_list_users(admin: ClickHouseAdmin) -> None:
+    step("Usuários · Lista", "SHOW USERS — depois escolha um para ver grants.")
+    with console.status("[cyan]Listando usuários…[/]", spinner="dots"):
+        try:
+            users = admin.list_users()
+        except Exception as e:
+            error(f"Falha ao listar usuários: {e}")
+            info("Dica: sua conta precisa de SHOW USERS / acesso a system.users.")
+            return
+
+    if not users:
+        info("Nenhum usuário encontrado.")
+        return
+
+    table = Table(title=f"{len(users)} usuário(s)", show_header=True, header_style="bold cyan")
+    table.add_column("#", style="dim")
+    table.add_column("Usuário", style="bold")
+    for i, u in enumerate(users, 1):
+        table.add_row(str(i), u)
+    console.print(table)
+
+    see = _ask_or_abort(
+        Q.confirm("Ver detalhes (grants) de um usuário?", default=True, style=APP_STYLE, qmark="›")
+    )
+    if not see:
+        return
+    target = _ask_or_abort(
+        Q.select(
+            "Qual usuário?",
+            choices=users,
+            style=APP_STYLE, qmark="›",
+            instruction="(↑↓ navega · enter confirma)",
+        )
+    )
+    show_user_details(admin, target)
+
+
+def flow_manage_users(admin: ClickHouseAdmin) -> None:
+    step("Usuários · Gerenciar", "Desativar = HOST NONE (reversível). Excluir = DROP USER (definitivo).")
+    with console.status("[cyan]Listando usuários…[/]", spinner="dots"):
+        try:
+            users = admin.list_users()
+        except Exception as e:
+            error(f"Falha ao listar usuários: {e}")
+            return
+
+    if not users:
+        info("Nenhum usuário encontrado.")
+        return
+
+    target = _ask_or_abort(
+        Q.select(
+            "Qual usuário gerenciar?",
+            choices=users,
+            style=APP_STYLE, qmark="›",
+            instruction="(↑↓ navega · enter confirma)",
+        )
+    )
+    create_sql, _grants = show_user_details(admin, target)
+    inactive = _is_inactive(create_sql)
+
+    if target == admin.conn.username:
+        error(f" Atenção: '{target}' é o usuário conectado agora. Desativar/excluir pode te derrubar.")
+
+    options = []
+    if inactive:
+        options.append(Q.Choice("Reativar — ALTER USER … HOST ANY", value="activate"))
+    else:
+        options.append(Q.Choice("Desativar — ALTER USER … HOST NONE (reversível)", value="deactivate"))
+    options += [
+        Q.Choice("Excluir — DROP USER (definitivo!)", value="drop"),
+        Q.Choice("Voltar ao menu", value="back"),
+    ]
+    action = _ask_or_abort(
+        Q.select("Ação:", choices=options, style=APP_STYLE, qmark="›")
+    )
+    if action == "back":
+        return
+
+    preview = {
+        "deactivate": build_deactivate_user_sql(target),
+        "activate": build_activate_user_sql(target),
+        "drop": build_drop_user_sql(target),
+    }[action]
+
+    console.print("[dim]SQL a executar:[/]")
+    from rich.panel import Panel as RichPanel
+
+    console.print(RichPanel(Syntax(preview + ";", "sql", theme="monokai"), border_style="dim"))
+
+    # Confirmação: default sempre o mais seguro (não executar).
+    label = {"deactivate": f"Desativar '{target}' agora?", "activate": f"Reativar '{target}' agora?", "drop": f"EXCLUIR '{target}' em definitivo?"}[action]
+    go = _ask_or_abort(Q.confirm(label, default=False, style=APP_STYLE, qmark="›"))
+    if not go:
+        console.print("[dim]Nada foi executado.[/]")
+        return
+
+    with console.status("[cyan]Executando…[/]", spinner="dots"):
+        try:
+            if action == "deactivate":
+                admin.deactivate_user(target)
+            elif action == "activate":
+                admin.activate_user(target)
+            else:
+                admin.drop_user(target)
+        except Exception as e:
+            error(f"Falha na operação: {e}")
+            info("Dica: verifique se sua conta tem ALTER USER / DROP USER.")
+            return
+    success({"deactivate": f"Usuário '{target}' desativado (HOST NONE).", "activate": f"Usuário '{target}' reativado (HOST ANY).", "drop": f"Usuário '{target}' excluído."}[action])
+
+
+def flow_create_user(admin: ClickHouseAdmin) -> None:
+    profile = ask_profile()
+    username, password = ask_new_credentials()
+    databases = ask_databases(admin)
+    scopes = ask_tables(admin, databases)
+    privileges, grant_option = ask_privileges(profile)
+    if profile == "admin":
+        grant_option = True
+    hosts = ask_host_restriction()
+    if_not_exists = ask_create_options()
+
+    spec = UserSpec(
+        username=username,
+        password=password,
+        privileges=privileges,
+        scopes=scopes,
+        hosts=hosts,
+        if_not_exists=if_not_exists,
+        grant_option=grant_option,
+    )
+    confirm_and_execute(admin, spec)
+
+
+# ── main ─────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    try:
+        banner()
+        conn = ask_connection()
+        admin = connect_with_retry(conn)
+
+        while True:
+            action = ask_main_action()
+            if action == "create":
+                flow_create_user(admin)
+            elif action == "list":
+                flow_list_users(admin)
+            elif action == "manage":
+                flow_manage_users(admin)
+            else:
+                console.print("[dim]Até logo![/]")
+                return
+    except SystemExit:
+        raise
+    except KeyboardInterrupt:
+        console.print("\n[dim]Interrompido. Nada foi executado.[/]")
+    except Exception as e:  # pragma: no cover — guarda-chuva final
+        error(f"Erro inesperado: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

clickhouse_users_cli/db.py

@@ -0,0 +1,110 @@
+"""Camada de acesso ao ClickHouse via clickhouse-connect."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ConnectionInfo:
+    host: str
+    port: int
+    secure: bool
+    username: str
+    password: str
+
+    @property
+    def protocol(self) -> str:
+        return "https" if self.secure else "http"
+
+
+# Bancos internos que poluim a seleção — vão para o fim da lista, desmarcados.
+SYSTEM_DATABASES = {"system", "information_schema", "INFORMATION_SCHEMA"}
+
+
+class ClickHouseAdmin:
+    def __init__(self, conn: ConnectionInfo):
+        self.conn = conn
+        self._client = None
+
+    def connect(self):
+        """Cria cliente e valida com SELECT 1. Levanta exceção com msg amigável."""
+        try:
+            from clickhouse_connect import get_client
+        except ImportError as e:  # pragma: no cover
+            raise RuntimeError(
+                "Dependência 'clickhouse-connect' não instalada. Rode: pip install -r requirements.txt"
+            ) from e
+
+        try:
+            self._client = get_client(
+                host=self.conn.host,
+                port=self.conn.port,
+                username=self.conn.username,
+                password=self.conn.password,
+                secure=self.conn.secure,
+            )
+            self._client.query("SELECT 1")
+        except Exception as e:
+            raise RuntimeError(f"Falha ao conectar em {self.conn.protocol}://{self.conn.host}:{self.conn.port}: {e}") from e
+        return self
+
+    @property
+    def client(self):
+        if self._client is None:
+            raise RuntimeError("Não conectado. Chame .connect() primeiro.")
+        return self._client
+
+    def list_databases(self) -> list[str]:
+        rows = self.client.query("SHOW DATABASES").result_rows
+        dbs = [r[0] for r in rows if r and r[0]]
+        # UX: bancos de usuário primeiro (alfabético), sistema por último.
+        user_dbs = sorted(d for d in dbs if d not in SYSTEM_DATABASES)
+        sys_dbs = sorted(d for d in dbs if d in SYSTEM_DATABASES)
+        return user_dbs + sys_dbs
+
+    def list_tables(self, database: str) -> list[str]:
+        # Escapa com backticks pois nome do banco vem do servidor, não do usuário.
+        rows = self.client.query(f"SHOW TABLES FROM `{database}`").result_rows
+        return sorted(r[0] for r in rows if r and r[0])
+
+    def list_users(self) -> list[str]:
+        rows = self.client.query("SHOW USERS").result_rows
+        return sorted(r[0] for r in rows if r and r[0])
+
+    def show_grants(self, username: str) -> list[str]:
+        from clickhouse_users_cli.sql_builder import build_show_grants_sql
+
+        rows = self.client.query(build_show_grants_sql(username)).result_rows
+        return [r[0] for r in rows if r and r[0]]
+
+    def show_create_user(self, username: str) -> str:
+        from clickhouse_users_cli.sql_builder import build_show_create_user_sql
+
+        rows = self.client.query(build_show_create_user_sql(username)).result_rows
+        return rows[0][0] if rows and rows[0] else ""
+
+    def deactivate_user(self, username: str) -> str:
+        from clickhouse_users_cli.sql_builder import build_deactivate_user_sql
+
+        sql = build_deactivate_user_sql(username)
+        self.client.command(sql)
+        return sql
+
+    def activate_user(self, username: str) -> str:
+        from clickhouse_users_cli.sql_builder import build_activate_user_sql
+
+        sql = build_activate_user_sql(username)
+        self.client.command(sql)
+        return sql
+
+    def drop_user(self, username: str) -> str:
+        from clickhouse_users_cli.sql_builder import build_drop_user_sql
+
+        sql = build_drop_user_sql(username)
+        self.client.command(sql)
+        return sql
+
+    def execute_statements(self, statements: list[str]) -> None:
+        for sql in statements:
+            self.client.command(sql)

clickhouse_users_cli/sql_builder.py

@@ -0,0 +1,116 @@
+"""Construção do SQL DDL/DCL — separada do fluxo interativo para testar sem banco."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+def escape_ident(name: str) -> str:
+    """Escapa identificador com backticks: `nome`."""
+    return "`" + name.replace("`", "``") + "`"
+
+
+def escape_string(value: str) -> str:
+    """Escapa literal de string com aspas simples."""
+    return "'" + value.replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def escape_host(value: str) -> str:
+    # HOST em CREATE USER aceita IP/hostname; aspas simples são o seguro.
+    return escape_string(value)
+
+
+@dataclass
+class GrantScope:
+    """Um alvo de GRANT: (database, table|None, table|*)."""
+
+    database: str  # "*" = todas
+    table: str | None = None  # None = db.* | "*" = *.* quando database == "*"
+
+    def on_clause(self) -> str:
+        if self.database == "*":
+            return "*.*"
+        if self.table in (None, "*"):
+            return f"{escape_ident(self.database)}.*"
+        return f"{escape_ident(self.database)}.{escape_ident(self.table)}"
+
+
+@dataclass
+class UserSpec:
+    username: str
+    password: str  # plaintext na criação; ClickHouse guarda o hash
+    privileges: list[str] = field(default_factory=list)  # ex.: ["SELECT", "SHOW"]
+    scopes: list[GrantScope] = field(default_factory=list)
+    hosts: list[str] = field(default_factory=list)  # vazio = qualquer host
+    if_not_exists: bool = True
+    grant_option: bool = False  # WITH GRANT OPTION (só admin)
+    # Quota futura: ex. "MAX QUERIES PER HOUR 1000" — mantido para evoluir sem quebrar API.
+
+
+# Templates de perfil → privilégios padrão. "custom" deixa o usuário marcar.
+PROFILE_PRIVILEGES: dict[str, list[str]] = {
+    "readonly": ["SHOW", "SELECT"],
+    "readwrite": ["SHOW", "SELECT", "INSERT"],
+    "admin": ["ALL"],
+    "custom": [],
+}
+
+PROFILE_LABELS: dict[str, str] = {
+    "readonly": "Somente leitura — SELECT + SHOW (analistas, BI)",
+    "readwrite": "Leitura + escrita — SELECT + SHOW + INSERT (engenheiros)",
+    "admin": "Administrador — ALL com GRANT OPTION (acesso total!)",
+    "custom": "Personalizado — eu escolho os privilégios",
+}
+
+
+def build_create_user_sql(spec: UserSpec) -> str:
+    ine = "IF NOT EXISTS " if spec.if_not_exists else ""
+    parts = [f"CREATE USER {ine}{escape_ident(spec.username)}"]
+    parts.append(f"IDENTIFIED WITH plaintext_password BY {escape_string(spec.password)}")
+    if spec.hosts:
+        hosts = ", ".join(f"HOST {escape_host(h)}" for h in spec.hosts)
+        parts.append(hosts)
+    else:
+        parts.append("HOST ANY")
+    return " ".join(parts)
+
+
+def build_grant_sql(spec: UserSpec) -> list[str]:
+    if not spec.scopes:
+        raise ValueError("Nenhum escopo (banco/tabela) selecionado.")
+    if not spec.privileges:
+        raise ValueError("Nenhum privilégio selecionado.")
+    privs = ", ".join(spec.privileges)
+    stmts: list[str] = []
+    for scope in spec.scopes:
+        suffix = " WITH GRANT OPTION" if spec.grant_option else ""
+        stmts.append(f"GRANT {privs} ON {scope.on_clause()} TO {escape_ident(spec.username)}{suffix}")
+    return stmts
+
+
+def build_all_statements(spec: UserSpec) -> list[str]:
+    return [build_create_user_sql(spec), *build_grant_sql(spec)]
+
+
+def build_show_grants_sql(username: str) -> str:
+    return f"SHOW GRANTS FOR {escape_ident(username)}"
+
+
+def build_show_create_user_sql(username: str) -> str:
+    return f"SHOW CREATE USER {escape_ident(username)}"
+
+
+def build_deactivate_user_sql(username: str) -> str:
+    """Desativa o login sem excluir: bloqueia qualquer origem (reversível)."""
+    return f"ALTER USER {escape_ident(username)} HOST NONE"
+
+
+def build_activate_user_sql(username: str) -> str:
+    """Reativa o login: permite qualquer origem."""
+    return f"ALTER USER {escape_ident(username)} HOST ANY"
+
+
+def build_drop_user_sql(username: str, if_exists: bool = True) -> str:
+    """Exclui o usuário em definitivo."""
+    ine = "IF EXISTS " if if_exists else ""
+    return f"DROP USER {ine}{escape_ident(username)}"

clickhouse_users_cli/style.py

@@ -0,0 +1,55 @@
+"""Estilo centralizado (UI) + helpers de apresentação com Rich."""
+
+from questionary import Style
+from rich.console import Console
+from rich.panel import Panel
+from rich.rule import Rule
+
+console = Console()
+
+# Estilo questionary: alto contraste, foco visível, perigo em vermelho.
+# Mantém a navegação por teclado óbvia (setas + espaço + enter).
+APP_STYLE = Style(
+    [
+        ("qmark", "fg:#00d7ff bold"),       # "?" das perguntas
+        ("question", "fg:#ffffff bold"),     # texto da pergunta
+        ("answer", "fg:#00ff87 bold"),       # resposta escolhida
+        ("pointer", "fg:#00d7ff bold"),      # "»" do item focado
+        ("highlighted", "fg:#00d7ff bold"), # item focado
+        ("selected", "fg:#00ff87"),          # checkbox marcado "●"
+        ("separator", "fg:#6c7086"),
+        ("instruction", "fg:#a6adc8 italic"),
+        ("text", "fg:#ffffff"),
+        ("disabled", "fg:#6c7086 italic"),
+    ]
+)
+
+
+def banner() -> None:
+    console.print(
+        Panel.fit(
+            "[bold cyan]ClickHouse Users CLI[/]\n"
+            "[dim]Crie usuários com escopo mínimo necessário (least privilege)[/dim]",
+            border_style="cyan",
+        )
+    )
+
+
+def step(title: str, subtitle: str = "") -> None:
+    """Cabeçalho de etapa — orienta o usuário sobre 'onde estou' no fluxo."""
+    console.print()
+    console.print(Rule(f"[bold cyan]{title}[/]", style="cyan"))
+    if subtitle:
+        console.print(f"[dim]{subtitle}[/]")
+
+
+def success(msg: str) -> None:
+    console.print(f"[bold green]✔ {msg}[/]")
+
+
+def error(msg: str) -> None:
+    console.print(f"[bold red]✘ {msg}[/]")
+
+
+def info(msg: str) -> None:
+    console.print(f"[dim]{msg}[/]")

clickhouse_users_cli/validators.py

@@ -0,0 +1,57 @@
+"""Validadores semânticos para cada tipo de input."""
+
+from __future__ import annotations
+
+import re
+
+USERNAME_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]{0,63}$")
+HOST_RE = re.compile(
+    r"^([a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?)*|localhost|\d{1,3}(\.\d{1,3}){3})$"
+)
+
+
+def validate_required(value: str) -> bool | str:
+    if value and value.strip():
+        return True
+    return "Valor obrigatório — digite algo para continuar."
+
+
+def validate_host(value: str) -> bool | str:
+    if not value.strip():
+        return "Informe o host (ex.: localhost ou 10.0.0.5)."
+    if not HOST_RE.match(value.strip()):
+        return "Host inválido. Ex.: localhost, db.empresa.com, 10.0.0.5"
+    return True
+
+
+def validate_port(value: str) -> bool | str:
+    v = value.strip()
+    if not v.isdigit():
+        return "Porta deve ser numérica. Ex.: 8123 (http) ou 8443 (https)."
+    n = int(v)
+    if not 1 <= n <= 65535:
+        return "Porta fora do intervalo 1–65535."
+    return True
+
+
+def validate_username(value: str) -> bool | str:
+    v = value.strip()
+    if not USERNAME_RE.match(v):
+        return "Use letras, números e _ , começando com letra ou _. Ex.: analyst_julho"
+    if v.lower() in {"default", "root", "admin", "system"}:
+        return f"'{v}' é reservado — escolha outro nome."
+    return True
+
+
+def validate_new_password(value: str) -> bool | str:
+    if len(value) < 8:
+        return "Mínimo 8 caracteres (recomendado 12+ com letras + números)."
+    if len(value) > 128:
+        return "Máximo 128 caracteres."
+    return True
+
+
+def validate_at_least_one(selection: list) -> bool | str:
+    if selection:
+        return True
+    return "Selecione pelo menos 1 item (espaço marca, enter confirma)."

clickhouse_users_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: clickhouse-users-cli
+Version: 0.1.0
+Summary: CLI interativa para criar usuarios ClickHouse com privilegio minimo (least privilege)
+License-Expression: MIT
+Keywords: clickhouse,cli,users,access-control,least-privilege
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: clickhouse-connect>=0.8.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file
+
+# ClickHouse Users CLI
+
+CLI interativa em Python com [`questionary`](https://questionary.readthedocs.io/) para criar usuários no ClickHouse com **privilégio mínimo** (least privilege): pergunta credenciais, lista bancos, lista tabelas, define perfil e gera `CREATE USER` + `GRANT`s com preview antes de executar.
+
+## Instalar
+
+```powershell
+pip install clickhouse-users-cli
+ch-users
+```
+
+## Rodar do código-fonte
+
+```powershell
+pip install -r requirements.txt
+python main.py
+```
+
+Requer uma conta admin (ex.: `default`) com permissão `CREATE USER` + `GRANT`.
+Para listar/gerenciar também precisa de `SHOW USERS` + `ALTER USER` / `DROP USER`.
+
+## Menu
+
+Após conectar, escolha: **Criar usuário** · **Listar usuários** · **Gerenciar usuário** · **Sair**.
+O menu fica em loop — dá para criar, auditar e desativar vários sem reconectar.
+
+## Fluxo — criar (6 etapas)
+
+1. **Conexão** — host, protocolo, porta, usuário/senha admin. Testa com `SELECT 1` e permite tentar de novo / editar / sair.
+2. **Tipo de usuário** — perfil (`readonly`, `readwrite`, `admin`, `custom`).
+3. **Novo usuário** — nome validado + senha com confirmação.
+4. **Escopo** — `SHOW DATABASES` → checkbox de bancos → `SHOW TABLES FROM` por banco → checkbox de tabelas (com opção `banco.*`).
+5. **Privilégios + origem** — se `custom`, checkbox de privilégios; depois `HOST ANY | LOCALHOST | IPs`.
+6. **Revisão** — tabela resumo (Rich) + SQL com syntax highlight + confirmação final.
+
+Exemplo do SQL gerado:
+
+```sql
+CREATE USER IF NOT EXISTS `analyst_julho` IDENTIFIED WITH plaintext_password BY '***' HOST ANY;
+GRANT SHOW, SELECT ON `vendas`.`pedidos` TO `analyst_julho`;
+GRANT SHOW, SELECT ON `vendas`.`clientes` TO `analyst_julho`;
+```
+
+## Fluxo — listar / gerenciar
+
+- **Listar** — `SHOW USERS` em tabela + opção de ver `SHOW CREATE USER` e `SHOW GRANTS FOR` de um usuário.
+- **Gerenciar** — escolhe 1 usuário, vê status (`HOST NONE` = inativo) + grants, depois:
+  - **Desativar** → `ALTER USER \`nome\` HOST NONE` (reversível, bloqueia login);
+  - **Reativar** → `ALTER USER \`nome\` HOST ANY`;
+  - **Excluir** → `DROP USER IF EXISTS \`nome\`` (definitivo).
+- Todo DDL mostra preview + confirmação com default `não`. Mexer no próprio usuário logado gera alerta extra.
+
+## Por que cada widget?
+
+| Dado | Widget | Motivo semântico / UX |
+|---|---|---|
+| Host, porta, nomes, IPs | `text` + `validate` + `default` | Entrada livre com validação imediata e exemplo; `default` acelera o caminho feliz (localhost:8123) |
+| Senhas (admin e nova) | `password` (mascarado) | Não ecoa segredo; com validação de tamanho e dupla confirmação no novo usuário |
+| Protocolo (http/https) | `select` | Escolha única em lista pequena; descrição já indica a porta padrão |
+| Perfil | `select` com descrição | 4 opções mutuamente exclusivas; descrição diz o privilégio e o público (analista, engenheiro…) |
+| Bancos, tabelas, privilégios custom | `checkbox` + validação mín. 1 | Multi-seleção com `espaço`; instrução de teclado visível; `banco.*` evita marcar 100 tabelas |
+| Confirmações (IF NOT EXISTS, GRANT OPTION, DROP, executar) | `confirm` com default seguro | Yes/No explícito; default é sempre a opção menos destrutiva |
+| Progresso e erros | `rich.status` (spinner) + `Rule` por etapa | Feedback durante `SHOW DATABASES` / DDL; cabeçalho `1/6…6/6` orienta "onde estou" |
+| Revisão | `rich.table` + `rich.syntax` | Resumo legível + SQL exato que será executado — sem "caixa-preta" |
+
+Decisões de UX:
+
+- **Sistemas por último e desmarcados** (`system`, `information_schema`) para evitar `GRANT` acidental.
+- **Ctrl+C = saída limpa**, nada executa sem confirmação final.
+- **SQL separado da UI** (`clickhouse_users_cli/sql_builder.py`) — dá para testar sem banco.
+- **Escape correto** de identificadores (backticks) e strings (aspas simples).
+- **Perfis com defaults seguros**: `readonly → SHOW+SELECT`, `readwrite → +INSERT`, `admin → ALL + GRANT OPTION`, `custom → você escolhe` (com confirmação extra para `DROP`/`TRUNCATE`).
+
+## Estrutura
+
+```
+main.py                  # entrypoint (dev local)
+requirements.txt
+pyproject.toml           # build + metadados PyPI (comando: ch-users)
+clickhouse_users_cli/
+  __init__.py            # __version__ (fonte única da versão)
+  app.py                 # fluxo questionary (6 etapas)
+  db.py                  # clickhouse-connect: connect, list_databases/tables, execute
+  sql_builder.py         # CREATE USER / GRANT puros (testável)
+  validators.py          # validações por tipo de input
+  style.py               # Style questionary + banner/tabela Rich
+```
+
+## Perfis
+
+- `readonly`: `SHOW, SELECT` — BI, analistas.
+- `readwrite`: `SHOW, SELECT, INSERT` — engenheiros, ingestão.
+- `admin`: `ALL ... WITH GRANT OPTION` em `*.*` — cuidado!
+- `custom`: `SELECT/SHOW/INSERT/CREATE/ALTER/DROP/TRUNCATE/OPTIMIZE/KILL QUERY` à escolha.

clickhouse_users_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+clickhouse_users_cli/__init__.py,sha256=jxMQ7QW-Y91tK4ToZ0GFN6QLUNjjtsrZzC1jNa1ibkQ,134
+clickhouse_users_cli/app.py,sha256=Dj258tLQnnW-2Pr2SansVORhARVhiFRiIHKq3-dgnok,21130
+clickhouse_users_cli/db.py,sha256=3X6FmRSwdsJuGTPguQZEmEmI6LRHrjH6jsaWlFczFYo,3871
+clickhouse_users_cli/sql_builder.py,sha256=fnHSwxOi45zZPEOYJQdqD2C92aWYVOmKuRluYmE39AI,4058
+clickhouse_users_cli/style.py,sha256=aTjmQmXOmUy1uPkP2qSRfO5J7PhuQVuT997-qWQc5XI,1689
+clickhouse_users_cli/validators.py,sha256=3A_FyOfQxJFkjtJl3rZIj1ZQT2rGUjs_7npPAEjIHtQ,1771
+clickhouse_users_cli-0.1.0.dist-info/licenses/LICENSE,sha256=PB9Ow4AGAsl3OiFMkuVOfhtZxzUbzCvFRhLQaBwDdU4,1070
+clickhouse_users_cli-0.1.0.dist-info/METADATA,sha256=wFb_IEg-rMNg5pfj4Q6kvqgi2u2FRfrz_rOm0ZFziwM,5976
+clickhouse_users_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+clickhouse_users_cli-0.1.0.dist-info/entry_points.txt,sha256=Xc-CYZF_4Dq5ChZP_Cy0NE_R3g3QHvSwvfMBIPtgKtY,59
+clickhouse_users_cli-0.1.0.dist-info/top_level.txt,sha256=CRnjGzZQwzXzoLn82wAgVaYiyaxKHPWRAzXRuBwXz4c,21
+clickhouse_users_cli-0.1.0.dist-info/RECORD,,

clickhouse_users_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clickhouse_users_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ch-users = clickhouse_users_cli.app:main

clickhouse_users_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TODO-SEU-NOME
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clickhouse_users_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clickhouse_users_cli