@graphile/postgis

中文文档
0.2.0发布于 2023/04/19MITTypeScriptCommonJS近 30 天下载 1.6万

PostGIS support for PostGraphile

原始使用文档
文档目录3 节
  1. Roadmap
  2. Usage
  3. Development

@graphile/postgis

This is a PostGraphile schema plugin that provides support for the popular PostGIS spatial database system.

Create a PostgreSQL database with PostGIS columns, run PostGraphile with this plugin, and have a fully functional geospatial-aware GraphQL API for your database.

Roadmap

Work is ongoing, here's the plan:

  • Read-only support for geojson field from all geography types (via a shared GraphQL interface)
  • Add GraphQL types for all the expected geography types (implementing this interface)
  • Read-only support for determining the geometry sub-types of columns and exposing these directly (rather than the interface)
  • Read-only support for longitude and latitude on geography(POINT) columns
  • Read-only support for viewing the list of geometries in a geography(GEOMETRYCOLLECTION)
  • Read-only support for a list of points (longitude and latitude) on geography(LINESTRING) and geography(POLYGON) columns
  • Create/update/null support for geography(POINT) columns
  • Create/update/null support for geography(LINESTRING) and geography(POLYGON) columns
  • Integration with postgraphile-plugin-connection-filter to enable PostGIS specific filtering (via 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:

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:

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:

query {
  allDatas {
    nodes {
      geomPoint {
        geojson
        srid
        x
        y
      }
    }
  }
}

In mutations geom_point is represented as type GeoJSON. Example:

mutation ($id: UUID!, $geomPoint: GeoJSON!) {
  updateDataById(
    input: {
      id: $id,
      dataPatch: {
        geomPoint: $geomPoint
      }
    }
  ) { ... }
}

with these variables:

{
  "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:

{
  "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

版本与发布记录

@graphile/postgis 共发布 9 个版本,首次发布于 2019/03/08;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.2.0latest2023/04/193 年前
0.2.0-02022/09/054 年前
0.1.02019/04/047 年前
0.0.62019/03/227 年前
0.0.52019/03/137 年前
0.0.42019/03/137 年前

关于 @graphile/postgis 的常见问题

@graphile/postgis 是什么?

PostGIS support for PostGraphile

如何安装 @graphile/postgis?

在项目目录运行 npm install @graphile/postgis,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:graphile-build(^4.4.0)、graphile-build-pg(^4.4.0)、graphql(>=0.6 <16)、pg-sql2(>=2.2.1 <5)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@graphile/postgis 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@graphile/postgis 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@graphile/postgis 可以商用吗?

@graphile/postgis 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@graphile/postgis 的下载量有多少?

根据 npm 官方下载统计,@graphile/postgis 在 2026/10/17 – 2026/11/15 这 30 天内被下载 15,649 次,日均约 522 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@graphile/postgis 还在维护吗?

最新版本 0.2.0 发布于 2023/04/19(3 年前);至今共发布 9 个版本,其中过去 12 个月发布了 0 个;首次发布于 2019/03/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。