geodetic-projdb

Builds an enriched proj.db from a Georepository instance. See Custom database from Georepository for the workflow and what each option is for.

Build a PROJ database enriched with a custom authority’s CRSs and transformations, fetched from a Georepository instance.

usage: geodetic-projdb [-h] [-v] {build,validate,inspect,config} ...

Positional Arguments

command

Possible choices: build, validate, inspect, config

Named Arguments

-v, --verbose

log every imported object

Default: False

Sub-commands

build

build an enriched proj.db

geodetic-projdb build [-h] [--config CONFIG] [--output OUTPUT] [--append]
                      [--replace] [--overwrite-rows] [--no-cache]
                      [--refresh-cache] [--cache-db CACHE_DB]
                      [--skip-validation] [--dry-run]

Named Arguments

--config

TOML file with a [projdb] table (no secrets)

--output

path of the database to write

--append

add to the database already at –output instead of rebuilding it from the base proj.db, so this build extends what another source already wrote there

Default: False

--replace

discard an existing –output database built by other authorities; without this a build that would drop another source’s import is refused

Default: False

--overwrite-rows

replace a colliding row of this build’s own authorities instead of aborting; another authority’s rows are still never touched

Default: False

--no-cache

fetch every object from the register, reading nothing from the local response cache and writing nothing to it

Default: False

--refresh-cache

fetch every object afresh and replace what the cache holds, so the next build is fast again

Default: False

--cache-db

where to keep the cached register responses; defaults to a sidecar of the output database

--skip-validation

write the database without checking that PROJ can read it back

Default: False

--dry-run

run the whole build and report what it would write, then discard it; nothing is left on disk

Default: False

validate

validate an existing proj.db

geodetic-projdb validate [-h] --authority AUTHORITIES database

Positional Arguments

database

Named Arguments

--authority

custom authority to check; repeatable

inspect

summarise what a built database contains

geodetic-projdb inspect [-h] database

Positional Arguments

database

config

show the resolved settings and where they came from

geodetic-projdb config [-h] [--config CONFIG]

Named Arguments

--config

TOML file with a [projdb] table (no secrets)

Example configuration

geodetic-projdb.example.toml, from the repository root. Copy it to geodetic-projdb.toml and edit; the file is picked up from the working directory without a flag. Credentials never go in this file – the loader rejects them – see Handling secrets safely.

# Settings for `geodetic-projdb`.
#
# Copy this file to `geodetic-projdb.toml` and edit the values. It is picked up
# automatically from the working directory; use --config to point elsewhere.
#
# This file holds no secrets: credentials go in `.env` instead, and the loader
# rejects them if it finds them here. See `.env.example`.
#
# Precedence, highest first: command line options, environment variables, this
# file, built-in defaults. A misspelled setting is an error rather than being
# ignored, so a typo cannot silently leave a setting unapplied.

[projdb]

# --- Required ---------------------------------------------------------------

# Base URL of your Georepository instance, without the /api suffix. Must be
# https, because client credentials are sent to it. If you paste a URL that
# still ends in /api or /api/v1 it is trimmed, with a warning.
api_url = "https://georepository.example.com"

# Authority name(s) whose objects are imported, matched against each object's
# DataSource field. This has no default: nothing is assumed about who you are.
# Only rows belonging to these authorities may be written to the database; an
# attempt to write an EPSG, PROJ or ESRI row aborts the build.
authorities = ["YourAuthority"]

# Where the enriched database is written. The official proj.db is copied, never
# modified in place.
output_db = "build/proj.db"

# --- Authentication ---------------------------------------------------------

# OAuth2 token endpoint. Defaults to "{api_url}/auth/connect/token". Set this
# only if your identity server lives elsewhere; it is not described by the
# Georepository API document, so it is never guessed beyond that default.
# token_url = "https://identity.example.com/connect/token"

# Scope requested for the client credentials grant.
# scope = "GeoRepositoryAPI_Scope"

# --- Operation selection ----------------------------------------------------

# How your operations enter PROJ's choice of transformation. This changes which
# operation is applied to a coordinate, so it is stated explicitly.
#
#   custom_first  Your operations are preferred for CRS pairs involving your
#                 authority, and are appended to PROJ's shipped rules for other
#                 pairs so they become candidates without displacing EPSG's
#                 established ordering.
#   custom_only   Your operations are preferred for pairs involving your
#                 authority. Selection between other authorities is untouched.
#   none          No preference rules are written. Your operations are only
#                 found when one of your CRSs is named directly.
# authority_preference = "custom_first"

# Authorities listed after yours in each generated rule.
# fallback_authorities = ["PROJ", "EPSG"]

# --- What to import ---------------------------------------------------------

# Import deprecated objects, flagged as deprecated and linked to their
# replacements. Keep this on if you validate user input: it is what lets you
# answer "that code is deprecated, superseded by X" instead of "CRS not found".
# include_deprecated = true

# Naming systems whose aliases are imported. Defaults to `authorities`. Use
# ["*"] to import aliases from every naming system the register defines, which
# is what you want if it curates several of them for your objects.
# naming_systems = ["YourAuthority"]

# EPSG coordinate operation method codes this PROJ build cannot evaluate.
# Objects using them are skipped and listed in the build report.
# unsupported_method_codes = [1044, 1108]

# --- Combining sources ------------------------------------------------------

# Add to the database already at `output_db` instead of starting from a fresh
# copy of the official proj.db, so this build extends one another source (an
# OSDU catalogue, say) already wrote there. Has no effect when the output does
# not exist yet, so the first build of a chain still starts from the base.
# Off by default: a build that silently added to whatever happened to be at the
# output path could not be reproduced from its configuration alone.
# append = false

# Replace a row this build collides with instead of aborting. Only reaches the
# authorities configured above: the per-row authority guard runs first, and
# every object table is keyed on (auth_name, code), so a replacement can never
# land on an EPSG or PROJ definition. Off by default, so a collision is a
# reported failure rather than a definition that changed underneath whoever was
# already using it.
# overwrite_rows = false

# --- Response cache ----------------------------------------------------------

# A build is almost entirely network wait, and nearly every object it fetches is
# unchanged since the last one, so responses are cached locally by default.
#
#   use      Serve what is cached, store what is not. The default.
#   refresh  Fetch everything afresh and replace what is cached, so the next
#            build is fast again. Use after the register reports a new version.
#   off      Ignore the cache entirely. A full, first-hand build.
#
# The register's version history is never cached, because it is what a build
# reads to decide whether the rest of the cache is stale. When the register has
# moved on, the build warns and continues from cache rather than silently
# turning a version bump into a full refetch.
# cache = "use"

# Where those responses are kept. Defaults to a sidecar of `output_db`, so each
# built database carries its own cache.
# cache_db = "build/proj.db.cache"

# --- Advanced ---------------------------------------------------------------

# Official database to start from. Defaults to the proj.db of the linked PROJ.
# base_proj_db = "/usr/local/share/proj/proj.db"

# Results requested per API page.
# page_size = 500

# Per-request timeout in seconds.
# request_timeout = 60.0

# Georepository version recorded in the build report, for provenance.
# georepository_version = "v1.92"