Implementation:ClickHouse ClickHouse Server Process Stop

Knowledge Sources	ClickHouse
Domains	Testing
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for stopping a locally running ClickHouse server process, provided by standard Unix process management utilities.

Description

After completing a test session, the ClickHouse server process must be stopped to free ports and system resources. The recommended procedure, documented in .claude/instructions.md (lines 48-49), uses two standard Unix commands:

1. pgrep -f "clickhouse server" -- Searches the process table for processes whose full command line matches the pattern "clickhouse server". The -f flag is essential because it matches against the entire command line, not just the process name. This returns one or more PIDs.
2. kill <pid> -- Sends SIGTERM (signal 15) to the identified process(es). The server handles SIGTERM gracefully: it stops accepting new connections, waits for in-flight queries to complete (within a timeout), flushes internal buffers and write-ahead logs to disk, and then exits.

This approach is preferred over recording PIDs in files because:

• It works regardless of how the server was started (foreground, background, or from a script).
• It does not depend on PID files that may become stale.
• It correctly handles multiple server instances if they exist.

After the server shuts down, all data directories (containing table data, metadata, and system logs) and server log files remain on disk and are available for inspection.

Usage

Use this procedure after finishing a test session, before starting a different server build, or whenever you need to reclaim the ports that the server is occupying (typically 9000 and 8123).

Code Reference

Source Location

• Repository: ClickHouse
• File: .claude/instructions.md lines 48-49

Signature

# Step 1: Find the server process ID(s)
pgrep -f "clickhouse server"

# Step 2: Terminate the server
kill <pid>

I/O Contract

Inputs

Name	Type	Required	Description
-f "clickhouse server"	Pattern string (passed to pgrep)	Yes	Full command-line pattern to match the running ClickHouse server process
Running ClickHouse server PID	Process ID (integer)	Yes	The PID returned by pgrep, passed to kill

Outputs

Name	Type	Description
Server process terminated	Process state change	The ClickHouse server process receives SIGTERM and performs a graceful shutdown
Data directories preserved	Filesystem state	All table data, metadata, and write-ahead logs remain intact on disk
Server logs preserved	Filesystem state	Log files written during the server session remain available for post-mortem analysis
Ports released	Network state	TCP port 9000 and HTTP port 8123 (or other configured ports) become available for new processes

Usage Examples

Standard shutdown procedure:

# Find the ClickHouse server process
pgrep -f "clickhouse server"
# Example output:
# 12345
# 12346

# Stop the server processes
kill 12345 12346

One-liner to find and stop all ClickHouse server processes:

kill $(pgrep -f "clickhouse server")

Verify the server has stopped:

# Should return no output if the server has exited
pgrep -f "clickhouse server"

Force-stop an unresponsive server (use only as a last resort):

# SIGKILL bypasses graceful shutdown -- may leave data in inconsistent state
kill -9 $(pgrep -f "clickhouse server")

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Server_Process_Management

Requires Environment

• Environment:ClickHouse_ClickHouse_Python3_Test_Environment