<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="postgis_introduction">
  <title>Introduction</title>

  <section xml:id="what_is_postgis">
    <title>What Is PostGIS?</title>

    <para>PostGIS extends <link xlink:href="https://www.postgresql.org/">PostgreSQL</link>
    so that geospatial data can be stored, indexed, queried, and processed in
    the database. It keeps location data beside ordinary relational data, so a
    spatial query can use the same SQL, transactions, constraints, access
    controls, backup tools, and application connections as the rest of a
    PostgreSQL database.</para>

    <para>The main <literal>postgis</literal> extension adds:</para>

    <itemizedlist>
      <listitem><para><varname>geometry</varname> for planar coordinate systems
      and <varname>geography</varname> for geodetic coordinates on the
      earth.</para></listitem>
      <listitem><para>Spatial indexes that let the PostgreSQL planner avoid
      scanning every row when objects can be filtered by location.</para></listitem>
      <listitem><para>Functions for measurement, relationships, overlays,
      geometry construction and editing, coordinate transformation, clustering,
      and spatial data exchange.</para></listitem>
      <listitem><para>Support for common geospatial encodings and formats,
      including WKT, WKB, GeoJSON, GML, KML, FlatGeobuf, Geobuf, and Mapbox
      Vector Tiles.</para></listitem>
    </itemizedlist>

    <para>This makes PostgreSQL a spatial database: applications can ask both
    ordinary questions and location-aware questions without moving data to a
    separate GIS processing system. Desktop GIS, map servers, ETL tools, and
    application frameworks can connect through normal PostgreSQL interfaces.</para>
  </section>

  <section xml:id="postgis_distribution">
    <title>What Is in the PostGIS Distribution?</title>

    <para>This manual documents the main PostGIS source distribution. Depending
    on how PostGIS was built and packaged, it can provide several PostgreSQL
    extensions and command-line tools:</para>

    <variablelist>
      <varlistentry>
        <term><literal>postgis</literal></term>
        <listitem><para>The core geometry and geography types, spatial indexes,
        and most spatial functions.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>postgis_raster</literal></term>
        <listitem><para>Raster storage, analysis, loading, and export. Raster
        support uses GDAL and can be omitted from a build.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>postgis_topology</literal></term>
        <listitem><para>SQL/MM topology types and functions for models based on
        shared nodes, edges, and faces.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>postgis_sfcgal</literal></term>
        <listitem><para>Additional 2D and 3D processing functions backed by the
        optional SFCGAL library.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>Loaders and utilities</term>
        <listitem><para><command>shp2pgsql</command>,
        <command>pgsql2shp</command>, and <command>raster2pgsql</command> move
        data between common file formats and PostGIS. Other utilities support
        upgrades, profiling, and development.</para></listitem>
      </varlistentry>
    </variablelist>

    <para>The source tree also contains internal libraries such as
    <filename>liblwgeom</filename> and <filename>libpgcommon</filename>. They
    are implementation layers shared by PostGIS components, not separately
    released PostgreSQL extensions. Most users start by enabling the core
    extension with <code>CREATE EXTENSION postgis</code>; see
    <xref linkend="postgis_installation"/> for available components and build
    options.</para>
  </section>

  <section xml:id="postgis_project_family">
    <title>The PostGIS Project Family</title>

    <para>This manual covers the main <literal>postgis/postgis</literal>
    distribution. The official
    <link xlink:href="https://gitea.osgeo.org/postgis/">PostGIS source
    organization</link> also hosts or mirrors complementary projects. These
    projects have their own release cycles, installation instructions, and
    documentation; installing the core extension does not install them.</para>

    <itemizedlist>
      <listitem><para><link xlink:href="https://github.com/postgis/address_standardizer">Address
      Standardizer</link> parses and normalizes postal addresses. It moved from
      the main PostGIS source tree to a separate repository for the PostGIS 3.7
      development cycle.</para></listitem>
      <listitem><para><link xlink:href="https://gitea.osgeo.org/postgis/postgis_tiger_geocoder">PostGIS
      TIGER Geocoder</link> provides United States address geocoding and reverse
      geocoding using Census TIGER data. It is also maintained separately from
      the main distribution.</para></listitem>
      <listitem><para><link xlink:href="https://github.com/postgis/h3-pg">H3-pg</link>
      provides PostgreSQL bindings for the H3 hierarchical hexagonal indexing
      system and interoperates with PostGIS.</para></listitem>
      <listitem><para><link xlink:href="https://github.com/postgis/postgis-java">PostGIS
      Java</link> provides Java bindings for PostGIS types.</para></listitem>
      <listitem><para><link xlink:href="https://postgis.net/workshops/postgis-intro/">Introduction
      to PostGIS</link> is the hands-on workshop maintained by the PostGIS
      project.</para></listitem>
    </itemizedlist>

    <para>Other PostgreSQL spatial extensions can complement PostGIS while
    remaining independent projects. For example,
    <link xlink:href="https://pgrouting.org/">pgRouting</link> adds routing and
    graph analysis. Use each project's own manual for its functions and support
    policy.</para>
  </section>

  <section xml:id="using_this_manual">
    <title>How to Use This Manual</title>

    <para>The manual is both a guide to the PostGIS data model and the complete
    reference for the SQL interface. Choose a starting point based on what you
    are trying to do:</para>

    <variablelist>
      <varlistentry>
        <term>If you are new to spatial SQL</term>
        <listitem><para>Start with the
        <link xlink:href="https://postgis.net/workshops/postgis-intro/">Introduction
        to PostGIS workshop</link> for a tutorial, then use
        <xref linkend="using_postgis_dbmanagement"/> to understand spatial
        types, coordinate systems, validity, loading, and indexes.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>If you are installing or upgrading PostGIS</term>
        <listitem><para>Read <xref linkend="postgis_installation"/> and
        <xref linkend="postgis_administration"/>. Package-specific instructions
        and supported release information are maintained on the
        <link xlink:href="https://postgis.net/documentation/getting_started/">PostGIS
        website</link>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>If you are writing spatial queries</term>
        <listitem><para>Read <xref linkend="using_postgis_query"/> for spatial
        relationships and index-aware query patterns, and
        <xref linkend="performance_tips"/> for common performance problems.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>If you are connecting a desktop GIS</term>
        <listitem><para>Use the client's current database documentation for its
        user interface and supported geometry types. For example, the
        <link xlink:href="https://docs.qgis.org/latest/en/docs/training_manual/databases/db_manager.html">QGIS
        DB Manager lesson</link> covers PostgreSQL connections, table layers,
        SQL query layers, import, and export. A query layer should return a
        stable unique identifier and a geometry column with a known SRID and
        geometry type. Expensive read-only queries can be exposed through a
        view or materialized view and indexed as appropriate.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>If you need a particular function</term>
        <listitem><para>Use <xref linkend="reference"/> or
        <xref linkend="PostGIS_Special_Functions_Index"/>. Function pages state
        accepted types, dimensional support, standards conformance, dependency
        requirements, and version availability.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>If you use an optional component</term>
        <listitem><para>See <xref linkend="Topology"/>,
        <xref linkend="using_raster_dataman"/>,
        <xref linkend="RT_reference"/>, or
        <xref linkend="reference_sfcgal"/>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>If something goes wrong</term>
        <listitem><para>Collect the versions reported by
        <xref linkend="PostGIS_Full_Version"/> and follow
        <xref linkend="reporting"/>. Check <xref linkend="release_notes"/> when
        behavior differs between release lines.</para></listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section xml:id="standards_support">
    <title>Standards Support</title>

    <para>This manual marks individual functions as compliant with spatial
    standards so users can tell which behavior is portable and which behavior is
    a PostGIS extension. PostGIS implements the
    <link xlink:href="https://www.ogc.org/standard/sfs/">OGC Simple Features
    for SQL</link> model, including the geometry type, Well-Known Text (WKT),
    Well-Known Binary (WKB), and the common spatial accessors, constructors,
    predicates, and processing functions. PostGIS also implements many
    <link xlink:href="https://www.iso.org/standard/60343.html">SQL/MM Spatial</link>
    types and functions.</para>

    <para>PostGIS supports geometry families defined by later standards,
    including SQL/MM curved geometry and OGC Simple Features Access 1.2
    PolyhedralSurface, Triangle, and TIN. Support for these geometry families is
    function-specific, and each function page documents the supported input
    types and conformance level.</para>

    <para>PostGIS also includes widely used extensions and integrations.
    Examples of PostGIS extensions include Extended WKT (EWKT), Extended WKB
    (EWKB), SRID metadata in those extended formats, geography, and raster.
    PostGIS also supports input and output exchange formats defined by other
    standards, such as GeoJSON, GML, and KML. These features are documented
    individually and should not be read as OGC Simple Features or SQL/MM
    requirements unless the specific function or format says so.</para>

    <para>When the implementation intentionally differs from a standard, or when
    a standard leaves behavior ambiguous, the relevant function page describes
    the PostGIS behavior. <xref linkend="PostGIS_Special_Functions_Index"/>
    summarizes SQL/MM compliance and geometry-type support across
    functions.</para>
  </section>

  <section xml:id="postgis_project">
    <title>Project and Community</title>

    <para>PostGIS began in 2001 as a spatial database research project at
    Refractions Research. It is now an
    <link xlink:href="https://www.osgeo.org/projects/postgis/">OSGeo project</link>
    developed by contributors and organizations around the world. The Project
    Steering Committee coordinates releases, project policy, and the general
    direction of development. The complete contributor and sponsor record is in
    <xref linkend="postgis_credits"/> at the end of this manual.</para>

    <para>The manual is the authoritative reference for the released SQL
    interface. The project website and source tree provide the surrounding
    material:</para>

    <itemizedlist>
      <listitem><para><link xlink:href="https://postgis.net/documentation/">Documentation</link>
      routes readers to getting-started instructions, versioned manuals, tips,
      training material, and the FAQ.</para></listitem>
      <listitem><para><link xlink:href="https://postgis.net/community/">Community</link>
      lists mailing lists, chat, events, videos, and other support channels.</para></listitem>
      <listitem><para><link xlink:href="https://gitea.osgeo.org/postgis/postgis/src/branch/master/doc/development">Developer documentation</link>
      covers development environments, testing, coding style, internals,
      maintenance, governance, releases, and website work.</para></listitem>
    </itemizedlist>
  </section>

</chapter>
