geo_postgis

To use geo_postgis in your Elixir project, add it to your mix.exs dependencies. Ensure that the PostGIS extension is also installed on your PostgreSQL database.

def deps do
  [
    {:geo_postgis, "~> 3.7"}
  ]
end

Before using PostGIS features, you must ensure the extension is enabled in your database. You can do this via an Ecto migration.

defmodule MyApp.Repo.Migrations.EnablePostgis do
  use Ecto.Migration

  def change do
    execute "CREATE EXTENSION IF NOT EXISTS postgis", "DROP EXTENSION IF EXISTS postgis"
  end
end

When a binary is passed to Geo.PostGIS.Geometry.cast/1 (via Ecto.Type.cast/1), it is treated as a GeoJSON string. By default, geo_postgis uses the standard JSON library to convert this binary to a map. You can specify a different JSON module (e.g., Jason) in your config.exs using the json_library key.

# config.exs
config :geo_postgis,
  json_library: Jason

When Geo.PostGIS.Geometry.cast/1 receives a binary, it assumes the binary is a GeoJSON string. By default, it uses Geo.JSON to decode the string into a map.

If you need to use a different JSON parser for decoding these binaries, you can configure it via Geo.PostGIS.Config.json_library/0. This is useful if your application requires a specific JSON implementation for performance or compatibility reasons.

The Geo.PostGIS module provides a collection of macros that wrap PostGIS functions, allowing you to use spatial operations directly within Ecto queries. To use them, import the module into your query context.

Currently, only OpenGIS functions are implemented.

defmodule Example do
  import Ecto.Query
  import Geo.PostGIS

  def example_query(geom) do
    from location in Location, 
      limit: 5, 
      select: st_distance(location.geom, ^geom)
  end
end

To use PostGIS geometry and geography types in your application, you must register Geo.PostGIS.Extension as a type module using Postgrex.Types.define/2.

If you are using Ecto with the Postgres adapter, you should include the Ecto Postgres extensions alongside the GeoPostGIS extension to ensure all standard Postgres types are also handled correctly.

# Standard Postgrex usage
Postgrex.Types.define(MyApp.PostgresTypes, [Geo.PostGIS.Extension], [])

# Recommended usage with Ecto
Postgrex.Types.define(MyApp.PostgresTypes,
                    [Geo.PostGIS.Extension] ++ Ecto.Adapters.Postgres.extensions(),
                    json: Poison)

To use PostGIS types directly with Postgrex, define a custom types module using Postgrex.Types.define/3 and include Geo.PostGIS.Extension. Pass this module to the types option when starting your connection.

# Define the types module
Postgrex.Types.define(MyApp.PostgresTypes, [Geo.PostGIS.Extension], [])

# Start the connection with the custom types
opts = [hostname: "localhost", username: "postgres", database: "geo_postgrex_test", types: MyApp.PostgresTypes]
{:ok, pid} = Postgrex.Connection.start_link(opts)

# Example usage
geo = %Geo.Point{coordinates: {30, -90}, srid: 4326}
{:ok, _} = Postgrex.Connection.query(pid, "INSERT INTO point_test VALUES ($1, $2)", [42, geo])

You can use implemented OpenGIS functions in Ecto queries by importing Geo.PostGIS. This allows you to perform spatial operations like st_distance directly within your from macros.

defmodule Example do
  import Ecto.Query
  import Geo.PostGIS

  def example_query(geom) do
    query = from location in Location, 
            limit: 5, 
            select: st_distance(location.geom, ^geom)
    query
    |> Repo.one()
  end
end

By default, geo_postgis uses the JSON module if it is loaded; otherwise, it falls back to Poison. This is used when a binary is passed to Geo.PostGIS.Geometry.cast/1 (via Ecto.Type.cast/1), where the binary is assumed to be a GeoJSON string. You can override the default JSON parser by setting the :json_library key in your application configuration under the :geo_postgis application name.

# In your config/config.exs or similar
config :geo_postgis, json_library: MyCustomJsonModule