diff --git a/docs/cloud/features/02b_cli.md b/docs/cloud/features/02b_cli.md new file mode 100644 index 00000000000..9973ca1b1ba --- /dev/null +++ b/docs/cloud/features/02b_cli.md @@ -0,0 +1,113 @@ +--- +sidebar_label: 'ClickHouse CLI' +slug: /cloud/features/cli +title: 'ClickHouse CLI' +description: 'Use the ClickHouse CLI to manage ClickHouse Cloud services and local ClickHouse instances' +keywords: ['clickhousectl', 'CLI', 'cloud management', 'local development'] +doc_type: 'reference' +--- + +# ClickHouse CLI {#clickhouse-cli} + +The ClickHouse CLI (`clickhousectl`) is a unified command-line tool for managing ClickHouse Cloud resources, and local development with ClickHouse. + +## Installation {#installation} + +```bash +curl https://clickhouse.com/cli | sh +``` + +A `chctl` alias is also created automatically for convenience. + +## Cloud management {#cloud-management} + +Authenticate with ClickHouse Cloud and manage your services directly from the command line. + +### Authentication {#authentication} + +```bash +clickhousectl cloud auth +``` + +This prompts for your API key and secret, and saves them to `.clickhouse/credentials.json` (project-local, git-ignored). + +You can also use environment variables: + +```bash +export CLICKHOUSE_CLOUD_API_KEY=your-key +export CLICKHOUSE_CLOUD_API_SECRET=your-secret +``` + +### Services {#services} + +```bash +# List services +clickhousectl cloud service list + +# Create a service +clickhousectl cloud service create --name my-service \ + --provider aws \ + --region us-east-1 + +# Get service details +clickhousectl cloud service get + +# Scale a service +clickhousectl cloud service scale \ + --min-replica-memory-gb 24 \ + --max-replica-memory-gb 48 \ + --num-replicas 3 + +# Start/stop a service +clickhousectl cloud service start +clickhousectl cloud service stop + +# Delete a service +clickhousectl cloud service delete +``` + +### Organizations {#organizations} + +```bash +clickhousectl cloud org list +clickhousectl cloud org get +``` + +### API keys {#api-keys} + +```bash +clickhousectl cloud key list +clickhousectl cloud key create --name ci-key --role-id +clickhousectl cloud key delete +``` + +### Members and invitations {#members-and-invitations} + +```bash +clickhousectl cloud member list +clickhousectl cloud invitation create --email dev@example.com --role-id +``` + +### Backups {#backups} + +```bash +clickhousectl cloud backup list +clickhousectl cloud backup get +``` + +### JSON output {#json-output} + +Use the `--json` flag to get JSON-formatted responses from any cloud command: + +```bash +clickhousectl cloud --json service list +``` + +## Local development {#local-development} + +The CLI also manages local ClickHouse installations and servers. See the [quick install](/install/quick-install) page for getting started with local development. + +## Requirements {#requirements} + +- macOS (aarch64, x86_64) or Linux (aarch64, x86_64) +- Cloud commands require a [ClickHouse Cloud API key](/cloud/manage/openapi) diff --git a/docs/cloud/onboard/01_discover/01_what_is.md b/docs/cloud/onboard/01_discover/01_what_is.md index bbf95eaee23..9049858b17a 100644 --- a/docs/cloud/onboard/01_discover/01_what_is.md +++ b/docs/cloud/onboard/01_discover/01_what_is.md @@ -38,6 +38,7 @@ ClickHouse Cloud offers several major benefits over the open-source version: | **ClickPipes** | ClickPipes is ClickHouse's managed ingestion pipeline that allows you to seamlessly connect your external data sources like databases, APIs, and streaming services into ClickHouse Cloud, eliminating the need for managing pipelines, custom jobs, or ETL processes. It supports workloads of all sizes. | ❌ | ✅ | | **Pre-built integrations** | ClickHouse provides pre-built integrations that connect ClickHouse to popular tools and services such as data lakes, SQL and language clients, visualization libraries, and more. | ❌ | ✅ | | **SQL console** | The SQL console offers a fast, intuitive way to connect, explore, and query ClickHouse databases, featuring a slick caption, query interface, data import tools, visualizations, collaboration features, and GenAI-powered SQL assistance. | ❌ | ✅ | +| **ClickHouse CLI** | The ClickHouse CLI (`clickhousectl`) lets you install and manage local ClickHouse versions, launch servers, run queries, and manage ClickHouse Cloud services and resources. | ✅ | ✅ | | **Compliance** | ClickHouse Cloud compliance includes CCPA, EU-US DPF, GDPR, HIPAA, ISO 27001, ISO 27001 SoA, PCI DSS, SOC2. ClickHouse Cloud's security, availability, processing integrity, and confidentiality processes are all independently audited. Details: trust.clickhouse.com. | ❌ | ✅ | | **Enterprise-grade security** | Support for advanced security features such as SSO, multi-factor authentication, role-based access control (RBAC), private and secure connections with support for Private Link and Private Service Connect, IP filtering, customer-managed encryption keys (CMEK), and more. | ❌ | ✅ | | **Scaling and optimization** | Seamlessly scales up or down based on workload, supporting both horizontal and vertical scaling. With automated backups, replication, and high availability, ClickHouse, it provides users with optimal resource allocation. | ❌ | ✅ | diff --git a/docs/deployment-modes.md b/docs/deployment-modes.md index 59bbf9e25f3..a1a51ccaf80 100644 --- a/docs/deployment-modes.md +++ b/docs/deployment-modes.md @@ -1,7 +1,7 @@ --- slug: /deployment-modes sidebar_label: 'Deployment modes' -description: 'ClickHouse offers four deployment options that all use the same powerful database engine, just packaged differently to suit your specific needs.' +description: 'ClickHouse offers five deployment options that all use the same powerful database engine, just packaged differently to suit your specific needs.' title: 'Deployment modes' keywords: ['Deployment Modes', 'chDB'] show_related_blogs: true @@ -17,10 +17,11 @@ import Image from '@theme/IdealImage'; ClickHouse is a versatile database system that can be deployed in several different ways depending on your needs. At its core, all deployment options **use the same powerful ClickHouse database engine** – what differs is how you interact with it and where it runs. Whether you're running large-scale analytics in production, doing local data analysis, or building applications, there's a deployment option designed for your use case. The consistency of the underlying engine means you get the same high performance and SQL compatibility across all deployment modes. -This guide explores the four main ways to deploy and use ClickHouse: +This guide explores the five main ways to deploy and use ClickHouse: * ClickHouse Server for traditional client/server deployments * ClickHouse Cloud for fully managed database operations +* ClickHouse CLI for local development and cloud management * clickhouse-local for command-line data processing * chDB for embedding ClickHouse directly in applications @@ -54,6 +55,24 @@ For monitoring and optimization, ClickHouse Cloud includes built-in charts and [ The managed nature of the service means you don't need to worry about updates, backups, scaling, or security patches – these are all handled automatically. This makes it an ideal choice for organizations that want to focus on their data and applications rather than database administration. +## ClickHouse CLI {#clickhouse-cli} + +The ClickHouse CLI (`clickhousectl`) is a command-line tool for local ClickHouse development and ClickHouse Cloud management. It simplifies the workflow of installing ClickHouse versions, launching and managing local server instances, and running queries. + +For local development, `clickhousectl` helps to install ClickHouse versions and run servers. You can install any ClickHouse version, spin up named servers, and connect via the built-in client. Each server gets its own data directory, so you can run multiple isolated environments side by side. + +`clickhousectl` also provides full management of ClickHouse Cloud resources, including creating and scaling services, managing API keys, and administering organizations, making it a unified tool for both local and cloud workflows. + +```bash +# Install the CLI +curl https://clickhouse.com/cli | sh + +# Install and start ClickHouse locally +clickhousectl local install stable +clickhousectl local server start +clickhousectl local client +``` + ## clickhouse-local {#clickhouse-local} [clickhouse-local](/operations/utilities/clickhouse-local) is a powerful command-line tool that provides the complete functionality of ClickHouse in a standalone executable. It's essentially the same database as ClickHouse Server, but packaged in a way that lets you harness all of ClickHouse's capabilities directly from the command line without running a server instance. diff --git a/docs/getting-started/install/_snippets/_cli_install.md b/docs/getting-started/install/_snippets/_cli_install.md new file mode 100644 index 00000000000..accf6e125c3 --- /dev/null +++ b/docs/getting-started/install/_snippets/_cli_install.md @@ -0,0 +1,66 @@ +# Install ClickHouse using the ClickHouse CLI + +The ClickHouse CLI (`clickhousectl`) helps you install and manage local ClickHouse +versions, launch servers, and run queries. + + + +## Install the ClickHouse CLI {#install-the-cli} + +```bash +curl https://clickhouse.com/cli | sh +``` + +A `chctl` alias is also created automatically for convenience. + +## Install ClickHouse {#cli-install-clickhouse} + +Install the latest stable version of ClickHouse: + +```bash +clickhousectl local install stable +``` + +You can also install a specific version: + +```bash +clickhousectl local install lts # Latest LTS release +clickhousectl local install 25.6 # Latest 25.6.x.x +clickhousectl local install 25.6.1.1 # Exact version +``` + +## Start clickhouse-server {#cli-start-clickhouse-server} + +```bash +clickhousectl local server start +``` + +The server runs in the background. To verify it's running: + +```bash +clickhousectl local server list +``` + +## Start clickhouse-client {#cli-start-clickhouse-client} + +```bash +clickhousectl local client +``` + +You will see something like this: + +```response +ClickHouse client version 24.5.1.117 (official build). +Connecting to localhost:9000 as user default. +Connected to ClickHouse server version 24.5.1. + +local-host :) +``` + +You're now ready to start sending SQL commands to ClickHouse! + +:::tip +The [Quick Start](/get-started/quick-start) walks you through the steps for creating tables and inserting data. +::: + + diff --git a/docs/getting-started/install/_snippets/_quick_install.md b/docs/getting-started/install/_snippets/_quick_install.md index 19ebcf5b8da..841e7f801c3 100644 --- a/docs/getting-started/install/_snippets/_quick_install.md +++ b/docs/getting-started/install/_snippets/_quick_install.md @@ -1,8 +1,6 @@ # Install ClickHouse via script using curl -If you don't need to install ClickHouse for production, the quickest way to get -set up is to run an install script using curl. The script will determine a suitable -binary for your OS. +If you don't need to install ClickHouse for production, you can run an install script using curl. The script will determine a suitable binary for your OS. diff --git a/docs/getting-started/install/install.mdx b/docs/getting-started/install/install.mdx index 44701558e92..10b4c247ac5 100644 --- a/docs/getting-started/install/install.mdx +++ b/docs/getting-started/install/install.mdx @@ -8,6 +8,7 @@ doc_type: 'guide' --- import InstallSelector from '@site/src/components/Install/Install' +import CLIInstall from './_snippets/_cli_install.md' import Windows from './_snippets/_windows_install.md' import TarProd from './_snippets/_linux_tar_install.md' import QuickInstall from './_snippets/_quick_install.md' @@ -40,6 +41,7 @@ Alternatively, select a platform, distribution and install method below to view instructions for Opensource ClickHouse: } windows={} quickinstall={} debian_prod={} diff --git a/docs/getting-started/install/quick-install-curl.md b/docs/getting-started/install/quick-install-curl.md deleted file mode 100644 index b8de0052cfd..00000000000 --- a/docs/getting-started/install/quick-install-curl.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: 'Install ClickHouse on any platform using curl' -keywords: ['ClickHouse', 'install', 'quick', 'curl'] -sidebar_label: 'Quick install' -slug: /install/quick-install-curl -title: 'Install ClickHouse via script using curl' -hide_title: true -doc_type: 'guide' ---- - -import QuickInstall from './_snippets/_quick_install.md' - - diff --git a/docs/getting-started/install/quick-install.md b/docs/getting-started/install/quick-install.md new file mode 100644 index 00000000000..6f3169b510c --- /dev/null +++ b/docs/getting-started/install/quick-install.md @@ -0,0 +1,84 @@ +--- +description: 'Quickly install ClickHouse using the CLI or curl' +keywords: ['ClickHouse', 'install', 'quick', 'curl', 'clickhousectl', 'CLI'] +sidebar_label: 'Quick install' +slug: /install/quick-install +title: 'Quick install' +hide_title: true +doc_type: 'guide' +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import QuickInstall from './_snippets/_quick_install.md' + +# Quick install + +If you don't need to install ClickHouse for production, the quickest way to get +set up is using the ClickHouse CLI or running an install script using curl. + + + + +The ClickHouse CLI (`clickhousectl`) helps you install and manage local ClickHouse +versions, launch servers, and run queries. + + + +## Install the ClickHouse CLI {#install-the-cli} + +```bash +curl https://clickhouse.com/cli | sh +``` + +A `chctl` alias is also created automatically for convenience. + +## Install ClickHouse {#install-clickhouse} + +```bash +clickhousectl local install stable +``` + +## Start clickhouse-server {#start-clickhouse-server} + +```bash +clickhousectl local server start +``` + +The server runs in the background. To verify it's running: + +```bash +clickhousectl local server list +``` + +## Start clickhouse-client {#start-clickhouse-client} + +```bash +clickhousectl local client +``` + +You will see something like this: + +```response +ClickHouse client version 24.5.1.117 (official build). +Connecting to localhost:9000 as user default. +Connected to ClickHouse server version 24.5.1. + +local-host :) +``` + +You're now ready to start sending SQL commands to ClickHouse! + +:::tip +The [Quick Start](/get-started/quick-start) walks you through the steps for creating tables and inserting data. +::: + + + + + + + + + + diff --git a/docs/getting-started/quick-start/oss.mdx b/docs/getting-started/quick-start/oss.mdx index a97c0c5ae92..ff08d28ceee 100644 --- a/docs/getting-started/quick-start/oss.mdx +++ b/docs/getting-started/quick-start/oss.mdx @@ -16,72 +16,60 @@ import {VerticalStepper} from '@clickhouse/click-ui/bundled'; # ClickHouse OSS quick start -> In this quick start tutorial, we'll get you set up with open-source ClickHouse in 8 -easy steps. You'll download an appropriate binary for your OS, -learn to run ClickHouse server, and use the ClickHouse client to create a table, -then insert data into it and run a query to select that data. -> -> Are you looking for the Cloud quick start instead? [Go here](/get-started/quick-start). +> In this quick start tutorial, we'll get you set up with OSS ClickHouse in 8 +easy steps. You'll use the ClickHouse CLI `clickhousectl` to install ClickHouse, +start a ClickHouse server, connect to your server to create a table, +insert data into it, and run a SELECT query. -## Download ClickHouse \{#download-the-binary\} +## Install the ClickHouse CLI \{#install-the-cli\} -ClickHouse runs natively on Linux, FreeBSD and macOS, and runs on Windows via -the [WSL](https://learn.microsoft.com/en-us/windows/wsl/about). The simplest way to download ClickHouse locally is to run the -following `curl` command. It determines if your operating system is supported, -then downloads an appropriate ClickHouse binary built from master branch. - -:::note -We recommend running the command below from a new and empty subdirectory as -some configuration files will be created in the directory the binary is located -in the first time ClickHouse server is run. - -The script below isn't the recommended way to install ClickHouse for production. -If you're looking to install a production instance of ClickHouse, please see the [install page](/install). -::: +The ClickHouse CLI (`clickhousectl`) helps you install and manage local ClickHouse +versions, launch servers, and run queries. Install it with: ```bash -curl https://clickhouse.com/ | sh +curl https://clickhouse.com/cli | sh ``` -You should see: +A `chctl` alias is also created automatically for convenience. -``` -Successfully downloaded the ClickHouse binary, you can run it as: - ./clickhouse +## Install ClickHouse \{#install-clickhouse\} -You can also install it: -sudo ./clickhouse install -``` +ClickHouse runs natively on Linux and macOS, and runs on Windows via +the [WSL](https://learn.microsoft.com/en-us/windows/wsl/about). -At this stage, you can ignore the prompt to run the `install` command. +Use the CLI to install the latest stable version of ClickHouse: + +```bash +clickhousectl local install stable +``` :::note -For Mac users: If you're getting errors that the developer of the binary can't -be verified, please see ["Fix the Developer Verification Error in MacOS"](https://clickhouse.com/docs/knowledgebase/fix-developer-verification-error-in-macos). +This isn't the recommended way to install ClickHouse for production. +If you're looking to install a production instance of ClickHouse, please see the [install page](/install). ::: -## Start the server +## Start the server \{#start-the-server\} -Run the following command to start the ClickHouse server: +Start a ClickHouse server instance: ```bash -./clickhouse server +clickhousectl local server start --name my-first-server ``` -You should see the terminal fill up with logging. This is expected. In ClickHouse -the [default logging level](https://clickhouse.com/docs/knowledgebase/why_default_logging_verbose) -is set to `trace` rather than `warning`. +The server runs in the background by default. To verify it's running: + +```bash +clickhousectl local server list +``` -## Start the client +## Start the client \{#start-the-client\} -Use `clickhouse-client` to connect to your ClickHouse service. Open a new -terminal, change directories to where your `clickhouse` binary is saved, and -run the following command: +Connect to your running ClickHouse server: ```bash -./clickhouse client +clickhousectl local client --name my-first-server ``` You should see a smiling face as it connects to your service running on localhost: diff --git a/sidebars.js b/sidebars.js index 210a243d73c..9cb55dfe72d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -41,7 +41,7 @@ const sidebars = { 'getting-started/install/macos', 'getting-started/install/windows', 'getting-started/install/docker', - 'getting-started/install/quick-install-curl', + 'getting-started/install/quick-install', 'getting-started/install/advanced', ], }, diff --git a/src/components/Install/Install.js b/src/components/Install/Install.js index b8c8971223c..cb0b3075b64 100644 --- a/src/components/Install/Install.js +++ b/src/components/Install/Install.js @@ -5,6 +5,7 @@ const InstallSelector = (props) => { const [platform, setPlatformType] = useState(null) + const handleSelectCLI = () => setPlatformType('CLI'); const handleSelectMacOS = () => setPlatformType('MacOS'); const handleSelectWindows = () => setPlatformType('Windows'); const handleSelectDocker = () => setPlatformType('Docker'); @@ -19,6 +20,16 @@ const InstallSelector = (props) => { const renderDistribution = () => { if (1) { return
+ { } } const renderInstallInstructions = (props) => { - if (platform === 'Debian') { + if (platform === 'CLI') { + return props.cli + } else if (platform === 'Debian') { return props.debian_prod } else if (platform === 'Ubuntu') { return props.debian_prod diff --git a/vercel.json b/vercel.json index 29688606c3c..a749f3521fb 100644 --- a/vercel.json +++ b/vercel.json @@ -22,6 +22,16 @@ } ] }, + { + "source": "/docs/install/quick-install-curl", + "destination": "/docs/install/quick-install", + "permanent": true + }, + { + "source": "/docs/en/install/quick-install-curl", + "destination": "/docs/install/quick-install", + "permanent": true + }, { "source": "/docs/integrations/clickpipes/secure-kinesis", "destination": "/docs/integrations/clickpipes/kinesis/auth",