postgis

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

README

pg/postgis

The template for a Postgres extension package. It is also a usable PostGIS layer for the calls a location feature needs. Needs CREATE EXTENSION postgis.

SQL Helper
Column type Geometry, EWKB hex text on the wire
ST_SetSRID(ST_MakePoint(lon, lat), srid) MakePoint
ST_Distance, ST_DistanceSphere Distance, DistanceSphere
ST_DWithin(a, b, d) DWithin, the index-served radius predicate
ST_Intersects, ST_Contains Intersects, Contains
a <-> b in ORDER BY KNN
ST_AsGeoJSON AsGeoJSON

How to add an extension package

Copy this directory, then change four things.

  1. The column type. A Go type with Scan and Value in the extension's text I/O form, so any database/sql driver carries it. Decoding beyond text is the job of a domain library, not the builder.
  2. The helpers. One line each over the constructors pg exports: pg.Func for a call, pg.BinOp for an operator that yields a value, pg.BinPred for an operator that yields a boolean, pg.Expr or pg.Pred when the shape is irregular, pg.ClauseIn for a statement clause. The first argument is the construct name that appears in the error, "postgis.DWithin".
  3. The guard test. Build one statement under sqlb.SQLiteDialect{} and assert sqlb.ErrUnsupportedDialect; build the same under Postgres and assert the exact SQL. The guard is what makes the package safe to import in a multi-engine library.
  4. The README. A table from SQL to helper, the CREATE EXTENSION line, and the index the operators expect.

Nothing in pg changes. The extension package imports pg for the constructors and sqlb for the types, and the application imports the extension package. A helper the extension package lacks is written the same way by the application, against the same constructors.

Documentation

Overview

Package postgis is the template for adding a Postgres extension without touching pg. It covers the PostGIS calls a location feature needs: make a point, measure, filter by radius, order by nearest. Needs CREATE EXTENSION postgis. Everything here is one line over pg's exported constructors, so a new extension package is a copy of this file with the names changed.

Index

Constants

This section is empty.

Variables

View Source
var ErrGeometryType = errors.New("postgis: geometry must scan from text")

ErrGeometryType is returned by Scan for a value that is not text.

View Source
var Extension = pg.Extension{Name: "postgis"}

Extension is the PostGIS extension this package's constructs need, for pg.CreateExtension(Extension), so a library installs what it uses without spelling its name.

Functions

func AsGeoJSON

func AsGeoJSON(g sqlb.Expr[Geometry]) sqlb.Expr[string]

AsGeoJSON renders ST_AsGeoJSON(g).

func Contains

func Contains(a, b sqlb.Expr[Geometry]) sqlb.Predicate

Contains renders ST_Contains(a, b): b lies entirely inside a. The argument order is the reverse of what reads naturally, so name the arguments at the call site.

func DWithin

func DWithin(a, b sqlb.Expr[Geometry], d sqlb.Expr[float64]) sqlb.Predicate

DWithin renders ST_DWithin(a, b, d), the index-served radius predicate.

func Distance

func Distance(a, b sqlb.Expr[Geometry]) sqlb.Expr[float64]

Distance renders ST_Distance(a, b) in the SRID's units.

func DistanceSphere

func DistanceSphere(a, b sqlb.Expr[Geometry]) sqlb.Expr[float64]

DistanceSphere renders ST_DistanceSphere(a, b) in metres.

func Intersects

func Intersects(a, b sqlb.Expr[Geometry]) sqlb.Predicate

Intersects renders ST_Intersects(a, b): the geometries share any point.

func KNN

func KNN(a, b sqlb.Expr[Geometry]) sqlb.Expr[float64]

KNN renders a <-> b for ORDER BY, the nearest-neighbour index scan.

func MakePoint

func MakePoint(lon, lat sqlb.Expr[float64], srid int) sqlb.Expr[Geometry]

MakePoint renders ST_SetSRID(ST_MakePoint(lon, lat), srid). lon comes first because PostGIS points are x, y.

Types

type Geometry

type Geometry string

Geometry is a PostGIS geometry as the server sends it: EWKB hex text, or GeoJSON when selected through AsGeoJSON. The wire form stays opaque here because decoding it is a job for a geometry library, not a query builder.

func (*Geometry) Scan

func (g *Geometry) Scan(src any) error

Scan accepts the text the server sends, EWKB hex or GeoJSON, and keeps it unchanged. It never parses, because decoding geometry is a job for a geometry library.

func (Geometry) Value

func (g Geometry) Value() (driver.Value, error)

Value sends the text back unchanged, so a value read from one query is a valid parameter to the next.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL