{"id":13425045,"url":"https://github.com/go-spatial/tegola-postgis","last_synced_at":"2025-03-15T19:32:35.399Z","repository":{"id":88495545,"uuid":"231684018","full_name":"go-spatial/tegola-postgis","owner":"go-spatial","description":"A version of of tegola that that leverages PostGIS ST_AsMVT","archived":true,"fork":false,"pushed_at":"2020-08-26T22:58:44.000Z","size":24140,"stargazers_count":6,"open_issues_count":4,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-28T03:39:10.103Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/go-spatial.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-03T23:55:04.000Z","updated_at":"2023-01-28T13:06:37.000Z","dependencies_parsed_at":"2023-08-28T17:32:25.454Z","dependency_job_id":null,"html_url":"https://github.com/go-spatial/tegola-postgis","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-spatial%2Ftegola-postgis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-spatial%2Ftegola-postgis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-spatial%2Ftegola-postgis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-spatial%2Ftegola-postgis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-spatial","download_url":"https://codeload.github.com/go-spatial/tegola-postgis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243781819,"owners_count":20347152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T00:01:03.176Z","updated_at":"2025-03-15T19:32:33.663Z","avatar_url":"https://github.com/go-spatial.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"#tegola-postgis\n\nTHIS IS NOW PART OF MAIN LINE OF TEGOLA. V0.12.x branch has this support. Please, use that instead of this one.\n\n\n\n\n## This is an experiment to see how to integrate ST_AsMVT into Tegola. \n\nThe main feature of this fork is the addition of mvt data providers. These data providers cannot be\nconflated.\n\n[![Build Status](https://travis-ci.org/go-spatial/tegola.svg?branch=master)](https://travis-ci.org/go-spatial/tegola)\n[![Report Card](https://goreportcard.com/badge/github.com/go-spatial/tegola)](https://goreportcard.com/badge/github.com/go-spatial/tegola)\n[![Coverage Status](https://coveralls.io/repos/github/go-spatial/tegola/badge.svg?branch=master)](https://coveralls.io/github/go-spatial/tegola?branch=master)\n[![Godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/go-spatial/tegola)\n[![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://github.com/go-spatial/tegola/blob/master/LICENSE.md)\n\ntegola-postgis is a vector tile server delivering [Mapbox Vector Tiles](https://github.com/mapbox/vector-tile-spec) with support for [PostGIS](https://postgis.net/) and [GeoPackage](https://www.geopackage.org/) data providers. User documentation can be found at [tegola.io](https://tegola.io)\n\n## Features\n- Native geometry processing (simplification, clipping, make valid, intersection, contains, scaling, translation)\n- [Mapbox Vector Tile v2 specification](https://github.com/mapbox/vector-tile-spec) compliant.\n- Embedded viewer with auto generated style for quick data visualization and inspection.\n- Support for PostGIS and GeoPackage data providers. Extensible design to support additional data providers.\n- Support for several cache backends: [file](cache/file), [s3](cache/s3), [redis](cache/redis), [azure blob store](cache/azblob).\n- Cache seeding and invalidation via individual tiles (ZXY), lat / lon bounds and ZXY tile list.\n- Parallelized tile serving and geometry processing.\n- Support for Web Mercator (3857) and WGS84 (4326) projections.\n- Support for [AWS Lambda](cmd/tegola_lambda).\n- Support for Data Providers that can generate MVT directly. Currenly postgis's `ST_AsMVT`. This is an experimental feature in `tegola-postgis` that may be backported to `tegola`. Additional details can be found [here](mvtprovider/postgis).\n\n## Usage\n```\ntegola is a vector tile server\nVersion: v0.10.2\n\nUsage:\n  tegola [command]\n\nAvailable Commands:\n  cache       Manipulate the tile cache\n  help        Help about any command\n  serve       Use tegola as a tile server\n  version     Print the version number of tegola\n\nFlags:\n      --config string   path to config file (default \"config.toml\")\n  -h, --help            help for tegola\n\nUse \"tegola [command] --help\" for more information about a command.\n```\n\n## Running tegola as a vector tile server\n1. Download the appropriate binary of tegola for your platform via the [release page](https://github.com/go-spatial/tegola/releases).\n2. Setup your config file and run. Dy default tegola looks for a `config.toml` in the same directory as the binary. You can set a different location for the `config.toml` using a command flag:\n\n```\n./tegola serve --config=/path/to/config.toml\n```\n\n## Server Endpoints\n\n```\n/\n```\n\nThe server root will display a built in viewer with an auto generated style. For example:\n\n![tegola built in viewer](https://raw.githubusercontent.com/go-spatial/tegola/v0.4.0/docs/screenshots/built-in-viewer.png \"tegola built in viewer\")\n\n\n```\n/maps/:map_name/:z/:x/:y\n```\n\nReturn vector tiles for a map. The URI supports the following variables:\n\n- `:map_name` is the name of the map as defined in the `config.toml` file.\n- `:z` is the zoom level of the map.\n- `:x` is the row of the tile at the zoom level.\n- `:y` is the column of the tile at the zoom level.\n\n\n```\n/maps/:map_name/:layer_name/:z/:x/:y\n```\n\nReturn vector tiles for a map layer. The URI supports the same variables as the map URI with the additional variable:\n\n- `:layer_name` is the name of the map layer as defined in the `config.toml` file.\n\n\n```\n/capabilities\n```\n\nReturn a JSON encoded list of the server's configured maps and layers with various attributes.\n\n```\n/capabilities/:map_name\n```\n\nReturn [TileJSON](https://github.com/mapbox/tilejson-spec) details about the map.\n\n```\n/maps/:map_name/style.json\n```\n\nReturn an auto generated [Mapbox GL Style](https://www.mapbox.com/mapbox-gl-js/style-spec/) for the configured map.\n\n## Configuration\nThe tegola config file uses the [TOML](https://github.com/toml-lang/toml) format. The following example shows how to configure a PostGIS data provider with two layers. The first layer includes a `tablename`, `geometry_field` and an `id_field`. The second layer uses a custom `sql` statement instead of the `tablename` property.\n\nUnder the `maps` section, map layers are associated with data provider layers and their `min_zoom` and `max_zoom` values are defined. Optionally, `default_tags` can be setup which will be encoded into the layer. If the same tags are returned from a data provider, the data provider's values will take precedence.\n\n```toml\n[webserver]\nport = \":9090\"              # port to bind the web server to. defaults \":8080\"\nssl_cert = \"fullchain.pem\"  # ssl cert for serving by https\nssl_key = \"privkey.pem\"     # ssl key for serving by https\n\n\t[webserver.headers]\n\tAccess-Control-Allow-Origin = \"*\"\n\tCache-Control = \"no-cache, no-store, must-revalidate\"\n\n[cache]                     # configure a tile cache\ntype = \"file\"               # a file cache will cache to the local file system\nbasepath = \"/tmp/tegola\"    # where to write the file cache\n\n# register mvt data providers\n# note mvt data providers can not be conflated\n[[mvt_providers]]\nname = \"test_postgis\"       # provider name is referenced from map layers (required)\ntype = \"postgis\"            # the type of data provider must be \"postgis\" for this data provider (required)\nhost = \"localhost\"          # PostGIS database host (required)\nport = 5432                 # PostGIS database port (required)\ndatabase = \"tegola\"         # PostGIS database name (required)\nuser = \"tegola\"             # PostGIS database user (required)\npassword = \"\"               # PostGIS database password (required\n\n[[mvt_providers.layers]]\nname = \"landuse\"\n# MVT data provider must use SQL statements\n# this table uses \"geom\" for the geometry_fieldname and \"gid\" for the id_fieldname so they don't need to be configured\nsql = \"SELECT ST_AsMVTGeom(geom,!BBOX!) AS geom, gid FROM gis.landuse WHERE geom \u0026\u0026 !BBOX!\"\n\n# register data providers\n[[providers]]\nname = \"test_postgis\"       # provider name is referenced from map layers (required)\ntype = \"postgis\"            # the type of data provider. currently only supports postgis (required)\nhost = \"localhost\"          # postgis database host (required)\nport = 5432                 # postgis database port (required)\ndatabase = \"tegola\"         # postgis database name (required)\nuser = \"tegola\"             # postgis database user (required)\npassword = \"\"               # postgis database password (required)\nsrid = 3857                 # The default srid for this provider. Defaults to WebMercator (3857) (optional)\nmax_connections = 50        # The max connections to maintain in the connection pool. Default is 100. (optional)\nssl_mode = \"prefer\"        # PostgreSQL SSL mode*. Default is \"disable\". (optional)\n\n\t[[providers.layers]]\n\tname = \"landuse\"                    # will be encoded as the layer name in the tile\n\ttablename = \"gis.zoning_base_3857\"  # sql or tablename are required\n\tgeometry_fieldname = \"geom\"         # geom field. default is geom\n\tid_fieldname = \"gid\"                # geom id field. default is gid\n\tsrid = 4326                         # the srid of table's geo data. Defaults to WebMercator (3857)\n\n\t[[providers.layers]]\n\tname = \"roads\"                      # will be encoded as the layer name in the tile\n\ttablename = \"gis.zoning_base_3857\"  # sql or tablename are required\n\tgeometry_fieldname = \"geom\"         # geom field. default is geom\n\tgeometry_type = \"linestring\"        # geometry type. if not set, tables are inspected at startup to try and infer the gemetry type\n\tid_fieldname = \"gid\"                # geom id field. default is gid\n\tfields = [ \"class\", \"name\" ]        # Additional fields to include in the select statement.\n\n\t[[providers.layers]]\n\tname = \"rivers\"                     # will be encoded as the layer name in the tile\n\tgeometry_fieldname = \"geom\"         # geom field. default is geom\n\tid_fieldname = \"gid\"                # geom id field. default is gid\n\t# Custom sql to be used for this layer. Note: that the geometery field is wraped\n\t# in a ST_AsBinary() and the use of the !BBOX! token\n\tsql = \"SELECT gid, ST_AsBinary(geom) AS geom FROM gis.rivers WHERE geom \u0026\u0026 !BBOX!\"\n\n\t[[providers.layers]]\n\tname = \"buildings\"                  # will be encoded as the layer name in the tile\n\tgeometry_fieldname = \"geom\"         # geom field. default is geom\n\tid_fieldname = \"gid\"                # geom id field. default is gid\n\t# Custom sql to be used for this layer as a sub query. ST_AsBinary and\n\t# !BBOX! filter are applied automatically.\n\tsql = \"(SELECT gid, geom, type FROM buildings WHERE scalerank = !ZOOM! LIMIT 1000) AS sub\"\n\n# maps are made up of layers\n[[maps]]\nname = \"zoning\"                              # used in the URL to reference this map (/maps/:map_name)\n\n\t[[maps.layers]]\n\tname = \"landuse\"                         # name is optional. If it's not defined the name of the ProviderLayer will be used.\n\t                                         # It can also be used to group multiple ProviderLayers under the same namespace.\n\tprovider_layer = \"test_postgis.landuse\"  # must match a data provider layer\n\tmin_zoom = 12                            # minimum zoom level to include this layer\n\tmax_zoom = 16                            # maximum zoom level to include this layer\n\n\t\t[maps.layers.default_tags]           # table of default tags to encode in the tile. SQL statements will override\n\t\tclass = \"park\"\n\n\t[[maps.layers]]\n\tname = \"rivers\"                          # name is optional. If it's not defined the name of the ProviderLayer will be used.\n\t                                         # It can also be used to group multiple ProviderLayers under the same namespace.\n\tprovider_layer = \"test_postgis.rivers\"   # must match a data provider layer\n\tdont_simplify = true                     # optionally, turn off simplification for this layer. Default is false.\n\tdont_clip = true                         # optionally, turn off clipping for this layer. Default is false.\n\tmin_zoom = 10                            # minimum zoom level to include this layer\n\tmax_zoom = 18                            # maximum zoom level to include this layer\n\n[[maps]]\nname = \"landuse_mvt\"\n\n\t [[maps.layers]]\n\t name = \"landuse\"\n\t provider_layer = \"mvt_test_postgis.landuse\" # note the mvt data provider name is prefixed with `mvt_`\n\t min_zoom = 12                            # minimum zoom level to include this layer\n\t max_zoom = 16                            # maximum zoom level to include this layer\n\n\n```\n\n\\* more on PostgreSQL SSL mode [here](https://www.postgresql.org/docs/9.2/static/libpq-ssl.html). The `postgis` config also supports \"ssl_cert\" and \"ssl_key\" options are required, corresponding semantically with \"PGSSLKEY\" and \"PGSSLCERT\". These options do not check for environment variables automatically. See the section [below](#environment-variables) on injecting environment variables into the config.\n\n## Environment Variables\n\n#### Config TOML\nEnvironment variables can be injected into the configuration file. One caveat is that the injection has to be within a string, though the value it represents does not have to be a string.\n\nThe above config example could be written as:\n```toml\n# register data providers\n[[providers]]\nname = \"test_postgis\"\ntype = \"postgis\"\nhost = \"${POSTGIS_HOST}\"    # postgis database host (required)\nport = \"${POSTGIS_PORT}\"    # recall this value must be an int\ndatabase = \"${POSTGIS_DB}\"\nuser = \"tegola\"\npassword = \"\"\nsrid = 3857\nmax_connections = \"${POSTGIS_MAX_CONN}\"\n```\n\n#### SQL Debugging\nThe following environment variables can be used for debugging:\n\n`TEGOLA_SQL_DEBUG` specify the type of SQL debug information to output. Currently support two values:\n\n- `LAYER_SQL`: print layer SQL as they are parsed from the config file.\n- `EXECUTE_SQL`: print SQL that is executed for each tile request and the number of items it returns or an error.\n\n#### Usage\n\n```bash\n$ TEGOLA_SQL_DEBUG=LAYER_SQL tegola serve --config=/path/to/conf.toml\n```\n\nThe following environment variables can be used to control various runtime options:\n\n`TEGOLA_OPTIONS` specify a set of options comma or space delimited. Supports the following options\n\n- `DontSimplifyGeo` to turn off simplification for all layers.\n- `SimplifyMaxZoom={{int}}` to set the max zoom that simplification will apply to. (14 is default)\n\n\n## Client side debugging\n\nWhen debugging client side, it's often helpful to to see an outline of a tile along with it's Z/X/Y values. To encode a debug layer into every tile add the query string variable `debug=true` to the URL template being used to request tiles. For example:\n\n```\nhttp://localhost:8080/maps/mymap/{z}/{x}/{y}.vector.pbf?debug=true\n```\n\nThe requested tile will be encode a layer with the `name` value set to `debug` and include two features:\n\n - `debug_outline`: a line feature that traces the border of the tile\n - `debug_text`: a point feature in the middle of the tile with the following tags:\n   - `zxy`: a string with the `Z`, `X` and `Y` values formatted as: `Z:0, X:0, Y:0`\n\n## Building from source\n\nTegola is written in [Go](https://golang.org/) and requires Go 1.x to compile from source. (We support the three newest versions of Go.) To build tegola from source, make sure you have Go installed and have cloned the repository to your `$GOPATH`. Navigate to the repository then run the following commands:\n\n\n```bash\ncd cmd/tegola/\ngo build\n```\n\nYou will now have a binary named `tegola` in the current directory which is [ready for running](#running-tegola).\n\n**Build Flags**\nThe following build flags can be used to turn off certain features of tegola:\n\n- `noAzblobCache` - turn off the Azure Blob cache back end.\n- `noS3Cache` - turn off the AWS S3 cache back end.\n- `noRedisCache` - turn off the Redis cache back end.\n- `noPostgisProvider` - turn off the PostGIS data provider.\n- `noGpkgProvider` - turn off the GeoPackage data provider. Note, GeoPackage uses CGO and will be turned off if the environment variable `CGO_ENABLED=0` is set prior to building.\n- `noViewer` - turn off the built in viewer.\n- `pprof` - enable [Go profiler](https://golang.org/pkg/net/http/pprof/). Start profile server by setting the environment `TEGOLA_HTTP_PPROF_BIND` environment (e.g. `TEGOLA_HTTP_PPROF_BIND=localhost:6060`).\n\nExample of using the build flags to turn of the Redis cache back end, the GeoPackage provider and the built in viewer.\n\n```bash\ngo build -tags 'noRedisCache noGpkgProvider noViewer'\n```\n\n\n**Turning off CGO**\nTegola uses CGO for certain functionality (i.e. GeoPackge support). To build tegola without CGO use the following command:\n\n```bash\nCGO_ENABLED=0 go build\n```\n\n\n## License\nSee [license](LICENSE.md) file in repo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-spatial%2Ftegola-postgis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-spatial%2Ftegola-postgis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-spatial%2Ftegola-postgis/lists"}