先决条件

ClickHouse 可以在 Linux、FreeBSD 和 macOS 上构建。如果您使用 Windows，您仍然可以在运行 Linux 的虚拟机中构建 ClickHouse，例如使用 Ubuntu 的 VirtualBox。

在 GitHub 上创建仓库

要开始为 ClickHouse 开发，您需要一个 GitHub 帐户。还请在本地生成 SSH 密钥（如果您还没有），并将公钥上传到 GitHub，这是贡献补丁的先决条件。

接下来，通过单击右上角的“fork”按钮，在您的个人帐户中 fork ClickHouse 仓库。

要贡献更改，例如，问题的修复或功能，首先将您的更改提交到您的 fork 的分支，然后创建一个“Pull Request”，将更改提交到主仓库。

为了使用 Git 仓库，请安装 Git。例如，在 Ubuntu 中，运行

sudo apt update
sudo apt install git

Git 速查表可以在这里找到。详细的 Git 手册在这里。

将仓库克隆到您的开发机器

首先，将源文件下载到您的工作机器，即克隆仓库

git clone [email protected]:your_github_username/ClickHouse.git  # replace the placeholder with your GitHub user name
cd ClickHouse

此命令创建一个包含源代码、测试和其他文件的 ClickHouse/ 目录。您可以在 URL 之后为检出指定自定义目录，但重要的是此路径不包含空格，因为这可能会在以后破坏构建。

ClickHouse 的 Git 仓库使用子模块来拉取第三方库。默认情况下不检出子模块。您可以

使用选项 --recurse-submodules 运行 git clone，
如果 git clone 在没有 --recurse-submodules 的情况下运行，运行 git submodule update --init --jobs <N> 以显式检出所有子模块。（<N> 可以设置为例如 12 以并行下载。）
如果 git clone 在没有 --recurse-submodules 的情况下运行，并且您想使用 sparse 和 shallow 子模块检出以省略子模块中不需要的文件和历史记录以节省空间（大约 5 GB 而不是大约 15 GB），运行 ./contrib/update-submodules.sh。 CI 使用此替代方法，但不建议用于本地开发，因为它使使用子模块不太方便且速度较慢。

要检查 Git 子模块的状态，请运行 git submodule status。

如果您收到以下错误消息

Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

连接到 GitHub 的 SSH 密钥丢失。这些密钥通常位于 ~/.ssh 中。为了使 SSH 密钥被接受，您需要在 GitHub 的设置中上传它们。

您也可以通过 HTTPS 克隆仓库

git clone https://github.com/ClickHouse/ClickHouse.git

但是，这将不允许您将更改发送到服务器。您仍然可以暂时使用它，并在以后添加 SSH 密钥，用 git remote 命令替换仓库的远程地址。

您还可以将原始 ClickHouse 仓库地址添加到您的本地仓库，以便从那里拉取更新

git remote add upstream [email protected]:ClickHouse/ClickHouse.git

成功运行此命令后，您将能够通过运行 git pull upstream master 从主 ClickHouse 仓库拉取更新。

编写代码

下面您可以找到一些快速链接，这些链接在为 ClickHouse 编写代码时可能很有用

IDE

CLion（推荐）

如果您不知道使用哪个 IDE，我们建议您使用 CLion。 CLion 是商业软件，但它提供 30 天免费试用。学生也可以免费使用。 CLion 可以在 Linux 和 macOS 上使用。

使用 CLion 开发 ClickHouse 时需要了解的一些事项

CLion 会自行创建一个 build 路径，并自动选择 debug 作为构建类型
它使用 CLion 中定义的 CMake 版本，而不是您安装的版本
CLion 将使用 make 运行构建任务，而不是 ninja（这是正常行为）

替代方案

KDevelop 和 QTCreator 是开发 ClickHouse 的其他优秀替代 IDE。虽然 KDevelop 是一个很棒的 IDE，但有时不稳定。如果 KDevelop 在打开项目时崩溃，您应该在它打开项目文件列表后立即单击“Stop All”按钮。这样做之后，KDevelop 应该可以正常工作了。

您可以使用的其他 IDE 包括 Sublime Text、Visual Studio Code 或 Kate（所有这些都可在 Linux 上使用）。如果您使用 VS Code，我们建议使用 clangd 扩展来替换 IntelliSense，因为它性能更高。

创建拉取请求

导航到 GitHub UI 中的 fork 仓库。如果您一直在分支中开发，则需要选择该分支。屏幕上会有一个“Pull request”按钮。实质上，这意味着“创建一个请求，将我的更改接受到主仓库中”。

即使工作尚未完成，也可以创建拉取请求。在这种情况下，请在标题开头加上单词“WIP”（正在进行中），稍后可以更改。这对于协作审查和讨论更改以及运行所有可用测试非常有用。重要的是您提供更改的简要描述，它稍后将用于生成发布更新日志。

一旦 ClickHouse 员工用标签“can be tested”标记您的 PR，测试将立即开始。一些初步检查（例如，代码风格）的结果将在几分钟内出现。构建检查结果将在半小时内到达。主要测试集将在一个小时内报告自身。

系统将单独为您的拉取请求准备 ClickHouse 二进制构建。要检索这些构建，请单击检查列表中“Builds”条目旁边的“Details”链接。在那里，您将找到指向已构建的 ClickHouse .deb 包的直接链接，即使在您的生产服务器上也可以部署（如果您不害怕）。

编写文档

每个添加新功能的拉取请求都必须附带适当的文档。如果您想预览您的文档更改，请参阅这里的 README.md 文件，其中提供了如何在本地构建文档页面的说明。当向 ClickHouse 添加新函数时，您可以使用下面的模板作为指南

# newFunctionName

A short description of the function goes here. It should describe briefly what it does and a typical usage case.

**Syntax**

\```sql
newFunctionName(arg1, arg2[, arg3])
\```

**Arguments**

- `arg1` — Description of the argument. [DataType](../data-types/float.md)
- `arg2` — Description of the argument. [DataType](../data-types/float.md)
- `arg3` — Description of optional argument (optional). [DataType](../data-types/float.md)

**Implementation Details**

A description of implementation details if relevant.

**Returned value**

- Returns {insert what the function returns here}. [DataType](../data-types/float.md)

**Example**

Query:

\```sql
SELECT 'write your example query here';
\```

Response:

\```response
┌───────────────────────────────────┐
│ the result of the query           │
└───────────────────────────────────┘
\```

使用测试数据

开发 ClickHouse 通常需要加载真实数据集。这对于性能测试尤为重要。我们有一组专门准备的匿名网络分析数据。它还需要额外约 3GB 的可用磁盘空间。

    sudo apt install wget xz-utils

    wget https://datasets.clickhouse.com/hits/tsv/hits_v1.tsv.xz
    wget https://datasets.clickhouse.com/visits/tsv/visits_v1.tsv.xz

    xz -v -d hits_v1.tsv.xz
    xz -v -d visits_v1.tsv.xz

    clickhouse-client

在 clickhouse-client 中

CREATE DATABASE IF NOT EXISTS test

CREATE TABLE test.hits ( WatchID UInt64,  JavaEnable UInt8,  Title String,  GoodEvent Int16,  EventTime DateTime,  EventDate Date,  CounterID UInt32,  ClientIP UInt32,  ClientIP6 FixedString(16),  RegionID UInt32,  UserID UInt64,  CounterClass Int8,  OS UInt8,  UserAgent UInt8,  URL String,  Referer String,  URLDomain String,  RefererDomain String,  Refresh UInt8,  IsRobot UInt8,  RefererCategories Array(UInt16),  URLCategories Array(UInt16),  URLRegions Array(UInt32),  RefererRegions Array(UInt32),  ResolutionWidth UInt16,  ResolutionHeight UInt16,  ResolutionDepth UInt8,  FlashMajor UInt8,  FlashMinor UInt8,  FlashMinor2 String,  NetMajor UInt8,  NetMinor UInt8,  UserAgentMajor UInt16,  UserAgentMinor FixedString(2),  CookieEnable UInt8,  JavascriptEnable UInt8,  IsMobile UInt8,  MobilePhone UInt8,  MobilePhoneModel String,  Params String,  IPNetworkID UInt32,  TraficSourceID Int8,  SearchEngineID UInt16,  SearchPhrase String,  AdvEngineID UInt8,  IsArtifical UInt8,  WindowClientWidth UInt16,  WindowClientHeight UInt16,  ClientTimeZone Int16,  ClientEventTime DateTime,  SilverlightVersion1 UInt8,  SilverlightVersion2 UInt8,  SilverlightVersion3 UInt32,  SilverlightVersion4 UInt16,  PageCharset String,  CodeVersion UInt32,  IsLink UInt8,  IsDownload UInt8,  IsNotBounce UInt8,  FUniqID UInt64,  HID UInt32,  IsOldCounter UInt8,  IsEvent UInt8,  IsParameter UInt8,  DontCountHits UInt8,  WithHash UInt8,  HitColor FixedString(1),  UTCEventTime DateTime,  Age UInt8,  Sex UInt8,  Income UInt8,  Interests UInt16,  Robotness UInt8,  GeneralInterests Array(UInt16),  RemoteIP UInt32,  RemoteIP6 FixedString(16),  WindowName Int32,  OpenerName Int32,  HistoryLength Int16,  BrowserLanguage FixedString(2),  BrowserCountry FixedString(2),  SocialNetwork String,  SocialAction String,  HTTPError UInt16,  SendTiming Int32,  DNSTiming Int32,  ConnectTiming Int32,  ResponseStartTiming Int32,  ResponseEndTiming Int32,  FetchTiming Int32,  RedirectTiming Int32,  DOMInteractiveTiming Int32,  DOMContentLoadedTiming Int32,  DOMCompleteTiming Int32,  LoadEventStartTiming Int32,  LoadEventEndTiming Int32,  NSToDOMContentLoadedTiming Int32,  FirstPaintTiming Int32,  RedirectCount Int8,  SocialSourceNetworkID UInt8,  SocialSourcePage String,  ParamPrice Int64,  ParamOrderID String,  ParamCurrency FixedString(3),  ParamCurrencyID UInt16,  GoalsReached Array(UInt32),  OpenstatServiceName String,  OpenstatCampaignID String,  OpenstatAdID String,  OpenstatSourceID String,  UTMSource String,  UTMMedium String,  UTMCampaign String,  UTMContent String,  UTMTerm String,  FromTag String,  HasGCLID UInt8,  RefererHash UInt64,  URLHash UInt64,  CLID UInt32,  YCLID UInt64,  ShareService String,  ShareURL String,  ShareTitle String,  `ParsedParams.Key1` Array(String),  `ParsedParams.Key2` Array(String),  `ParsedParams.Key3` Array(String),  `ParsedParams.Key4` Array(String),  `ParsedParams.Key5` Array(String),  `ParsedParams.ValueDouble` Array(Float64),  IslandID FixedString(16),  RequestNum UInt32,  RequestTry UInt8) ENGINE = MergeTree PARTITION BY toYYYYMM(EventDate) SAMPLE BY intHash32(UserID) ORDER BY (CounterID, EventDate, intHash32(UserID), EventTime);

CREATE TABLE test.visits ( CounterID UInt32,  StartDate Date,  Sign Int8,  IsNew UInt8,  VisitID UInt64,  UserID UInt64,  StartTime DateTime,  Duration UInt32,  UTCStartTime DateTime,  PageViews Int32,  Hits Int32,  IsBounce UInt8,  Referer String,  StartURL String,  RefererDomain String,  StartURLDomain String,  EndURL String,  LinkURL String,  IsDownload UInt8,  TraficSourceID Int8,  SearchEngineID UInt16,  SearchPhrase String,  AdvEngineID UInt8,  PlaceID Int32,  RefererCategories Array(UInt16),  URLCategories Array(UInt16),  URLRegions Array(UInt32),  RefererRegions Array(UInt32),  IsYandex UInt8,  GoalReachesDepth Int32,  GoalReachesURL Int32,  GoalReachesAny Int32,  SocialSourceNetworkID UInt8,  SocialSourcePage String,  MobilePhoneModel String,  ClientEventTime DateTime,  RegionID UInt32,  ClientIP UInt32,  ClientIP6 FixedString(16),  RemoteIP UInt32,  RemoteIP6 FixedString(16),  IPNetworkID UInt32,  SilverlightVersion3 UInt32,  CodeVersion UInt32,  ResolutionWidth UInt16,  ResolutionHeight UInt16,  UserAgentMajor UInt16,  UserAgentMinor UInt16,  WindowClientWidth UInt16,  WindowClientHeight UInt16,  SilverlightVersion2 UInt8,  SilverlightVersion4 UInt16,  FlashVersion3 UInt16,  FlashVersion4 UInt16,  ClientTimeZone Int16,  OS UInt8,  UserAgent UInt8,  ResolutionDepth UInt8,  FlashMajor UInt8,  FlashMinor UInt8,  NetMajor UInt8,  NetMinor UInt8,  MobilePhone UInt8,  SilverlightVersion1 UInt8,  Age UInt8,  Sex UInt8,  Income UInt8,  JavaEnable UInt8,  CookieEnable UInt8,  JavascriptEnable UInt8,  IsMobile UInt8,  BrowserLanguage UInt16,  BrowserCountry UInt16,  Interests UInt16,  Robotness UInt8,  GeneralInterests Array(UInt16),  Params Array(String),  `Goals.ID` Array(UInt32),  `Goals.Serial` Array(UInt32),  `Goals.EventTime` Array(DateTime),  `Goals.Price` Array(Int64),  `Goals.OrderID` Array(String),  `Goals.CurrencyID` Array(UInt32),  WatchIDs Array(UInt64),  ParamSumPrice Int64,  ParamCurrency FixedString(3),  ParamCurrencyID UInt16,  ClickLogID UInt64,  ClickEventID Int32,  ClickGoodEvent Int32,  ClickEventTime DateTime,  ClickPriorityID Int32,  ClickPhraseID Int32,  ClickPageID Int32,  ClickPlaceID Int32,  ClickTypeID Int32,  ClickResourceID Int32,  ClickCost UInt32,  ClickClientIP UInt32,  ClickDomainID UInt32,  ClickURL String,  ClickAttempt UInt8,  ClickOrderID UInt32,  ClickBannerID UInt32,  ClickMarketCategoryID UInt32,  ClickMarketPP UInt32,  ClickMarketCategoryName String,  ClickMarketPPName String,  ClickAWAPSCampaignName String,  ClickPageName String,  ClickTargetType UInt16,  ClickTargetPhraseID UInt64,  ClickContextType UInt8,  ClickSelectType Int8,  ClickOptions String,  ClickGroupBannerID Int32,  OpenstatServiceName String,  OpenstatCampaignID String,  OpenstatAdID String,  OpenstatSourceID String,  UTMSource String,  UTMMedium String,  UTMCampaign String,  UTMContent String,  UTMTerm String,  FromTag String,  HasGCLID UInt8,  FirstVisit DateTime,  PredLastVisit Date,  LastVisit Date,  TotalVisits UInt32,  `TraficSource.ID` Array(Int8),  `TraficSource.SearchEngineID` Array(UInt16),  `TraficSource.AdvEngineID` Array(UInt8),  `TraficSource.PlaceID` Array(UInt16),  `TraficSource.SocialSourceNetworkID` Array(UInt8),  `TraficSource.Domain` Array(String),  `TraficSource.SearchPhrase` Array(String),  `TraficSource.SocialSourcePage` Array(String),  Attendance FixedString(16),  CLID UInt32,  YCLID UInt64,  NormalizedRefererHash UInt64,  SearchPhraseHash UInt64,  RefererDomainHash UInt64,  NormalizedStartURLHash UInt64,  StartURLDomainHash UInt64,  NormalizedEndURLHash UInt64,  TopLevelDomain UInt64,  URLScheme UInt64,  OpenstatServiceNameHash UInt64,  OpenstatCampaignIDHash UInt64,  OpenstatAdIDHash UInt64,  OpenstatSourceIDHash UInt64,  UTMSourceHash UInt64,  UTMMediumHash UInt64,  UTMCampaignHash UInt64,  UTMContentHash UInt64,  UTMTermHash UInt64,  FromHash UInt64,  WebVisorEnabled UInt8,  WebVisorActivity UInt32,  `ParsedParams.Key1` Array(String),  `ParsedParams.Key2` Array(String),  `ParsedParams.Key3` Array(String),  `ParsedParams.Key4` Array(String),  `ParsedParams.Key5` Array(String),  `ParsedParams.ValueDouble` Array(Float64),  `Market.Type` Array(UInt8),  `Market.GoalID` Array(UInt32),  `Market.OrderID` Array(String),  `Market.OrderPrice` Array(Int64),  `Market.PP` Array(UInt32),  `Market.DirectPlaceID` Array(UInt32),  `Market.DirectOrderID` Array(UInt32),  `Market.DirectBannerID` Array(UInt32),  `Market.GoodID` Array(String),  `Market.GoodName` Array(String),  `Market.GoodQuantity` Array(Int32),  `Market.GoodPrice` Array(Int64),  IslandID FixedString(16)) ENGINE = CollapsingMergeTree(Sign) PARTITION BY toYYYYMM(StartDate) SAMPLE BY intHash32(UserID) ORDER BY (CounterID, StartDate, intHash32(UserID), VisitID);

导入数据

clickhouse-client --max_insert_block_size 100000 --query "INSERT INTO test.hits FORMAT TSV" < hits_v1.tsv
clickhouse-client --max_insert_block_size 100000 --query "INSERT INTO test.visits FORMAT TSV" < visits_v1.tsv

在 GitHub 上创建仓库​

将仓库克隆到您的开发机器​

编写代码​

IDE​

创建拉取请求​

编写文档​

使用测试数据​