Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/graphile/postgis
PostGIS support for PostGraphile
https://github.com/graphile/postgis
Last synced: 4 days ago
JSON representation
PostGIS support for PostGraphile
- Host: GitHub
- URL: https://github.com/graphile/postgis
- Owner: graphile
- Created: 2018-02-18T14:34:11.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-07-01T11:22:54.000Z (4 months ago)
- Last Synced: 2024-07-18T20:02:02.646Z (4 months ago)
- Language: TypeScript
- Homepage:
- Size: 667 KB
- Stars: 90
- Watchers: 10
- Forks: 9
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-starred - graphile/postgis - PostGIS support for PostGraphile (others)
README
# @graphile/postgis
This is a [PostGraphile schema
plugin](https://www.graphile.org/postgraphile/extending/) that provides
support for the popular [PostGIS](http://postgis.net/) spatial database
system.
Create a [PostgreSQL](https://www.postgresql.org/) database with PostGIS
columns, run [PostGraphile](https://www.graphile.org/postgraphile/) with this
plugin, and have a fully functional geospatial-aware
[GraphQL](http://graphql.org/) API for your database.
## Roadmap
Work is ongoing, here's the plan:
- [x] Read-only support for `geojson` field from all geography types (via a shared GraphQL interface)
- [x] Add GraphQL types for all the expected geography types (implementing this interface)
- [x] Read-only support for determining the geometry sub-types of columns and exposing these directly (rather than the interface)
- [x] Read-only support for `longitude` and `latitude` on `geography(POINT)` columns
- [x] Read-only support for viewing the list of `geometries` in a `geography(GEOMETRYCOLLECTION)`
- [x] Read-only support for a list of points (`longitude` and `latitude`) on
`geography(LINESTRING)` and `geography(POLYGON)` columns
- [x] Create/update/null support for `geography(POINT)` columns
- [x] Create/update/null support for `geography(LINESTRING)` and `geography(POLYGON)` columns
- [x] Integration with `postgraphile-plugin-connection-filter` to enable PostGIS specific filtering (via [postgraphile-plugin-connection-filter-postgis](https://github.com/mattbretl/postgraphile-plugin-connection-filter-postgis/))
- [ ] Read-only support for computed attributes on
`geography(LINESTRING)` and `geography(POLYGON)`, such as `area`,
`length`, `perimeter`, and `centroid` - currently possible by adding a plugin and consuming the GeoJSON directly.
There are many, many other features that this plugin could support - if you
have specific needs please get in touch!
## Usage
This plugin requires PostGraphile **v4.4.0** or higher to function correctly.
Add PostGIS to your database:
```sql
CREATE EXTENSION IF NOT EXISTS postgis WITH SCHEMA public;
```
Load the plugin:
```
postgraphile --append-plugins @graphile/postgis
```
#### Querying and mutating
Using this table as example:
```sql
CREATE TABLE data (
id UUID PRIMARY KEY DEFAULT uuid_generate_v1mc(),
geom_point geometry(Point, 4326) default null
);
```
In **queries** `geom_point` is represented as type `GeometryPoint`. Example:
```graphql
query {
allDatas {
nodes {
geomPoint {
geojson
srid
x
y
}
}
}
}
```
In **mutations** `geom_point` is represented as type `GeoJSON`. Example:
```graphql
mutation ($id: UUID!, $geomPoint: GeoJSON!) {
updateDataById(
input: {
id: $id,
dataPatch: {
geomPoint: $geomPoint
}
}
) { ... }
}
```
with these variables:
```json
{
"id": "0116254a-0146-11ea-8418-4f89d6596247",
"geomPoint": {
"type": "Point",
"coordinates": [8.5, 47.5]
}
}
```
Beware of the fact that since 2016 the `GeoJSON` spec expects the coordinates to be of SRID 4326/WGS84 (see https://tools.ietf.org/html/rfc7946#section-4). So adding a `crs` field to the GeoJSON is deprecated. Thus since v3 PostGIS will be happy to receive above GeoJSON.
**In earlier versions PostGIS expects a SRID to be passed**. So the variables would be:
```json
{
"id": "0116254a-0146-11ea-8418-4f89d6596247",
"geomPoint": {
"type": "Point",
"coordinates": [8.5, 47.5],
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
}
}
}
```
## Development
Contributions are extremely welcome! To get started, clone down this repo and then:
```
createdb graphile_test
export TEST_DATABASE_URL=postgres://localhost:5432/graphile_test
yarn
yarn dev
```
Note the development server runs at http://localhost:5123/graphiql
To run the tests:
```
yarn test
```