<!-- Converted by db4-upgrade version 1.1 -->
<section xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="PostGIS_GUC">
    <title>Grand Unified Custom Variables (GUCs)</title><info>
    <abstract>
    <para>This section lists custom PostGIS Grand Unified Custom Variables (GUC).
These can be set globally, by database, by session or by transaction. Best set at global or database level.</para>
<para>For more examples of usage refer to <link xlink:href="https://www.postgresql.org/docs/current/sql-set.html">SQL SET</link> 
    and <link xlink:href="https://www.postgresql.org/docs/current/sql-altersystem.html">SQL ALTER SYSTEM</link></para>
    </abstract>
    </info>

  <refentry xml:id="postgis_gdal_datapath">
            <refnamediv>
                <refname>postgis.gdal_datapath</refname>
                <refpurpose>
                    A configuration option to assign the value of GDAL's GDAL_DATA option. If not set, the environmentally set GDAL_DATA variable is used.
                </refpurpose>
            </refnamediv>

            <refsection>
                <title>Description</title>
                <para>
                    A PostgreSQL GUC variable for setting the value of GDAL's GDAL_DATA option. The <varname>postgis.gdal_datapath</varname> value should be the complete physical path to GDAL's data files.
                </para>
                <para>
                    This configuration option is of most use for Windows platforms where GDAL's data files path is not hard-coded. This option should also be set when GDAL's data files are not located in GDAL's expected path.
                </para>

                <note>
                    <para>
                        This option can be set in PostgreSQL's configuration file postgresql.conf. It can also be set by connection or transaction.
                    </para>
                </note>
                <para role="availability" conformance="2.2.0">Availability: 2.2.0</para>

                <note>
                    <para>
                        Additional information about GDAL_DATA is available at GDAL's <link xlink:href="http://trac.osgeo.org/gdal/wiki/ConfigOptions">Configuration Options</link>.
                    </para>
                </note>

            </refsection>

            <refsection>
                <title>Examples</title>
                <para>Set and reset <varname>postgis.gdal_datapath</varname></para>

                <programlisting>
SET postgis.gdal_datapath TO '/usr/local/share/gdal.hidden';
SET postgis.gdal_datapath TO default;
                </programlisting>

                <para>Setting on windows for a particular database</para>
                <programlisting>ALTER DATABASE gisdb
SET postgis.gdal_datapath = 'C:/Program Files/PostgreSQL/9.3/gdal-data';</programlisting>
            </refsection>

            <refsection>
                <title>See Also</title>
                <para>
                    <xref linkend="RT_PostGIS_GDAL_Version"/>, <xref linkend="RT_ST_Transform"/>
                </para>
            </refsection>
    </refentry>

  <refentry xml:id="postgis_gdal_enabled_drivers">
            <refnamediv>
                <refname>postgis.gdal_enabled_drivers</refname>
                <refpurpose>
                    A configuration option to set the enabled GDAL drivers in the PostGIS environment. Affects the GDAL configuration variable GDAL_SKIP.
                </refpurpose>
            </refnamediv>

            <refsection>
                <title>Description</title>
                <para>
                    A configuration option to set the enabled GDAL drivers in the PostGIS environment. Affects the GDAL configuration variable GDAL_SKIP. This option can be set in PostgreSQL's configuration file: postgresql.conf. It can also be set by connection or transaction.
                </para>

                <para>
                    The initial value of <varname>postgis.gdal_enabled_drivers</varname> may also be set by passing the environment variable <varname>POSTGIS_GDAL_ENABLED_DRIVERS</varname> with the list of enabled drivers to the process starting PostgreSQL.
                </para>

                <para>
                    Enabled GDAL specified drivers can be specified by the driver's short-name or code. Driver short-names or codes can be found at <link xlink:href="http://www.gdal.org/formats_list.html">GDAL Raster Formats</link>. Multiple drivers can be specified by putting a space between each driver.
                </para>

                <note>
                    <para>
                        There are three special codes available for <varname>postgis.gdal_enabled_drivers</varname>. The codes are case-sensitive.

                        <itemizedlist>
                            <listitem>
                                <para><varname>DISABLE_ALL</varname> disables all GDAL drivers. If present, <varname>DISABLE_ALL</varname> overrides all other values in <varname>postgis.gdal_enabled_drivers</varname>.</para>
                        </listitem>
                            <listitem>
                                <para><varname>ENABLE_ALL</varname> enables all GDAL drivers.</para>
                        </listitem>
                            <listitem>
                                <para><varname>VSICURL</varname> enables GDAL's <varname>/vsicurl/</varname> virtual file system.</para>
                        </listitem>
                        </itemizedlist>
                    </para>
                    <para>
                        When <varname>postgis.gdal_enabled_drivers</varname> is set to DISABLE_ALL, attempts to use out-db rasters, ST_FromGDALRaster(), ST_AsGDALRaster(), ST_AsTIFF(), ST_AsJPEG() and ST_AsPNG() will result in error messages.
                    </para>
                </note>

                <note>
                    <para>
                        In the standard PostGIS installation, <varname>postgis.gdal_enabled_drivers</varname> is set to DISABLE_ALL.
                    </para>
                </note>

                <note>
                    <para>
                        Additional information about GDAL_SKIP is available at GDAL's <link xlink:href="http://trac.osgeo.org/gdal/wiki/ConfigOptions">Configuration Options</link>.
                    </para>
                </note>

                <para role="availability" conformance="2.2.0">Availability: 2.2.0</para>

            </refsection>

            <refsection>
                <title>Examples</title>
                <para>To set and reset <varname>postgis.gdal_enabled_drivers</varname> for current session</para>

                <programlisting>
SET postgis.gdal_enabled_drivers = 'ENABLE_ALL';
SET postgis.gdal_enabled_drivers = default;
                </programlisting>

                <para>Set for all new connections to a specific database to specific drivers</para>

                <programlisting>ALTER DATABASE mygisdb SET postgis.gdal_enabled_drivers TO 'GTiff PNG JPEG';</programlisting>

                <para>Setting for whole database cluster to enable all drivers. Requires super user access.
                    Also note that database, session, and user settings override this.</para>

                <programlisting>
 --writes to postgres.auto.conf
ALTER SYSTEM SET postgis.gdal_enabled_drivers TO 'ENABLE_ALL';
 --Reloads postgres conf
SELECT pg_reload_conf();
                </programlisting>
            </refsection>

            <refsection>
                <title>See Also</title>
                <para>
                    <xref linkend="RT_ST_FromGDALRaster"/>,
                    <xref linkend="RT_ST_AsGDALRaster"/>,
                    <xref linkend="RT_ST_AsTIFF"/>,
                    <xref linkend="RT_ST_AsPNG"/>,
                    <xref linkend="RT_ST_AsJPEG"/>,
                    <xref linkend="postgis_enable_outdb_rasters"/>
                </para>
            </refsection>
    </refentry>

  <refentry xml:id="postgis_enable_outdb_rasters">
            <refnamediv>
                <refname>postgis.enable_outdb_rasters</refname>
                <refpurpose>
                    A boolean configuration option to enable access to out-db raster bands.
                </refpurpose>
            </refnamediv>

            <refsection>
                <title>Description</title>
                <para>
                    A boolean configuration option to enable access to out-db raster bands. This option can be set in PostgreSQL's configuration file: postgresql.conf. It can also be set by connection or transaction.
                </para>

                <para>
                    The initial value of <varname>postgis.enable_outdb_rasters</varname> may also be set by passing the environment variable <varname>POSTGIS_ENABLE_OUTDB_RASTERS</varname> with a non-zero value to the process starting PostgreSQL.
                </para>

                <note>
                    <para>
                        Even if <varname>postgis.enable_outdb_rasters</varname> is True, the GUC <varname>postgis.gdal_enabled_drivers</varname> determines the accessible raster formats.
                    </para>
                </note>

                <note>
                    <para>
                        In the standard PostGIS installation, <varname>postgis.enable_outdb_rasters</varname> is set to False.
                    </para>
                </note>

                <para role="availability" conformance="2.2.0">Availability: 2.2.0</para>

            </refsection>

            <refsection>
                <title>Examples</title>
                <para>Set and reset <varname>postgis.enable_outdb_rasters</varname> for current session</para>

                <programlisting>
SET postgis.enable_outdb_rasters TO True;
SET postgis.enable_outdb_rasters = default;
SET postgis.enable_outdb_rasters = True;
SET postgis.enable_outdb_rasters = False;
                </programlisting>

                <para>Set for all new connections to a specific database</para>

                <programlisting>
ALTER DATABASE gisdb SET postgis.enable_outdb_rasters = true;
                </programlisting>

                <para>Setting for whole database cluster. Requires super user access.
                    Also note that database, session, and user settings override this.</para>
                <programlisting>
 --writes to postgres.auto.conf
ALTER SYSTEM SET postgis.enable_outdb_rasters = true;
 --Reloads postgres conf
SELECT pg_reload_conf();
                </programlisting>
            </refsection>

            <refsection>
                <title>See Also</title>
                <para>
                    <xref linkend="postgis_gdal_enabled_drivers"/>
                    <xref linkend="postgis_gdal_vsi_options"/>
                </para>
            </refsection>
    </refentry>


  <refentry xml:id="postgis_gdal_vsi_options">
            <refnamediv>
                <refname>postgis.gdal_vsi_options</refname>
                <refpurpose>
                    A string configuration to set options used when working with an out-db raster.
                </refpurpose>
            </refnamediv>

            <refsection>
                <title>Description</title>
                <para>
                    A string configuration to set options used when working with an out-db raster. <link xlink:href="http://trac.osgeo.org/gdal/wiki/ConfigOptions">Configuration options</link> control things like how much space GDAL allocates to local data cache, whether to read overviews, and what access keys to use for remote out-db data sources.
                </para>

                <para role="availability" conformance="3.2.0">Availability: 3.2.0</para>

            </refsection>

            <refsection>
                <title>Examples</title>
                <para>Set <varname>postgis.gdal_vsi_options</varname> for current session:</para>

                <programlisting>
SET postgis.gdal_vsi_options = 'AWS_ACCESS_KEY_ID=xxxxxxxxxxxxxxx AWS_SECRET_ACCESS_KEY=yyyyyyyyyyyyyyyyyyyyyyyyyy';
                </programlisting>

                <para>Set <varname>postgis.gdal_vsi_options</varname> just for the <emphasis>current transaction</emphasis> using the <varname>LOCAL</varname> keyword:</para>
                <programlisting>
SET LOCAL postgis.gdal_vsi_options = 'AWS_ACCESS_KEY_ID=xxxxxxxxxxxxxxx AWS_SECRET_ACCESS_KEY=yyyyyyyyyyyyyyyyyyyyyyyyyy';
                </programlisting>
            </refsection>

            <refsection>
                <title>See Also</title>
                <para>
                    <xref linkend="postgis_enable_outdb_rasters"/>
                    <xref linkend="postgis_gdal_enabled_drivers"/>
                </para>
            </refsection>
    </refentry>



</section>
