Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 53 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Library for handling diffs for geospatial data. Works with GeoPackage files and

Geodiff library is used by [Mergin Maps](https://merginmaps.com/) - a platform for easy sharing of spatial data.

<div><img align="left" width="45" height="45" src="https://raw.githubusercontent.com/MerginMaps/docs/main/src/public/slack.svg"><a href="https://merginmaps.com/community/join">Join our community chat</a><br/>and ask questions!</div>
<a href="https://community.merginmaps.com">Join our community</a> and ask questions!

## Use cases for geodiff

Expand Down Expand Up @@ -49,6 +49,8 @@ The library nowadays comes with support for two drivers:

## Using command line interface

### GeoPackage

To get changes between two GeoPackage files and write them to `a-to-b.diff` (a binary diff file):
```bash
geodiff diff data-a.gpkg data-b.gpkg a-to-b.diff
Expand All @@ -70,6 +72,23 @@ geodiff invert a-to-b.diff b-to-a.diff
geodiff apply data-a.gpkg b-to-a.diff
```

### PostGIS

The same commands work with PostGIS databases. Instead of file paths, pass **schema names** and use `--driver postgres` with a [libpq connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING):
```bash
geodiff diff --driver postgres "host=localhost dbname=mydb user=myuser password=mypass" schema_a schema_b a-to-b.diff
```

```bash
geodiff diff --json --driver postgres "host=localhost dbname=mydb user=myuser password=mypass" schema_a schema_b
```

```bash
geodiff apply --driver postgres "host=localhost dbname=mydb user=myuser password=mypass" schema_a a-to-b.diff
```

Both schemas must be in the same database and have identical table structure. You can check which drivers are available with `geodiff drivers`.

The `geodiff` tool supports other various commands, use `geodiff help` for the full list.

## Using Python module
Expand All @@ -82,6 +101,8 @@ pip3 install pygeodiff
If you get error `ModuleNotFoundError: No module named 'skbuild'` try to update pip with command
`python -m pip install --upgrade pip`

### GeoPackage

Sample usage of the Python module:

```python
Expand All @@ -99,6 +120,37 @@ geodiff.apply_changeset('data-a.gpkg', 'a-to-b.diff')
geodiff.list_changes('a-to-b.diff', 'a-to-b.json')
```

### PostGIS

To perform the same actions against a PostGIS database, use the `_ex` methods with a driver name and connection string. The `base` and `modified` arguments are schema names:

```python
import pygeodiff

geodiff = pygeodiff.GeoDiff()
conninfo = "host=localhost dbname=mydb user=myuser password=mypass"

# create a diff between two PostGIS schemas
geodiff.create_changeset_ex(
driver="postgres",
driver_info=conninfo,
base="schema_a",
modified="schema_b",
changeset="a-to-b.diff"
)

# apply changes from a-to-b.diff to a PostGIS schema
geodiff.apply_changeset_ex(
driver="postgres",
driver_info=conninfo,
base="schema_a",
changeset="a-to-b.diff"
)

# export changes from the binary diff format to JSON
geodiff.list_changes('a-to-b.diff', 'a-to-b.json')
```

If there are any problems, calls will raise `pygeodiff.GeoDiffLibError` exception.

If you have Mergin plugin for QGIS installed, you can also use pygeodiff from QGIS' Python Console by starting with
Expand Down
Loading