document public.gtfs_via_postgres_import_version() 📝

follow-up of ea6395c

Author: derhuerst

cli.js

@@ -120,6 +120,11 @@ Options:
                                     Like --stats-by-route-date, this flag accepts
                                     none, view & materialized-view.
     --schema                      The schema to use for the database. Default: public
+                                    Even when importing into a schema other than \`public\`,
+                                    a function \`public.gtfs_via_postgres_import_version()\`
+                                    gets created, to ensure that multiple imports into the
+                                    same database are all made using the same version. See
+                                    also multiple-datasets.md in the docs.
     --postgraphile                Tweak generated SQL for PostGraphile usage.
                                     https://www.graphile.org/postgraphile/
     --postgraphile-password       Password for the PostGraphile PostgreSQL user.

docs/multiple-datasets.md

@@ -31,3 +31,5 @@ FROM
 ORDER BY paris.stop_loc <-> berlin.stop_loc DESC
 LIMIT 100
 ```
+
+*Note:* During an import, a function `public.gtfs_via_postgres_import_version()` gets created that returns `gtfs-via-postgres`'s version. If that function already exists (because it has been created by a previous import), its return value is compared to `gtfs-via-postgres`'s version, and if these two versions are not equal, the second import will fail. This ensures that multiple imports into the same database can only be made using the exact same `gtfs-via-postgres` version.

readme.md

@@ -179,6 +179,11 @@ Options:
                                     Like --stats-by-route-date, this flag accepts
                                     none, view & materialized-view.
     --schema                      The schema to use for the database. Default: public
+                                    Even when importing into a schema other than `public`,
+                                    a function `public.gtfs_via_postgres_import_version()`
+                                    gets created, to ensure that multiple imports into the
+                                    same database are all made using the same version. See
+                                    also multiple-datasets.md in the docs.
     --postgraphile                Tweak generated SQL for PostGraphile usage.
                                     https://www.graphile.org/postgraphile/
     --postgraphile-password       Password for the PostGraphile PostgreSQL user.