diff --git a/README.md b/README.md index 5f566f0..b64e6d5 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,10 @@ PgOSM Flex provides high quality OpenStreetMap datasets in PostGIS using the This project provides a curated set of Lua and SQL scripts to clean and organize the most commonly used OpenStreetMap data, such as roads, buildings, and points of interest (POIs). -The easiest way to use PgOSM Flex is via [the Docker image](docs/DOCKER-RUN.md). -For ultimate control and customization, -there are [instructions for installing and running manually](docs/MANUAL-STEPS-RUN.md). +The recommended way to use PgOSM Flex is via the PgOSM Docker image +[hosted on Docker Hub](https://hub.docker.com/repository/docker/rustprooflabs/pgosm-flex). +Basic usage instructions are included in this README.md file, full Docker +usage instructions are available in [docs/DOCKER-RUN.md](docs/DOCKER-RUN.md). ## Project decisions @@ -17,13 +18,14 @@ A few decisions made in this project: * ID column is `osm_id` * Geometry stored in SRID 3857 (customizable) * Geometry column named `geom` -* Default to same units as OpenStreetMap (e.g. km/hr, meters) -* Data not deemed worthy of a dedicated column goes in side table `osm.tags`. Raw key/value data stored in `JSONB` column +* Defaults to same units as OpenStreetMap (e.g. km/hr, meters) +* Data not included in a dedicated column goes into the `osm.tags` table's `JSONB` column * Points, Lines, and Polygons are not mixed in a single table * Tracks latest Postgres, PostGIS, and osm2pgsql versions This project's approach is to do as much processing in the Lua styles -passed along to osm2pgsql, with post-processing steps creating indexes, constraints and comments. +passed along to osm2pgsql, with post-processing steps creating indexes, +constraints and comments. @@ -66,9 +68,9 @@ The PBF/MD5 source files are archived by date on your local storage with the ability to easily reload them at a later date. -### Basic Docker usage +### Docker usage -This section outlines the basic operations for using Docker to run PgOSM-Flex. +This section outlines a typical import using Docker to run PgOSM-Flex. See [the full Docker instructions in docs/DOCKER-RUN.md](docs/DOCKER-RUN.md). Create directory for the `.osm.pbf` file, output `.sql` file, log output, and @@ -264,8 +266,8 @@ For example queries with data loaded by PgOSM-Flex see ## Points of Interest (POIs) - -Loads an range of tags into a materialized view (`osm.poi_all`) for easy searching POIs. +PgOSM Flex loads an range of tags into a materialized view (`osm.poi_all`) for +easily searching POIs. Line and polygon data is forced to point geometry using `ST_Centroid()`. This layer duplicates a bunch of other more specific layers (shop, amenity, etc.) to provide a single place for simplified POI searches. @@ -330,10 +332,10 @@ SELECT geom_type, COUNT(*) ## One table to rule them all From the perspective of database design, the `osm.unitable` option is the **worst**! -This violates all sorts of best practices established in this project +This table violates all sorts of best practices established in this project by shoving all features into a single unstructured table. -> This style included in PgOSM-Flex is intended to be used for troubleshooting and quality control. It is not intended to be used for real production workloads! This table is helpful for exploring the full data set when you don't really know what you are looking for, but you know **where** you are looking. +> This style included in PgOSM Flex is intended to be used for troubleshooting and quality control. It is not intended to be used for real production workloads! This table is helpful for exploring the full data set when you don't really know what you are looking for, but you know **where** you are looking. Unitable is loaded with the `everything` layerset. Feel free to create your own customized layerset if needed. @@ -355,24 +357,19 @@ docker exec -it \ ## JSONB support -PgOSM-Flex uses `JSONB` in Postgres to store the raw OpenSteetMap +PgOSM-Flex uses `JSONB` in Postgres to store the raw OpenStreetMap key/value data (`tags` column) and relation members (`member_ids`). +The `tags` column only exists in the `osm.tags` and `osm.unitable` tables. +The `member_ids` column is included in: -Current `JSONB` columns: - -* `osm.tags.tags` -* `osm.unitable.tags` -* `osm.place_polygon.member_ids` -* `osm.vplace_polygon.member_ids` -* `osm.poi_polygon.member_ids` - - - -## On-server import +* `osm.place_polygon` +* `osm.poi_polygon` +* `osm.public_transport_line` +* `osm.public_transport_polygon` +* `osm.road_line` +* `osm.road_major` +* `osm.road_polygon` -Don't want to use the Docker process? -See [docs/MANUAL-STEPS-RUN.md](docs/MANUAL-STEPS-RUN.md) for prereqs and steps -for running without Docker. diff --git a/docs/APPEND-MODE.md b/docs/APPEND-MODE.md index 5ed9656..f3873cf 100644 --- a/docs/APPEND-MODE.md +++ b/docs/APPEND-MODE.md @@ -1,94 +1 @@ -# Running osm2pgsql in append mode - -## FIXME: These docs are outdated and inaccurate - -Needs updating, `--append` is removed, now under `--replication` - -New option to `--update` in create/append mode making osm2pgsql's append -option available. - - ----- - - -> The `--replication` feature is experimental. - ----- - - -## Using manual steps - -This section documents differences from [MANUAL-STEPS-RUN.md](MANUAL-STEPS-RUN.md) - - -Setup - Need to use Python venv, osmium is a requirement. Something like... - -```bash -python -m venv venv && source venv/bin/activate -cd ~/git/pgosm-flex && pip install -r requirements.txt -``` - - -Run osm2pgsql. Must use `--slim` mode without drop. - - -```bash -cd pgosm-flex/flex-config - -osm2pgsql --output=flex --style=./run.lua \ - --slim \ - -d $PGOSM_CONN \ - ~/pgosm-data/district-of-columbia-latest.osm.pbf -``` - -Run the normal post-processing as you normally would. - - -`osm2pgsql-replication` is bundled with osm2pgsql install. - -https://osm2pgsql.org/doc/manual.html#keeping-the-database-up-to-date-with-osm2pgsql-replication - - -Initialize replication. - - -```bash -osm2pgsql-replication init -d $PGOSM_CONN \ - --osm-file ~/pgosm-data/district-of-columbia-latest.osm.pbf -``` - - - -Refresh the data. First clear out data that might violate foreign keys. Packaged -in convenient procedure. - - -```sql -CALL osm.append_data_start(); -``` - -Update the data. - - -```bash -osm2pgsql-replication update -d $PGOSM_CONN \ - -- \ - --output=flex --style=./run.lua \ - --slim \ - -d $PGOSM_CONN -``` - -Refresh Mat views, rebuilds nested place polygon data. - - -```sql -CALL osm.append_data_finish(); -``` - - -Skip nested: - -```sql -CALL osm.append_data_finish(skip_nested := True); -``` - +The contents of this file have moved to [MANUAL-STEPS-REPLICATION.md](MANUAL-STEPS-REPLICATION.md). \ No newline at end of file diff --git a/docs/DUMP-AND-LOAD.md b/docs/DUMP-AND-LOAD.md index a5e682c..a720957 100644 --- a/docs/DUMP-AND-LOAD.md +++ b/docs/DUMP-AND-LOAD.md @@ -1,5 +1,8 @@ # PgOSM Flex: Dump and reload data +> These manual procedures (outside of Docker) are not regularly tested or reviewed. The recommended way to use PgOSM Flex is through the Docker image. The Docker image is capable of renaming the schema and running pg_dump when desired. + +---- To move data loaded on one Postgres instance to another, use `pg_dump`. The import from PBF to PostGIS is far more taxing on resources than general diff --git a/docs/MANUAL-STEPS-REPLICATION.md b/docs/MANUAL-STEPS-REPLICATION.md new file mode 100644 index 0000000..09e5d58 --- /dev/null +++ b/docs/MANUAL-STEPS-REPLICATION.md @@ -0,0 +1,97 @@ +# Manually run osm2pgsql in replication mode + + +> These manual procedures (outside of Docker) are not regularly tested or reviewed. The recommended way to use PgOSM Flex is through the Docker image. The Docker image is capable of using osm2pgsql-replication as described in this document. + +---- + +Needs updating, `--append` is removed, now under `--replication` + +New option to `--update` in create/append mode making osm2pgsql's append +option available. + + +---- + + +> The `--replication` feature is experimental. + +---- + + +## Using manual steps + +This section documents differences from [MANUAL-STEPS-RUN.md](MANUAL-STEPS-RUN.md) + + +Setup - Need to use Python venv, osmium is a requirement. Something like... + +```bash +python -m venv venv && source venv/bin/activate +cd ~/git/pgosm-flex && pip install -r requirements.txt +``` + + +Run osm2pgsql. Must use `--slim` mode without drop. + + +```bash +cd pgosm-flex/flex-config + +osm2pgsql --output=flex --style=./run.lua \ + --slim \ + -d $PGOSM_CONN \ + ~/pgosm-data/district-of-columbia-latest.osm.pbf +``` + +Run the normal post-processing as you normally would. + + +`osm2pgsql-replication` is bundled with osm2pgsql install. + +https://osm2pgsql.org/doc/manual.html#keeping-the-database-up-to-date-with-osm2pgsql-replication + + +Initialize replication. + + +```bash +osm2pgsql-replication init -d $PGOSM_CONN \ + --osm-file ~/pgosm-data/district-of-columbia-latest.osm.pbf +``` + + + +Refresh the data. First clear out data that might violate foreign keys. Packaged +in convenient procedure. + + +```sql +CALL osm.append_data_start(); +``` + +Update the data. + + +```bash +osm2pgsql-replication update -d $PGOSM_CONN \ + -- \ + --output=flex --style=./run.lua \ + --slim \ + -d $PGOSM_CONN +``` + +Refresh Mat views, rebuilds nested place polygon data. + + +```sql +CALL osm.append_data_finish(); +``` + + +Skip nested: + +```sql +CALL osm.append_data_finish(skip_nested := True); +``` + diff --git a/docs/MANUAL-STEPS-RUN.md b/docs/MANUAL-STEPS-RUN.md index c6a74b8..6124838 100644 --- a/docs/MANUAL-STEPS-RUN.md +++ b/docs/MANUAL-STEPS-RUN.md @@ -1,4 +1,8 @@ -# PgOSM Flex Standard Import +# PgOSM Flex Manual Import + +> These manual procedures (outside of Docker) are not regularly tested or reviewed. The recommended way to use PgOSM Flex is through the Docker image. The Docker image is capable of adjusting for regions of any size so this manual process no longer serves a necessary purpose. + +---- These instructions show how to manually run the PgOSM-Flex process. This is the best option for scaling to larger regions (North America, Europe, etc.) diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md index 32d547f..4b0a5c4 100644 --- a/docs/PERFORMANCE.md +++ b/docs/PERFORMANCE.md @@ -7,7 +7,7 @@ server size [outlined in the osm2pgsql manual](https://osm2pgsql.org/doc/manual. ## Versions Tested -Versions used for testing: PgOSM Flex 0.4.7 Docker image, based on the offical +Versions used for testing: PgOSM Flex 0.4.7 Docker image, based on the official PostGIS image with Postgres 14 / PostGIS 3.2. diff --git a/docs/UPDATE-MODE.md b/docs/UPDATE-MODE.md index 892ef70..921af36 100644 --- a/docs/UPDATE-MODE.md +++ b/docs/UPDATE-MODE.md @@ -1,7 +1,9 @@ # PgOSM Flex Update Mode Running in experimental Update mode enables using osm2pgsql's `--append` -option. Not to be confused with the `--append` option in PgOSM Flex prior to 0.7.0... +option. + +> Note: This is **not** the `--append` option that existed in PgOSM Flex 0.6.3 and prior. ## Testing steps diff --git a/requirements.txt b/requirements.txt index c239de2..495ddac 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ click>=8.1.3 coverage>=6.4.1 -osm2pgsql-tuner==0.0.6rc2 +osm2pgsql-tuner==0.0.6 osmium>=3.4.1 psycopg>=3.1 psycopg-binary>=3.1