wehub-resource-sync
129 lines
5.1 KiB
Markdown
129 lines
5.1 KiB
Markdown
# 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.
|
|
|
|
[Join us on Discord](https://discord.com/invite/RFwfYpu) to say hi and
|
|
ask questions, or [check out our roadmap](https://dolthub.com/docs/other/roadmap)
|
|
to see what we're building next.
|
|
|
|
## What's it for?
|
|
|
|
Lots of things! Doltgres is a generally useful tool with countless applications. But if you want
|
|
some ideas, [here's how people are using it so
|
|
far](https://www.dolthub.com/blog/2022-07-11-dolt-case-studies/).
|
|
|
|
# How to use this image
|
|
|
|
This image is for the Doltgres server and is similar to the Postgres Docker image. Running this
|
|
image without any arguments is equivalent to running the `doltgres` command inside a Docker
|
|
container.
|
|
|
|
To see all supported options for `doltgres`, you can run the image with `--help` flag.
|
|
|
|
```shell
|
|
$ docker run dolthub/doltgresql:latest --help
|
|
```
|
|
|
|
## Building the image
|
|
|
|
To build this image, use the `Dockerfile` in the root of the [Doltgres
|
|
repository](https://github.com/dolthub/doltgresql/) with an optional build argument:
|
|
|
|
```shell
|
|
# Build the latest Doltgres version (automatically fetches the latest release)
|
|
$ docker build -t doltgres:latest .
|
|
|
|
# Build the latest Doltgres version (fetches the latest release)
|
|
$ docker build --build-arg DOLTGRES_VERSION=latest -t doltgres:latest .
|
|
|
|
# Build with a specific Doltgres version
|
|
$ docker build --build-arg DOLTGRES_VERSION=0.55.1 -t doltgres:0.55.1 .
|
|
|
|
# Build from local source code
|
|
$ docker build --build-arg DOLTGRES_VERSION=source -t doltgres:source .
|
|
```
|
|
|
|
## Connect to the server in the container from the host system
|
|
|
|
To connect to a server running in a container from the host system, we need to map a port on the
|
|
host system to the port our server is running on in the container.
|
|
|
|
```bash
|
|
$ docker run -p 5432:5432 dolthub/doltgresql:latest
|
|
```
|
|
|
|
*Note*: if you have Postgres installed on this machine already, port `5432` will be in use. Either
|
|
choose a different port to map or shut down Postgres.
|
|
|
|
Now connect with `psql` or another Postgres-compatible client.
|
|
|
|
```bash
|
|
$ PGPASSWORD=password psql --host 127.0.0.1 -U postgres
|
|
```
|
|
|
|
## Define configuration for the server
|
|
|
|
You can specify server configuration by providing your own `config.yaml` for the server to use as a
|
|
mounted volume. The image looks for a `config.yaml` file in the mounted directory
|
|
`/etc/doltgres/servercfg.d`. Place your desired `config.yaml` directory in a local file, then
|
|
provide it to `docker run` with the `-v` argument like this:
|
|
|
|
```shell
|
|
$ docker run -v ./doltgres_cfg:/etc/doltgres/servercfg.d -p 5432:5432 dolthub/doltgresql:latest
|
|
```
|
|
|
|
The data directory in the container is `/var/lib/doltgresql/`. To change this, provide the `PGDATA`
|
|
or `DOLTGRES_DATA` environment variable to `docker run`. This directory can also be a mounted
|
|
directory on the local machine.
|
|
|
|
```shell
|
|
$ docker run -e PGDATA=/path/to/doltgres/data -p 5432:5432 dolthub/doltgresql:latest
|
|
```
|
|
|
|
## Specifying a username and password
|
|
|
|
By default, the server creates a super-user named `postgres` with the password `password`. To change
|
|
this, provide the `DOLTGRES_USER` and `DOLTGRES_PASSWORD` environment variables to the `docker run`
|
|
command.
|
|
|
|
```shell
|
|
$ docker run -e DOLTGRES_USER=myuser -e DOLTGRES_PASSWORD=mypass -p 5432:5432 dolthub/doltgresql:latest
|
|
```
|
|
|
|
For convenience, `POSTGRES_USER` and `POSTGRES_PASSWORD` are accepted as aliases for these variables.
|
|
|
|
To create additional users, connect to the running database and issue `CREATE ROLE` and `GRANT`
|
|
statements as the super-user.
|
|
|
|
## Initialization
|
|
|
|
By default, the Doltgres server is initialized with a single empty database with the same name as
|
|
the system user (`postgres` by default). You can add additional data or execute arbitrary SQL setup
|
|
by including initialization scripts in the mounted volume
|
|
`/docker-entrypoint-initdb.d/`. Initialization scripts must have the `.sql` file extension and
|
|
contain statements separated by semicolons. They can be optionally compressed as `.bz2`, `.gz`,
|
|
`.xz`, or `.zst` files with the appropriate extension suffix, e.g. `init.sql.gz`.
|
|
|
|
Specify an initialization script directory as a volume with `docker run`:
|
|
|
|
```shell
|
|
$ docker run -v ./init_scripts:/docker-entrypoint-initdb.d/ -p 5432:5432 dolthub/doltgresql:latest
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
The Doltgres image supports the following environment variables:
|
|
|
|
- `DOLTGRES_USER`: The name of the super-user (default: `postgres`). `POSTGRES_USER` is an alias.
|
|
- `DOLTGRES_PASSWORD`: The password for the super-user (default: `password`). `POSTGRES_PASSWORD` is
|
|
an alias.
|
|
- `DOLTGRES_DATA`: Specifies a path in the container to store database data, created if it doesn't
|
|
exist (default: `/var/lib/doltgresql/`). `PGDATA` is an alias.
|