<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/dolthub/doltgresql) · [上游 README](https://github.com/dolthub/doltgresql/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Doltgres 是面向 Postgres 的 Dolt！


来自 [Dolt](https://www.doltdb.com), 全球首个支持版本控制的 SQL
数据库的创作者，现推出 [Doltgres](https://www.doltgres.com), Dolt 的 Postgres 版本。这是一款 SQL
数据库，你可以像使用 Git 仓库一样对它进行分支（branch）与合并（merge）、复刻（fork）与克隆（clone）、推送（push）与拉取（pull）。你可以像连接任何 Postgres 数据库一样连接到 Doltgres 服务器来读取或修改 schema
和数据。版本控制功能通过 SQL 中的系统表、函数和存储过程公开。

Git 为文件做版本控制，Doltgres 为表做版本控制。它就像是 Git 和 Postgres 的孩子。

# Doltgres 处于 Beta 阶段

[Doltgres 现已达到 Beta 质量](https://dolthub.com/blog/2025-04-16-doltgres-goes-beta/), 这意味着
它已可用于你的生产场景。仍会有 bug 和功能缺失，但如果你 [提交 issue](https://github.com/dolthub/doltgresql/issues).
[我们大多能在 24 小时内修复](https://www.dolthub.com/blog/2024-05-15-24-hour-bug-fixes/)

等待结束了！现在是 [试用 Doltgres](#getting-started) 并告诉我们你的想法的时候了。使用 `pg_dump` 和 `psql` 将你现有的 Postgres 数据库导入 Doltgres，如果有任何不工作的地方请告诉我们。

如果你对这个项目感到兴奋，还可以通过以下几种方式帮助推动项目进展：

- 给本仓库点 Star
- 如果发现 bug，请创建 [issues](https://github.com/dolthub/doltgresql/issues)
- 为你想要但缺失的功能创建 [issues](https://github.com/dolthub/doltgresql/issues)
- 为你想要的功能贡献代码（参见 [贡献指南](https://github.com/dolthub/doltgresql/blob/main/CONTRIBUTING.md))
- 告诉你的朋友和同事

# 完整文档

Doltgres 拥有 [文档网站](https://doltgres.com/docs)，其中包含大量文档。

# 安装

要在基于 Linx 或 Mac 的系统上安装 Doltgres，请在终端中运行以下命令：

```
sudo bash -c 'curl -L https://github.com/dolthub/doltgresql/releases/latest/download/install.sh | bash'
```

这将下载最新的 doltgres 发行版并将其放入 `/usr/local/bin/`，该路径很可能已在你的 `$PATH` 中。

## Windows

在 [releases](https://github.com/dolthub/doltgresql/releases) 下载最新的 Microsoft Installer（`.msi` 文件）并运行。

## Docker

Doltgres 在每次发布时都会提供官方 Docker 镜像：

* [dolthub/doltgresql](https://hub.docker.com/r/dolthub/doltgresql)

在本地 Docker 中这样运行：

```bash
$ docker run -e DOLTGRES_PASSWORD=myPassword -p 5432:5432 dolthub/doltgresql:latest
```

## 从源码构建

要从源码生成二进制文件，请运行 `./scripts/build.sh`。

# 快速入门

1. 运行 `doltgres`。这将在当前目录中创建一个 `postgres` 用户和一个 `postgres` 数据库。默认密码为 `password`，与 Postgres 中一样。你可以使用 `config.yaml` 文件或设置 `DOLTGRES_DATA_DIR` 环境变量来为数据库使用不同的目录。

你可以在首次运行 `doltgres` 之前，通过设置 `DOLTGRES_USER` 和 `DOLTGRES_PASSWORD` 环境变量来更改超级用户的名称和密码。

```bash
$ doltgres
INFO[0000] Server ready. Accepting connections.
```

2. 安装 Postgres 以获取 `psql` 工具。我在 Mac 上使用 Homebrew 安装了 Postgres。  这需要我手动将 `/opt/homebrew/opt/postgresql@15/bin` 添加到 path。我们只需要 Postgres 来使用 `psql`，因此如果你已有 `psql`，或使用其他 Postgres 客户端，可以跳过此步骤。

```
export PATH="/opt/homebrew/opt/postgresql@15/bin:$PATH"
```

3. 打开新终端。使用以下命令连接：`PGPASSWORD=password psql -h localhost
-U postgres`. This will connect to the `postgres` database with the `postgres` 用户。

```bash
$ PGPASSWORD=password psql -h localhost
psql (15.4 (Homebrew), server 15.0)
Type "help" for help.

postgres=>
```

4. 创建一个 `getting_started` 数据库。创建 `getting_started` 示例表。

```sql
postgres=> create database getting_started;
--
(0 rows)

postgres=> \c getting_started;
psql (15.4 (Homebrew), server 15.0)
You are now connected to database "getting_started" as user "postgres".
getting_started=> create table employees (
    id int8,
    last_name text,
    first_name text,
    primary key(id));
--
(0 rows)

getting_started=> create table teams (
    id int8,
    team_name text,
    primary key(id));
--
(0 rows)

getting_started=> create table employees_teams(
    team_id int8,
    employee_id int8,
    primary key(team_id, employee_id),
    foreign key (team_id) references teams(id),
    foreign key (employee_id) references employees(id));
--
(0 rows)

getting_started=> \d
              List of relations
 Schema |      Name       | Type  |  Owner
--------+-----------------+-------+----------
 public | employees       | table | postgres
 public | employees_teams | table | postgres
 public | teams           | table | postgres
(3 rows)
```

5. 创建 Dolt Commit。

```sql
getting_started=> select * from dolt.status;
   table_name           | staged |  status
------------------------+--------+-----------
 public.employees       | f      | new table
 public.employees_teams | f      | new table
 public.teams           | f      | new table
(3 rows)

getting_started=> select dolt_add('teams', 'employees', 'employees_teams');
 dolt_add
----------
 {0}
(1 row)
getting_started=> select * from dolt.status;
   table_name          | staged |  status
-----------------------+--------+-----------
public.employees       | t      | new table
public.employees_teams | t      | new table
public.teams           | t      | new table
(3 rows)

getting_started=> select dolt_commit('-m', 'Created initial schema');
            dolt_commit
------------------------------------
 {peqq98e2dl5gscvfvic71e7j6ne34533}
(1 row)
```

6. 查看 Dolt 日志。

```sql
getting_started=> select * from dolt.log;
           commit_hash            | committer |       email        |        date         |          message
----------------------------------+-----------+--------------------+---------------------+----------------------------
 peqq98e2dl5gscvfvic71e7j6ne34533 | postgres  | postgres@127.0.0.1 | 2023-11-01 22:08:04 | Created initial schema
 in7bk735qa6p6rv6i3s797jjem2pg4ru | timsehn   | tim@dolthub.com    | 2023-11-01 22:04:03 | Initialize data repository
(2 rows)
```

7. 继续阅读 [Dolt 快速入门](https://dolthub.com/docs/introduction/getting-started/database#insert-some-data)
   以体验更多 Doltgres 版本控制功能。

# 与 Dolt 的限制和差异

- 没有像 [Dolt](https://github.com/dolthub/dolt), 中那样的 [Git 风格 CLI](https://dolthub.com/docs/cli-reference/cli) 来做版本控制，仅有 SQL 接口。
- 无法推送到 DoltHub 或 DoltLab，仅支持自定义 remote（例如文件系统或 S3）。
- 备份和复制功能仍在开发中。
- 不支持 GSSAPI。
- 尚不支持扩展。
- 部分 Postgres 语法、类型、函数和功能尚未实现。如果你遇到应用所需但缺失的功能，请 [提交 issue 告知我们](https://github.com/dolthub/doltgresql/issues).

# 性能

根据标准 Sysbench 测试套件衡量，Dolt 比 MySQL [慢 1.1 倍](https://dolthub.com/docs/sql-reference/benchmarks/latency)。

我们使用相同的 Sysbench 测试对 DoltgreSQL 进行基准测试，并将结果与 PostgreSQL 进行比较。

以下是 DoltgreSQL 版本 `0.50.0` 的基准测试结果。所有数值均为以毫秒为单位的中位延迟。

<!-- START_LATENCY_RESULTS_TABLE -->

| 读取测试                     | Postgres | Doltgres | 倍数     |
| ---                          | ---      | ---      | ---      |
| covering_index_scan_postgres | 1.89     | 5.28     | 2.8      |
| groupby_scan_postgres        | 5.28     | 46.63    | 8.8      |
| index_join_postgres          | 1.96     | 10.09    | 5.1      |
| index_join_scan_postgres     | 0.67     | 8.9      | 13.3     |
| index_scan_postgres          | 17.95    | 130.13   | 7.2      |
| oltp_point_select            | 0.14     | 0.52     | 3.7      |
| oltp_read_only               | 2.48     | 12.75    | 5.1      |
| select_random_points         | 0.21     | 1.12     | 5.3      |
| select_random_ranges         | 0.41     | 1.39     | 3.4      |
| table_scan_postgres          | 17.95    | 132.49   | 7.4      |
| types_table_scan_postgres    | 43.39    | 292.6    | 6.7      |
| reads_mean_multiplier        |          |          | 6.3      |

| 写入测试                  | Postgres | Doltgres | 倍数 |
|------------------------------|----------|----------|----------|
| oltp_delete_insert_postgres  | 2.22     | 6.79     | 3.1      |
| oltp_insert                  | 1.1      | 3.68     | 3.3      |
| oltp_read_write              | 4.25     | 20.37    | 4.8      |
| oltp_update_index            | 1.12     | 3.55     | 3.2      |
| oltp_update_non_index        | 1.12     | 3.43     | 3.1      |
| oltp_write_only              | 1.73     | 7.43     | 4.3      |
| types_delete_insert_postgres | 2.3      | 7.04     | 3.1      |
| write_mean_multiplier        |          |          | 3.6      |

| 总体平均倍数 | 5.2 |
| --------------------- | --- |

<!-- END_LATENCY_RESULTS_TABLE -->
<br/>

# 正确性

Dolt 基于称为 `sqllogictest` 的标准正确性测试套件，[与 MySQL 100% 兼容](https://dolthub.com/docs/sql-reference/benchmarks/correctness)。

我们使用相同的测试来衡量 DoltgreSQL 的正确性。

以下是 DoltgreSQL 版本 `0.50.0` 的 sqllogictest 结果。未运行的测试是因为本次运行中更早阶段发生超时而无法完成。

<!-- START_CORRECTNESS_RESULTS_TABLE -->

| 结果     | 数量   |
| --          | --      |
| 未运行 | 91270   |
| 失败      | 411415  |
| 通过          | 5188604 |
| 超时     | 16      |
| 测试总数 | 5691305 |

| 正确率 | 91.16721 |
| --                     | --       |

<!-- END_CORRECTNESS_RESULTS_TABLE -->
<br/>

# 架构

Doltgres 模拟 Postgres 服务器，包括将 Postgres SQL 解析为抽象语法树（Abstract Syntax Tree，AST）。该 AST 会被转换为 Dolt 引擎可解释的形式。Doltgres 使用与 Dolt 相同的 SQL 引擎和存储格式。

[Dolt 具有独特的架构](https://dolthub.com/docs/architecture/architecture)，可在 OLTP 数据库性能级别支持版本控制功能。Doltgres 使用相同的架构。