Difficulty: beginner
Estimated Time: 10 minutes

Introduction to Vector Tiles and pg_tileserv

This scenario gives you a hands-on introduction to vector tiles and pg_tileserv.

Vector tiles are a bandwidth-efficient method of transferring spatial data over the web for display in web maps. For a brief history of web maps and vector tiles, watch Paul Ramsey's presentation at PostGIS Day 2019.

With the release of PostGIS 2.4, PostGIS introduced the ability to generate vector tiles directly from the database. This provided developers with the ability to have constantly up-to-date vector tiles in their web maps. However, it also required developers to write their own API to leverage this functionality. Pg_tileserv was created to make it easy to service enable your spatial data and integrate it into your web application.

To use pg_tileserv, you need to have a PostGIS database with spatial data loaded in it. The database has already been started and the spatial data has already been loaded. This scenario will use data from New York City (NYC).

This exercise demonstrates how to connect pg_tileserv to your database and shows the resulting vector tiles. We also provide an example of how pg_tileserv works with user-defined functions. If you would like to learn more about creating funcitons, please review our Basics on Writing Functions scenario. Data from this scenario is used in our other exercises as well, but the environments don't persist between scenarios.

Here are the details on the database we are connecting to:

  1. Username: groot
  2. Password: password (same password for the postgres user as well)
  3. A database named: nyc

And with that, let's dig in.

This scenario was meant to show you how easily and quickly you can add pg_tileserv to your exisitng PostGIS implementation to service enable your spatial data.

From here you can now add these vector tiles as layers to your web map. Common implementations use OpenLayers or Leaflet (a topic beyond the scope of this scenario).

You also saw in this scenario that you can also add functions to your database to do more complex geospatial analysis in the database and have them exposed as vector tiles. We encourage you to check out our PostGIS exercises for further information on the different types of analysis and functions you can create.

Don't forget to also check out the official pg_tileserv documentation.

pg_tileserv

Step 1 of 3

Vector Tiles and pg_tileserv

This exercise shows you the steps to add pg_tileserv to your PostGIS implementation.

First, take a look at the tab in the terminal to the right called "pg_tileserv". You'll see that it's still waiting for an available conneciton on port 7800, the port that pg_tileserv serves data on. That's because we haven't added pg_tileserv to our PostGIS implementation yet. Let's do that now.

Add pg_tileserv

To add pg_tileserv to your PostGIS database, you need to either download the source code, the binaries, or one of our supported containers. We'll use the container version of pg_tileserv for this scenario.

The code block below allows you to click on it to have the code execute in the terminal. Be sure to click in the Terminal tab before clicking the code block to make sure the code executes in the correct tab. You also have the option of copying and pasting the code, or typing it yourself in the Terminal tab.

docker run -p 7800:7800 --env=DATABASE_URL=postgres://groot:[email protected]/nyc pramsey/pg_tileserv:CI

You'll see that the connection info we provided in the intro (database name: nyc, username: groot, and password: password) is used in the statement above.

You should see lines of output like this in the terminal:

time="2020-07-02T14:06:45Z" level=info msg="pg_tileserv CI"
time="2020-07-02T14:06:45Z" level=info msg="Run with --help parameter for commandline options"
time="2020-07-02T14:06:45Z" level=info msg="Using database connection info from environment variable DATABASE_URL"
time="2020-07-02T14:06:45Z" level=info msg="Serving HTTP  at 0.0.0.0:7800"
time="2020-07-02T14:06:45Z" level=info msg="Serving HTTPS at 0.0.0.0:7801"
time="2020-07-02T14:06:45Z" level=info msg="Connected as 'groot' to 'nyc' @ '172.18.0.2'"
time="2020-07-02T14:06:47Z" level=info msg="HEAD /" method=HEAD url=/
time="2020-07-02T14:06:50Z" level=info msg="GET /" method=GET url=/

Now, if you look at the pg_tileserv tab again, you'll see the default UI as well as all of the NYC data being delivered as vector tiles (under Table Layers).

Next, we'll go over the default UI and then show you how to add a user-defined function and have it available via pg_tileserv.