[postgis-devel] Replacement of raster_columns and raster_overviews with constriant-based views in PostGIS Raster

[Bborie Park]

As of r8305, PostGIS Raster has replaced the raster_columns and
raster_overviews tables with constraint-based views.  The table to
view change was taken to keep in sync with the geomety_columns and
geography_columns views found in PostGIS as well as keep the values in
raster_columns and raster_overviews up to date without users doing so.
 When you run rtpostgis_upgrade_20_minor.sql or raster_upgrade.sql,
the two tables will be renamed by prefixing the names with
"deprecated_".

In addition to the table to view changes, the sets of functions for
AddRasterColumn, DropRasterColumn and DropRasterTable are now
deprecated in favor of AddRasterConstraints, DropRasterConstraints,
AddOverviewConstraints and DropOverviewConstraints.  AddRasterColumn
has been modified so that the python raster2pgsql.py  loader utility
continues to work but does nothing regarding the deprecated
raster_columns table.

One thing worth noting is that unlike AddRasterColumn where the
function creates the raster column and SRID constraint BEFORE you load
any raster data, AddRasterConstraints is called AFTER you've loaded
your raster data into your table.  This is because
AddRasterConstraints attempts to determine the constraint conditions
using the existing raster data instead of having you provide the
conditions and the large number of constraints possible (see below).

As stated above, the views are constraint-based.  This means that the
following constraints can now be applied to your raster columns:

enforce_srid (already existed prior to this revision): all rasters in
column have the same SRID

enforce_scalex: all rasters in column have the same scale in the X-axis

enforce_scaley: all rasters in column have the same scale in the Y-axis

enforce_width: all rasters in column have the same width

enforce_height: all rasters in column have the same height

enforce max_extent: all rasters in column are within the specified
maximum extent

enforce_same_alignment: all rasters in column are aligned where any
two rasters passed to ST_SameAlignment = TRUE

enforce_regular_blocking: a purely informational constraint (does NO
actual constraining) indicating that all the rasters in the column are
regularly blocked.  A regularly blocked set of rasters have the same
scale X and Y, width, height, alignment, does not overlap and has no
gaps within the set of rasters.  It is planned to have this constraint
be a true constraint but probably not until PostGIS 2.1

enforce_num_bands: all rasters in column have the same number of bands

enforce_pixel_types: all rasters in column have same pixel type for
each specific band.  e.g. band 2 of every raster is of the same pixel
type

enforce_nodata_values: all rasters in column have same nodata value
for each specific band. e.g. band 3 of every raster has the same
nodata value

enforce_overview: constraint only for overviews indicating the raster
column is an overview column with appropriate validation to the
reference raster column to make sure that the reference column exists.
 The constraint checks the raster_columns view to make sure the
reference raster column exists

All of the constraints above are optional and can be selectively added
or dropped with AddRasterConstraints, DropRasterConstraints,
AddOverviewConstraints and DropOverviewConstraints.  Any constraint
not applied to a raster column will have its corresponding column in
raster_columns and/or raster_overviews with no value or a "negative"
value (such as 0 for SRID) where appropriate.

So, what should you do with your existing raster and overview columns?

1. For your raster columns, call AddRasterConstraints('SCHEMANAME',
'TABLENAME', 'COLUMNAME') for each of your raster columns.  The basic
call will attempt to apply all constraints.  If you want to be
selective with the constraint(s), check the function in rtpostgis.sql

2. For your overview columns, call
AddOverviewConstraints('SCHEMANAME', 'TABLENAME', 'COLUMNNAME',
'REFRASTERSCHEMA', REFRASTERTABLE', 'REFRASTERCOL', 'OVERVIEWFACTOR')
for each of your overview columns using the information found in
deprecated_raster_overviews table.

In the next several weeks, the python-based raster2pgsql loader will
be replaced with one written in C.  At that time, the AddRasterColumn,
DropRasterColumn and DropRasterTable functions will be removed.  Your
deprecated_raster_columns and deprecated_raster_overviews tables will
remain untouched and it is left up to you to drop those tables.

If you're interested in looking at the discussion leading up to this
change, please check ticket #1319
(http://trac.osgeo.org/postgis/ticket/1319).

-bborie