wehub/dolthub--doltgresql
1
0
Fork 0
Code Issues Pull Requests Actions 1 Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
dolthub--doltgresql/README.en.md
T
wehub-resource-sync 81e416a3ce docs: preserve upstream English README
2026-07-13 10:21:18 +00:00

284 lines
10 KiB
Markdown
Raw Permalink Blame History

# Doltgres is Dolt for Postgres!
From the creators of [Dolt](https://www.doltdb.com), the world's first version controlled SQL
database, comes [Doltgres](https://www.doltgres.com), the Postgres-flavored version of Dolt. It's a
SQL database that you can branch and merge, fork and clone, push and pull just like a Git
repository. Connect to your Doltgres server just like any Postgres database to read or modify schema
and data. Version control functionality is exposed in SQL via system tables, functions, and
procedures.
Git versions file, Doltgres versions tables. It's like Git and Postgres had a baby.
# Doltgres is Beta
[Doltgres is now Beta quality](https://dolthub.com/blog/2025-04-16-doltgres-goes-beta/), which means
it's ready for your production use case. There will be bugs and missing features, but [we can fix
most of them in 24 hours](https://www.dolthub.com/blog/2024-05-15-24-hour-bug-fixes/) if you [file
an issue](https://github.com/dolthub/doltgresql/issues).
The wait is over! Now is the time to [try out Doltgres](#getting-started) and let us know what you
think. Import your existing Postgres database into Doltgres with `pg_dump` and `psql`, and let us
know if anything doesn't work.
If you're excited about this project, you can also help speed it along in a few other ways:
- Star this repo
- Create [issues](https://github.com/dolthub/doltgresql/issues) if you find bugs
- Create [issues](https://github.com/dolthub/doltgresql/issues) for missing functionality you want
- Contribute code for features you want (see the [Contribution
Guide](https://github.com/dolthub/doltgresql/blob/main/CONTRIBUTING.md))
- Tell your friends and colleagues
# Full Documentation
Doltgres has a [documentation website](https://doltgres.com/docs) with extensive documentation.
# Installation
To install Doltgres on Linx or Mac based systems run this command in your terminal:
```
sudo bash -c 'curl -L https://github.com/dolthub/doltgresql/releases/latest/download/install.sh | bash'
```
This will download the latest doltgres release and put it in `/usr/local/bin/`, which is probably on
your `$PATH`.
## Windows
Download the latest Microsoft Installer (`.msi` file) in
[releases](https://github.com/dolthub/doltgresql/releases) and run it.
## Docker
Doltgres publishes an official Docker image on every release:
* [dolthub/doltgresql](https://hub.docker.com/r/dolthub/doltgresql)
Run it on your local Docker like this:
```bash
$ docker run -e DOLTGRES_PASSWORD=myPassword -p 5432:5432 dolthub/doltgresql:latest
```
## Building From Source
To produce a binary from source code, run `./scripts/build.sh`.
# Getting Started
1. Run `doltgres`. This will create a `postgres` user and a `postgres` database in the current
directory. The default password will be `password`, just like in Postgres. You can use a
`config.yaml` file or set the `DOLTGRES_DATA_DIR` environment variable to use a different directory
for your databases.
You can change the name and password of the super-user by setting the `DOLTGRES_USER` and
`DOLTGRES_PASSWORD` environment variables before running `doltgres` for the first time.
```bash
$ doltgres
INFO[0000] Server ready. Accepting connections.
```
2. Install Postgres to get the `psql` tool. I used Homebrew to install Postgres on my Mac. This
requires I manually add `/opt/homebrew/opt/postgresql@15/bin` to my path. We only need Postgres in
order to use `psql`, so feel free to skip this step if you already have `psql`, or if you have
another Postgres client you use instead.
```
export PATH="/opt/homebrew/opt/postgresql@15/bin:$PATH"
```
3. Open a new terminal. Connect with the following command: `PGPASSWORD=password psql -h localhost
-U postgres`. This will connect to the `postgres` database with the `postgres` user.
```bash
$ PGPASSWORD=password psql -h localhost
psql (15.4 (Homebrew), server 15.0)
Type "help" for help.
postgres=>
```
4. Create a `getting_started` database. Create the `getting_started` example tables.
```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. Make a 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. View the Dolt log.
```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. Continue with [Dolt Getting Started](https://dolthub.com/docs/introduction/getting-started/database#insert-some-data)
to test out more Doltgres versioning functionality.
# Limitations and differences from Dolt
- No [Git-style CLI](https://dolthub.com/docs/cli-reference/cli) for version control like in
[Dolt](https://github.com/dolthub/dolt), only a SQL interface.
- Can't push to DoltHub or DoltLab, only custom remotes (such as on the file system or to S3).
- Backup and replication are a work in progress.
- No GSSAPI support.
- No extension support yet.
- Some Postgres syntax, types, functions, and features are not yet implemented. If you encounter a
missing feature you need for your application, please [file an issue to let us
know](https://github.com/dolthub/doltgresql/issues).
# Performance
Dolt is [1.1X slower than MySQL](https://dolthub.com/docs/sql-reference/benchmarks/latency) as
measured by a standard suite of Sysbench tests.
We use these same Sysbench tests to benchmark DoltgreSQL and compare the results to PostgreSQL.
Here are the benchmarks for DoltgreSQL version `0.50.0`. All figures are median latency in
milliseconds.
<!-- START_LATENCY_RESULTS_TABLE -->
| Read Tests | Postgres | Doltgres | Multiple |
| --- | --- | --- | --- |
| 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 |
| Write Tests | Postgres | Doltgres | Multiple |
|------------------------------|----------|----------|----------|
| 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 |
| Overall Mean Multiple | 5.2 |
| --------------------- | --- |
<!-- END_LATENCY_RESULTS_TABLE -->
<br/>
# Correctness
Dolt is [100% compatible](https://dolthub.com/docs/sql-reference/benchmarks/correctness) with MySQL
based on a standard suite of correctness tests called `sqllogictest`.
We use these same tests to measure the correctness of DoltgreSQL.
Here are DoltgreSQL's sqllogictest results for version `0.50.0`. Tests that did not run could not
complete due to a timeout earlier in the run.
<!-- START_CORRECTNESS_RESULTS_TABLE -->
| Results | Count |
| -- | -- |
| did not run | 91270 |
| not ok | 411415 |
| ok | 5188604 |
| timeout | 16 |
| Total Tests | 5691305 |
| Correctness Percentage | 91.16721 |
| -- | -- |
<!-- END_CORRECTNESS_RESULTS_TABLE -->
<br/>
# Architecture
Doltgres emulates a Postgres server, including parsing Postgres SQL into an Abstract Syntax Tree (AST). This AST is
converted to a form that can be interpreted by the Dolt engine. Doltgres uses the same SQL engine and storage format as Dolt.
[Dolt has a unique architecture](https://dolthub.com/docs/architecture/architecture) that allows for version control
features at OLTP database performance. Doltgres uses the same architecture.
Reference in New Issue View Git Blame Copy Permalink