Difficulty: beginner
Estimated Time: 15 minutes

Intro to pg_featureserv

This scenario gives you an introduction to pg_featureserv.

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

This exercise shows how to connect pg_featureserv to your database and shows the resulting features. We also demonstrate an example of using user-defined functions through pg_featureserv. If you would like to learn more about creating functions in PostgreSQL, 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

pg_featureserv

Pg_featureserv is a lightweight RESTful geospatial feature server for PostGIS, written in Go. It supports the OGC API - Features REST API standard.

Pg_featureserv uses PostGIS to provide geospatial functionality, namely:

  • Transforming geometry data into the output coordinate system
  • Marshalling feature data into GeoJSON

Pg_featureserv requires PostGIS 2.4 or greater to operate.

That's great, but you might be asking: "What does it do? How does it work?" Pg_featureserv works by taking an HTTP request and converting it to the neccessary SQL to have PostGIS return the spatial data as a feature. Pg_featureserv connects to the target PostGIS database via a Database URL connection string. It runs in a completely stateless manner, and any configuration of the data layers is driven by the underlying database. This means that data scientists, analysts and stewards can focus on maintaining their data and data structures.

Now, let's get to showing you how easily it can be added to your PostGIS implementation and expose features.

We put together this exercise to give you a taste of how easily and quickly you can add pg_featureserv to your existing PostGIS implementation and easily expose your spatial data via an API. We also showed you an example of adding a user-defined function and accessing it through the pg_featureserv generated API.

From here you can now add these features as layers to your web maps. Common implementations use OpenLayers or Leaflet. You can also add functions that do more complex geospatial analysis in the database and then expose them as web features. 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_featureserv documentation.

pg_featureserv

Step 1 of 4

pg_featureserv

This exercise will show you the steps to take to add pg_featureserv to your PostGIS implementation.

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

Add pg_featureserv

To add pg_featureserv to your own PostGIS database, you need to either download the source code, or the binaries, or one of our supported containers. We've already pre-staged the container of pg_featureserv for this scenario.

The code block below allows you to click on it to have the code execute in the terminal on the right-hand side. Be sure to click on the Terminal tab before click on the box 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 9000:9000 --env=DATABASE_URL=postgres://groot:[email protected]/nyc pramsey/pg_featureserv: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-06-30T19:48:04Z" level=info msg="----  pg_featureserv - Version 1.1 ----------\n"
time="2020-06-30T19:48:04Z" level=info msg="Using config file: DEFAULT"
time="2020-06-30T19:48:04Z" level=info msg="Using database connection info from environment variable DATABASE_URL"
time="2020-06-30T19:48:04Z" level=info msg="pg-featureserv\n"
time="2020-06-30T19:48:04Z" level=info msg="Connected as groot to nyc @ 172.18.0.2"
time="2020-06-30T19:48:04Z" level=info msg="Serving at 0.0.0.0:9000\n"
time="2020-06-30T19:48:04Z" level=info msg="CORS Allowed Origins: *\n"
time="2020-06-30T19:48:04Z" level=info msg="172.17.0.2:34332 HEAD /\n"
time="2020-06-30T19:48:08Z" level=info msg="172.17.0.4:51916 GET /\n"

Once you do, open the pg_featureserv tab again, and you'll see that it has successfully connected to the default UI. We'll go over some additional information about how pg_featureserv works and the basic layout of the UI on the next pages.