source: trunk/doc/reference_management.xml @ 7585

Last change on this file since 7585 was 7585, checked in by strk, 5 years ago

Drop dangling reference to Probe_Geometry_Columns (see #1083)

File size: 32.0 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2  <sect1 id="Management_Functions">
3        <title>Management Functions</title>
4
5        <refentry id="AddGeometryColumn">
6          <refnamediv>
7                <refname>AddGeometryColumn</refname>
8
9                <refpurpose>Adds a geometry column to an existing table of
10                attributes. By default uses type modifier to define rather than constraints. 
11                Pass in false for use_typmod to get old check contraint based behavior</refpurpose>
12          </refnamediv>
13
14          <refsynopsisdiv>
15                <funcsynopsis>
16                  <funcprototype>
17                        <funcdef>text <function>AddGeometryColumn</function></funcdef>
18
19                        <paramdef><type>varchar </type>
20                        <parameter>table_name</parameter></paramdef>
21
22                        <paramdef><type>varchar </type>
23                        <parameter>column_name</parameter></paramdef>
24
25                        <paramdef><type>integer </type>
26                        <parameter>srid</parameter></paramdef>
27
28                        <paramdef><type>varchar </type>
29                        <parameter>type</parameter></paramdef>
30
31                        <paramdef><type>integer </type>
32                        <parameter>dimension</parameter></paramdef>
33                        <paramdef choice='opt'><type>boolean </type>
34                        <parameter>use_typmod=true</parameter></paramdef>
35                  </funcprototype>
36
37                  <funcprototype>
38                        <funcdef>text <function>AddGeometryColumn</function></funcdef>
39
40                        <paramdef><type>varchar </type>
41                        <parameter>schema_name</parameter></paramdef>
42
43                        <paramdef><type>varchar </type>
44                        <parameter>table_name</parameter></paramdef>
45
46                        <paramdef><type>varchar </type>
47                        <parameter>column_name</parameter></paramdef>
48
49                        <paramdef><type>integer </type>
50                        <parameter>srid</parameter></paramdef>
51
52                        <paramdef><type>varchar </type>
53                        <parameter>type</parameter></paramdef>
54
55                        <paramdef><type>integer </type>
56                        <parameter>dimension</parameter></paramdef>
57                        <paramdef choice='opt'><type>boolean </type>
58                        <parameter>use_typmod=true</parameter></paramdef>
59                  </funcprototype>
60
61                  <funcprototype>
62                        <funcdef>text <function>AddGeometryColumn</function></funcdef>
63
64                        <paramdef><type>varchar </type>
65                        <parameter>catalog_name</parameter></paramdef>
66
67                        <paramdef><type>varchar </type>
68                        <parameter>schema_name</parameter></paramdef>
69
70                        <paramdef><type>varchar </type>
71                        <parameter>table_name</parameter></paramdef>
72
73                        <paramdef><type>varchar </type>
74                        <parameter>column_name</parameter></paramdef>
75
76                        <paramdef><type>integer </type>
77                        <parameter>srid</parameter></paramdef>
78
79                        <paramdef><type>varchar </type>
80                        <parameter>type</parameter></paramdef>
81
82                        <paramdef><type>integer </type>
83                        <parameter>dimension</parameter></paramdef>
84                       
85                        <paramdef choice='opt'><type>boolean </type>
86                        <parameter>use_typmod=true</parameter></paramdef>
87                  </funcprototype>
88                </funcsynopsis>
89          </refsynopsisdiv>
90
91          <refsection>
92                <title>Description</title>
93
94                <para>Adds a geometry column to an existing table of attributes. The
95                <varname>schema_name</varname> is the name of the table schema. The <varname>srid</varname>
96                must be an integer value reference to an entry in the SPATIAL_REF_SYS
97                table. The <varname>type</varname> must be a string
98                corresponding to the geometry type, eg, 'POLYGON' or
99                'MULTILINESTRING' .  An error is thrown if the schemaname doesn't exist
100                (or not visible in the current search_path) or the specified SRID,
101                geometry type, or dimension is invalid.</para>
102
103                <note>
104                        <para>Changed: 2.0.0 This function no longer updates geometry_columns since geometry_columns is a view that reads from system catalogs.  It by default
105                        also does not create constraints, but instead uses the built in type modifier behavior of PostgreSQL.  So for example building a wgs84 POINT column with this function is now
106                        equivalent to: <code>ALTER TABLE some_table ADD COLUMN geom geometry(Point,4326);</code> </para>
107                        <para>Changed: 2.0.0 If you require the old behavior of constraints use the default <varname>use_typmod</varname>, but set it to false.</para>
108                </note>
109               
110                <note>
111                    <para>Changed: 2.0.0 Views can no longer be manually registered in geometry_columns, however views built against geometry typmod tables geometries and used without wrapper functions will register themselves correctly
112                            because they inherit the typmod behavior of their parent table column.
113                            Views that use geometry functions that output other geometries will need to be cast to typmod geometries for these view geometry columns to be registered correctly
114                            in geometry_columns. Refer to <xref linkend="Manual_Register_Spatial_Column"/>.
115                        </para>
116                </note>
117                <para>&sfs_compliant;</para>
118                <para>&Z_support;</para>
119                <para>&curve_support;</para>
120          </refsection>
121
122          <refsection>
123                <title>Examples</title>
124
125                <programlisting>-- Create schema to hold data
126CREATE SCHEMA my_schema;
127-- Create a new simple PostgreSQL table
128CREATE TABLE my_schema.my_spatial_table (id serial);
129
130-- Describing the table shows a simple table with a single "id" column.
131postgis=# \d my_schema.my_spatial_table
132                                                         Table "my_schema.my_spatial_table"
133 Column |  Type   |                                Modifiers
134--------+---------+-------------------------------------------------------------------------
135 id     | integer | not null default nextval('my_schema.my_spatial_table_id_seq'::regclass)
136
137-- Add a spatial column to the table
138SELECT AddGeometryColumn ('my_schema','my_spatial_table','geom',4326,'POINT',2);
139
140-- Add a point using the old constraint based behavior
141SELECT AddGeometryColumn ('my_schema','my_spatial_table','geom_c',4326,'POINT',2, false);
142
143--Add a curvepolygon using old constraint behavior
144SELECT AddGeometryColumn ('my_schema','my_spatial_table','geomcp_c',4326,'CURVEPOLYGON',2, false);
145
146-- Describe the table again reveals the addition of a new geometry columns.
147\d my_schema.my_spatial_table
148                            addgeometrycolumn                           
149-------------------------------------------------------------------------
150 my_schema.my_spatial_table.geomcp_c SRID:4326 TYPE:CURVEPOLYGON DIMS:2
151(1 row)
152
153                                    Table "my_schema.my_spatial_table"
154  Column  |         Type         |                                Modifiers                               
155----------+----------------------+-------------------------------------------------------------------------
156 id       | integer              | not null default nextval('my_schema.my_spatial_table_id_seq'::regclass)
157 geom     | geometry(Point,4326) |
158 geom_c   | geometry             |
159 geomcp_c | geometry             |
160Check constraints:
161    "enforce_dims_geom_c" CHECK (st_ndims(geom_c) = 2)
162    "enforce_dims_geomcp_c" CHECK (st_ndims(geomcp_c) = 2)
163    "enforce_geotype_geom_c" CHECK (geometrytype(geom_c) = 'POINT'::text OR geom_c IS NULL)
164    "enforce_geotype_geomcp_c" CHECK (geometrytype(geomcp_c) = 'CURVEPOLYGON'::text OR geomcp_c IS NULL)
165    "enforce_srid_geom_c" CHECK (st_srid(geom_c) = 4326)
166    "enforce_srid_geomcp_c" CHECK (st_srid(geomcp_c) = 4326)
167   
168-- geometry_columns view also registers the new columns --
169SELECT f_geometry_column As col_name, type, srid, coord_dimension As ndims
170    FROM geometry_columns
171    WHERE f_table_name = 'my_spatial_table' AND f_table_schema = 'my_schema';
172
173 col_name |     type     | srid | ndims
174----------+--------------+------+-------
175 geom     | Point        | 4326 |     2
176 geom_c   | Point        | 4326 |     2
177 geomcp_c | CurvePolygon | 4326 |     2
178</programlisting>
179          </refsection>
180
181          <refsection>
182                <title>See Also</title>
183
184                <para><xref linkend="DropGeometryColumn"/>, <xref linkend="DropGeometryTable"/>, <xref linkend="geometry_columns"/>, <xref linkend="Manual_Register_Spatial_Column"/></para>
185          </refsection>
186        </refentry>
187
188        <refentry id="DropGeometryColumn">
189          <refnamediv>
190                <refname>DropGeometryColumn</refname>
191
192                <refpurpose>Removes a geometry column from a spatial
193                table.</refpurpose>
194          </refnamediv>
195
196          <refsynopsisdiv>
197                <funcsynopsis>
198                  <funcprototype>
199                        <funcdef>text <function>DropGeometryColumn</function></funcdef>
200
201                        <paramdef><type>varchar </type>
202                        <parameter>table_name</parameter></paramdef>
203
204                        <paramdef><type>varchar </type>
205                        <parameter>column_name</parameter></paramdef>
206                  </funcprototype>
207
208                  <funcprototype>
209                        <funcdef>text <function>DropGeometryColumn</function></funcdef>
210
211                        <paramdef><type>varchar </type>
212                        <parameter>schema_name</parameter></paramdef>
213
214                        <paramdef><type>varchar </type>
215                        <parameter>table_name</parameter></paramdef>
216
217                        <paramdef><type>varchar </type>
218                        <parameter>column_name</parameter></paramdef>
219                  </funcprototype>
220
221                  <funcprototype>
222                        <funcdef>text <function>DropGeometryColumn</function></funcdef>
223
224                        <paramdef><type>varchar </type>
225                        <parameter>catalog_name</parameter></paramdef>
226
227                        <paramdef><type>varchar </type>
228                        <parameter>schema_name</parameter></paramdef>
229
230                        <paramdef><type>varchar </type>
231                        <parameter>table_name</parameter></paramdef>
232
233                        <paramdef><type>varchar </type>
234                        <parameter>column_name</parameter></paramdef>
235                  </funcprototype>
236                </funcsynopsis>
237          </refsynopsisdiv>
238
239          <refsection>
240                <title>Description</title>
241
242                <para>Removes a geometry column from a spatial table. Note that
243                schema_name will need to match the f_table_schema field of the table's
244                row in the geometry_columns table.</para>
245
246                <para>&sfs_compliant;</para>
247                <para>&Z_support;</para>
248                <para>&curve_support;</para>
249                <note>
250                        <para>Changed: 2.0.0 This function is provided for backward compatibility.  Now that since geometry_columns is now a view against the system catalogs,
251                            you can drop a geometry column like any other table column using <code>ALTER TABLE</code></para>
252                </note>
253          </refsection>
254          <refsection>
255                <title>Examples</title>
256
257                <programlisting>
258                        SELECT DropGeometryColumn ('my_schema','my_spatial_table','geom');
259                        ----RESULT output ---
260                                          dropgeometrycolumn
261------------------------------------------------------
262 my_schema.my_spatial_table.geom effectively removed.
263 
264-- In PostGIS 2.0+ the above is also equivalent to the standard
265-- the standard alter table.  Both will deregister from geometry_columns
266ALTER TABLE my_schema.my_spatial_table DROP column geom;
267                </programlisting>
268          </refsection>
269          <refsection>
270                <title>See Also</title>
271
272                <para><xref linkend="AddGeometryColumn"/>, <xref linkend="DropGeometryTable"/>, <xref linkend="geometry_columns"/></para>
273          </refsection>
274        </refentry>
275
276        <refentry id="DropGeometryTable">
277          <refnamediv>
278                <refname>DropGeometryTable</refname>
279
280                <refpurpose>Drops a table and all its references in
281                geometry_columns.</refpurpose>
282          </refnamediv>
283
284          <refsynopsisdiv>
285                <funcsynopsis>
286                  <funcprototype>
287                        <funcdef>boolean <function>DropGeometryTable</function></funcdef>
288
289                        <paramdef><type>varchar </type>
290                        <parameter>table_name</parameter></paramdef>
291                  </funcprototype>
292
293                  <funcprototype>
294                        <funcdef>boolean <function>DropGeometryTable</function></funcdef>
295
296                        <paramdef><type>varchar </type>
297                        <parameter>schema_name</parameter></paramdef>
298
299                        <paramdef><type>varchar </type>
300                        <parameter>table_name</parameter></paramdef>
301                  </funcprototype>
302
303                  <funcprototype>
304                        <funcdef>boolean <function>DropGeometryTable</function></funcdef>
305                        <paramdef><type>varchar </type>
306                        <parameter>catalog_name</parameter></paramdef>
307                        <paramdef><type>varchar </type>
308                        <parameter>schema_name</parameter></paramdef>
309                        <paramdef><type>varchar </type>
310                        <parameter>table_name</parameter></paramdef>
311                  </funcprototype>
312                </funcsynopsis>
313          </refsynopsisdiv>
314
315          <refsection>
316                <title>Description</title>
317
318                <para>Drops a table and all its references in geometry_columns. Note:
319                uses current_schema() on schema-aware pgsql installations if schema is
320                not provided.</para>
321               
322                <note>
323                        <para>Changed: 2.0.0 This function is provided for backward compatibility.  Now that since geometry_columns is now a view against the system catalogs,
324                            you can drop a table with geometry columns like any other table using <code>DROP TABLE</code></para>
325                </note>
326          </refsection>
327
328          <refsection>
329                <title>Examples</title>
330
331                <programlisting>SELECT DropGeometryTable ('my_schema','my_spatial_table');
332----RESULT output ---
333my_schema.my_spatial_table dropped.
334                       
335-- The above is now equivalent to --
336DROP TABLE my_schema.my_spatial_table;
337                </programlisting>
338          </refsection>
339          <refsection>
340                <title>See Also</title>
341
342                <para><xref linkend="AddGeometryColumn"/>, <xref linkend="DropGeometryColumn"/>, <xref linkend="geometry_columns"/></para>
343          </refsection>
344        </refentry>
345
346
347        <refentry id="PostGIS_Full_Version">
348          <refnamediv>
349                <refname>PostGIS_Full_Version</refname>
350
351                <refpurpose>Reports full postgis version and build configuration
352                infos.</refpurpose>
353          </refnamediv>
354
355          <refsynopsisdiv>
356                <funcsynopsis>
357                  <funcprototype>
358                        <funcdef>text <function>PostGIS_Full_Version</function></funcdef>
359
360                        <paramdef></paramdef>
361                  </funcprototype>
362                </funcsynopsis>
363          </refsynopsisdiv>
364
365          <refsection>
366                <title>Description</title>
367
368                <para>Reports full postgis version and build configuration
369                infos.</para>
370          </refsection>
371
372          <refsection>
373                <title>Examples</title>
374
375                <programlisting>SELECT PostGIS_Full_Version();
376                                                           postgis_full_version
377----------------------------------------------------------------------------------
378 POSTGIS="1.3.3" GEOS="3.1.0-CAPI-1.5.0" PROJ="Rel. 4.4.9, 29 Oct 2004" USE_STATS
379(1 row)</programlisting>
380          </refsection>
381
382          <refsection>
383                <title>See Also</title>
384
385                <para><xref linkend="PostGIS_GEOS_Version" />, <xref
386                linkend="PostGIS_Lib_Version" />, <xref
387                linkend="PostGIS_LibXML_Version" />, <xref
388                linkend="PostGIS_PROJ_Version" />, <xref
389                linkend="PostGIS_Version" /></para>
390          </refsection>
391        </refentry>
392
393        <refentry id="PostGIS_GEOS_Version">
394          <refnamediv>
395                <refname>PostGIS_GEOS_Version</refname>
396
397                <refpurpose>Returns the version number of the GEOS
398                library.</refpurpose>
399          </refnamediv>
400
401          <refsynopsisdiv>
402                <funcsynopsis>
403                  <funcprototype>
404                        <funcdef>text <function>PostGIS_GEOS_Version</function></funcdef>
405
406                        <paramdef></paramdef>
407                  </funcprototype>
408                </funcsynopsis>
409          </refsynopsisdiv>
410
411          <refsection>
412                <title>Description</title>
413
414                <para>Returns the version number of the GEOS library, or
415                <varname>NULL</varname> if GEOS support is not enabled.</para>
416          </refsection>
417
418          <refsection>
419                <title>Examples</title>
420
421                <programlisting>SELECT PostGIS_GEOS_Version();
422 postgis_geos_version
423----------------------
424 3.1.0-CAPI-1.5.0
425(1 row)</programlisting>
426          </refsection>
427
428          <refsection>
429                <title>See Also</title>
430
431                <para><xref linkend="PostGIS_Full_Version" />, <xref
432                linkend="PostGIS_Lib_Version" />, <xref
433                linkend="PostGIS_LibXML_Version" />, <xref
434                linkend="PostGIS_PROJ_Version" />, <xref
435                linkend="PostGIS_Version" /></para>
436          </refsection>
437        </refentry>
438
439        <refentry id="PostGIS_LibXML_Version">
440          <refnamediv>
441                <refname>PostGIS_LibXML_Version</refname>
442
443                <refpurpose>Returns the version number of the libxml2
444                library.</refpurpose>
445          </refnamediv>
446
447          <refsynopsisdiv>
448                <funcsynopsis>
449                  <funcprototype>
450                        <funcdef>text <function>PostGIS_LibXML_Version</function></funcdef>
451
452                        <paramdef></paramdef>
453                  </funcprototype>
454                </funcsynopsis>
455          </refsynopsisdiv>
456
457          <refsection>
458                <title>Description</title>
459
460                <para>Returns the version number of the LibXML2 library.</para>
461                <para>Availability: 1.5</para>
462          </refsection>
463
464          <refsection>
465                <title>Examples</title>
466
467                <programlisting>SELECT PostGIS_LibXML_Version();
468 postgis_libxml_version
469----------------------
470 2.7.6
471(1 row)</programlisting>
472          </refsection>
473
474          <refsection>
475                <title>See Also</title>
476
477                <para><xref linkend="PostGIS_Full_Version" />, <xref
478                linkend="PostGIS_Lib_Version" />, <xref
479                linkend="PostGIS_PROJ_Version" />, <xref
480                linkend="PostGIS_GEOS_Version" />, <xref
481                linkend="PostGIS_Version" /></para>
482          </refsection>
483        </refentry>
484
485        <refentry id="PostGIS_Lib_Build_Date">
486          <refnamediv>
487                <refname>PostGIS_Lib_Build_Date</refname>
488
489                <refpurpose>Returns build date of the PostGIS library.</refpurpose>
490          </refnamediv>
491
492          <refsynopsisdiv>
493                <funcsynopsis>
494                  <funcprototype>
495                        <funcdef>text <function>PostGIS_Lib_Build_Date</function></funcdef>
496
497                        <paramdef></paramdef>
498                  </funcprototype>
499                </funcsynopsis>
500          </refsynopsisdiv>
501
502          <refsection>
503                <title>Description</title>
504
505                <para>Returns build date of the PostGIS library.</para>
506          </refsection>
507
508          <refsection>
509                <title>Examples</title>
510
511                <programlisting>SELECT PostGIS_Lib_Build_Date();
512 postgis_lib_build_date
513------------------------
514 2008-06-21 17:53:21
515(1 row)</programlisting>
516          </refsection>
517        </refentry>
518
519        <refentry id="PostGIS_Lib_Version">
520          <refnamediv>
521                <refname>PostGIS_Lib_Version</refname>
522
523                <refpurpose>Returns the version number of the PostGIS
524                library.</refpurpose>
525          </refnamediv>
526
527          <refsynopsisdiv>
528                <funcsynopsis>
529                  <funcprototype>
530                        <funcdef>text <function>PostGIS_Lib_Version</function></funcdef>
531
532                        <paramdef></paramdef>
533                  </funcprototype>
534                </funcsynopsis>
535          </refsynopsisdiv>
536
537          <refsection>
538                <title>Description</title>
539
540                <para>Returns the version number of the PostGIS library.</para>
541          </refsection>
542
543          <refsection>
544                <title>Examples</title>
545
546                <programlisting>SELECT PostGIS_Lib_Version();
547 postgis_lib_version
548---------------------
549 1.3.3
550(1 row)</programlisting>
551          </refsection>
552
553          <refsection>
554                <title>See Also</title>
555
556                <para><xref linkend="PostGIS_Full_Version" />, <xref
557                linkend="PostGIS_GEOS_Version" /><xref
558                linkend="PostGIS_LibXML_Version" />, <xref
559                linkend="PostGIS_PROJ_Version" />, <xref
560                linkend="PostGIS_Version" /></para>
561          </refsection>
562        </refentry>
563
564        <refentry id="PostGIS_PROJ_Version">
565          <refnamediv>
566                <refname>PostGIS_PROJ_Version</refname>
567
568                <refpurpose>Returns the version number of the PROJ4
569                library.</refpurpose>
570          </refnamediv>
571
572          <refsynopsisdiv>
573                <funcsynopsis>
574                  <funcprototype>
575                        <funcdef>text <function>PostGIS_PROJ_Version</function></funcdef>
576
577                        <paramdef></paramdef>
578                  </funcprototype>
579                </funcsynopsis>
580          </refsynopsisdiv>
581
582          <refsection>
583                <title>Description</title>
584
585                <para>Returns the version number of the PROJ4 library, or
586                <varname>NULL</varname> if PROJ4 support is not enabled.</para>
587          </refsection>
588
589          <refsection>
590                <title>Examples</title>
591
592                <programlisting>SELECT PostGIS_PROJ_Version();
593  postgis_proj_version
594-------------------------
595 Rel. 4.4.9, 29 Oct 2004
596(1 row)</programlisting>
597          </refsection>
598
599          <refsection>
600                <title>See Also</title>
601
602                <para><xref linkend="PostGIS_Full_Version" />, <xref
603                linkend="PostGIS_GEOS_Version" /><xref
604                linkend="PostGIS_Lib_Version" />, <xref
605                linkend="PostGIS_LibXML_Version" />, <xref
606                linkend="PostGIS_Version" /></para>
607          </refsection>
608        </refentry>
609
610        <refentry id="PostGIS_Scripts_Build_Date">
611          <refnamediv>
612                <refname>PostGIS_Scripts_Build_Date</refname>
613
614                <refpurpose>Returns build date of the PostGIS scripts.</refpurpose>
615          </refnamediv>
616
617          <refsynopsisdiv>
618                <funcsynopsis>
619                  <funcprototype>
620                        <funcdef>text <function>PostGIS_Scripts_Build_Date</function></funcdef>
621
622                        <paramdef></paramdef>
623                  </funcprototype>
624                </funcsynopsis>
625          </refsynopsisdiv>
626
627          <refsection>
628                <title>Description</title>
629
630                <para>Returns build date of the PostGIS scripts.</para>
631
632                <para>Availability: 1.0.0RC1</para>
633          </refsection>
634
635          <refsection>
636                <title>Examples</title>
637
638                <programlisting>SELECT PostGIS_Scripts_Build_Date();
639  postgis_scripts_build_date
640-------------------------
641 2007-08-18 09:09:26
642(1 row)</programlisting>
643          </refsection>
644
645          <refsection>
646                <title>See Also</title>
647
648                <para><xref linkend="PostGIS_Full_Version" />, <xref
649                linkend="PostGIS_GEOS_Version" />, <xref
650                linkend="PostGIS_Lib_Version" />, <xref
651                linkend="PostGIS_LibXML_Version" />, <xref
652                linkend="PostGIS_Version" /></para>
653          </refsection>
654        </refentry>
655
656        <refentry id="PostGIS_Scripts_Installed">
657          <refnamediv>
658                <refname>PostGIS_Scripts_Installed</refname>
659
660                <refpurpose>Returns version of the postgis scripts installed in this
661                        database.</refpurpose>
662          </refnamediv>
663
664          <refsynopsisdiv>
665                <funcsynopsis>
666                  <funcprototype>
667                        <funcdef>text <function>PostGIS_Scripts_Installed</function></funcdef>
668
669                        <paramdef></paramdef>
670                  </funcprototype>
671                </funcsynopsis>
672          </refsynopsisdiv>
673
674          <refsection>
675                <title>Description</title>
676
677                <para>Returns version of the postgis scripts installed in this
678                        database.</para>
679
680                <note>
681                          <para>If the output of this function doesn't match the output of
682                          <xref linkend="PostGIS_Scripts_Released" />
683                          you probably missed to properly upgrade an existing database.
684                          See the <link linkend="upgrading">Upgrading</link> section for
685                          more info.</para>
686                </note>
687
688                <para>Availability: 0.9.0</para>
689          </refsection>
690
691          <refsection>
692                <title>Examples</title>
693
694                <programlisting>SELECT PostGIS_Scripts_Installed();
695  postgis_scripts_installed
696-------------------------
697 1.5.0SVN
698(1 row)</programlisting>
699          </refsection>
700
701          <refsection>
702                <title>See Also</title>
703
704                <para><xref linkend="PostGIS_Full_Version" />, <xref linkend="PostGIS_Scripts_Released" />, <xref linkend="PostGIS_Version" /></para>
705          </refsection>
706        </refentry>
707
708        <refentry id="PostGIS_Scripts_Released">
709          <refnamediv>
710                <refname>PostGIS_Scripts_Released</refname>
711
712                <refpurpose>Returns the version number of the postgis.sql script
713                released with the installed postgis lib.</refpurpose>
714          </refnamediv>
715
716          <refsynopsisdiv>
717                <funcsynopsis>
718                  <funcprototype>
719                        <funcdef>text <function>PostGIS_Scripts_Released</function></funcdef>
720
721                        <paramdef></paramdef>
722                  </funcprototype>
723                </funcsynopsis>
724          </refsynopsisdiv>
725
726          <refsection>
727                <title>Description</title>
728
729                <para>Returns the version number of the postgis.sql script
730                released with the installed postgis lib.</para>
731
732                <note>
733                  <para>Starting with version 1.1.0 this function returns the same
734                  value of <xref linkend="PostGIS_Lib_Version" />. Kept
735                  for backward compatibility.</para>
736                </note>
737
738                <para>Availability: 0.9.0</para>
739          </refsection>
740
741          <refsection>
742                <title>Examples</title>
743
744                <programlisting>SELECT PostGIS_Scripts_Released();
745  postgis_scripts_released
746-------------------------
747 1.3.4SVN
748(1 row)</programlisting>
749          </refsection>
750
751          <refsection>
752                <title>See Also</title>
753
754                <para><xref linkend="PostGIS_Full_Version" />, <xref linkend="PostGIS_Scripts_Installed" />, <xref linkend="PostGIS_Lib_Version" /></para>
755          </refsection>
756        </refentry>
757
758        <refentry id="PostGIS_Uses_Stats">
759          <refnamediv>
760                <refname>PostGIS_Uses_Stats</refname>
761
762                <refpurpose>Returns <varname>TRUE</varname> if STATS usage has been
763                enabled.</refpurpose>
764          </refnamediv>
765
766          <refsynopsisdiv>
767                <funcsynopsis>
768                  <funcprototype>
769                        <funcdef>text <function>PostGIS_Uses_Stats</function></funcdef>
770
771                        <paramdef></paramdef>
772                  </funcprototype>
773                </funcsynopsis>
774          </refsynopsisdiv>
775
776          <refsection>
777                <title>Description</title>
778
779                <para>Returns <varname>TRUE</varname> if STATS usage has been enabled,
780                <varname>FALSE</varname> otherwise.</para>
781          </refsection>
782
783          <refsection>
784                <title>Examples</title>
785
786                <programlisting>SELECT PostGIS_Uses_Stats();
787 postgis_uses_stats
788--------------------
789 t
790(1 row)</programlisting>
791          </refsection>
792
793          <refsection>
794                <title>See Also</title>
795
796                <para><xref linkend="PostGIS_Version" /></para>
797          </refsection>
798        </refentry>
799
800        <refentry id="PostGIS_Version">
801          <refnamediv>
802                <refname>PostGIS_Version</refname>
803
804                <refpurpose>Returns PostGIS version number and compile-time
805                options.</refpurpose>
806          </refnamediv>
807
808          <refsynopsisdiv>
809                <funcsynopsis>
810                  <funcprototype>
811                        <funcdef>text <function>PostGIS_Version</function></funcdef>
812
813                        <paramdef></paramdef>
814                  </funcprototype>
815                </funcsynopsis>
816          </refsynopsisdiv>
817
818          <refsection>
819                <title>Description</title>
820
821                <para>Returns PostGIS version number and compile-time options.</para>
822          </refsection>
823
824          <refsection>
825                <title>Examples</title>
826
827                <programlisting>SELECT PostGIS_Version();
828                        postgis_version
829---------------------------------------
830 1.3 USE_GEOS=1 USE_PROJ=1 USE_STATS=1
831(1 row)</programlisting>
832          </refsection>
833
834          <refsection>
835                <title>See Also</title>
836
837                <para><xref linkend="PostGIS_Full_Version" />, <xref
838                linkend="PostGIS_GEOS_Version" />,<xref
839                linkend="PostGIS_Lib_Version" />, <xref
840                linkend="PostGIS_LibXML_Version" />, <xref
841                linkend="PostGIS_PROJ_Version" /></para>
842          </refsection>
843        </refentry>
844
845        <refentry id="Populate_Geometry_Columns">
846          <refnamediv>
847                <refname>Populate_Geometry_Columns</refname>
848
849                <refpurpose>Ensures geometry columns are defined with type modifiers or have appropriate spatial constraints
850                This ensures they will be registered correctly in <varname>geometry_columns</varname> view. By default will convert all geometry
851                    columns with no type modifier to ones with type modifiers. To get old behavior set <varname>use_typmod=false</varname></refpurpose>
852          </refnamediv>
853
854          <refsynopsisdiv>
855                <funcsynopsis>
856                  <funcprototype>
857                        <funcdef>text <function>Populate_Geometry_Columns</function></funcdef>
858
859                        <paramdef><type>boolean </type> <parameter>use_typmod=true</parameter></paramdef>
860                  </funcprototype>
861
862                  <funcprototype>
863                        <funcdef>int <function>Populate_Geometry_Columns</function></funcdef>
864
865                        <paramdef><type>oid</type> <parameter>relation_oid</parameter></paramdef>
866                        <paramdef><type>boolean </type> <parameter>use_typmod=true</parameter></paramdef>
867                  </funcprototype>
868                </funcsynopsis>
869          </refsynopsisdiv>
870
871          <refsection>
872                <title>Description</title>
873
874                <para>Ensures geometry columns have appropriate type modifiers or spatial constraints to ensure they are registered correctly in <varname>geometry_columns</varname> table.</para>
875               
876                <para>For backwards compatibility and for spatial needs such as tble inheritance where each child table may have different geometry type, the old check constraint behavior is still supported.
877                If you need the old behavior, you need to pass in the new optional argument as false <varname>use_typmod=false</varname>. When this is done geometry columns will be created with no type modifiers
878                but will have 3 constraints defined.  In particular,
879                this means that every geometry column belonging to a table has at least
880                three constraints:</para>
881
882                <itemizedlist>
883                  <listitem>
884                        <para><varname>enforce_dims_the_geom</varname> - ensures every
885                        geometry has the same dimension (see <xref
886                        linkend="ST_NDims" />)</para>
887                  </listitem>
888
889                  <listitem>
890                        <para><varname>enforce_geotype_the_geom</varname> - ensures every
891                        geometry is of the same type (see <xref
892                        linkend="GeometryType" />)</para>
893                  </listitem>
894
895                  <listitem>
896                        <para><varname>enforce_srid_the_geom</varname> - ensures every
897                        geometry is in the same projection (see <xref
898                        linkend="ST_SRID" />)</para>
899                  </listitem>
900                </itemizedlist>
901
902                <para>If a table <varname>oid</varname> is provided, this function
903                tries to determine the srid, dimension, and geometry type of all
904                geometry columns in the table, adding constraints as necessary. If
905                successful, an appropriate row is inserted into the geometry_columns
906                table, otherwise, the exception is caught and an error notice is raised
907                describing the problem.</para>
908
909                <para>If the <varname>oid</varname> of a view is provided, as with a
910                table oid, this function tries to determine the srid, dimension, and
911                type of all the geometries in the view, inserting appropriate entries
912                into the <varname>geometry_columns</varname> table, but nothing is done
913                to enforce contraints.</para>
914
915                <para>The parameterless variant is a simple wrapper for the parameterized
916                variant that first truncates and repopulates the geometry_columns table
917                for every spatial table and view in the database, adding spatial
918                contraints to tables where appropriate.  It returns a summary of the
919                number of geometry columns detected in the database and the number that
920                were inserted into the <varname>geometry_columns</varname> table.  The
921                parameterized version simply returns the number of rows inserted into
922                the <varname>geometry_columns</varname> table.</para>
923                <para>Availability: 1.4.0</para>
924                <para>Changed: 2.0.0 By default, now uses type modifiers instead of check constraints to constrain geometry types.  You can still use check
925                    constraint behavior instead by using the new  <varname>use_typmod</varname> and setting it to false.</para>
926                <para>Enhanced: 2.0.0 <varname>use_typmod</varname> optional argument was introduced that allows controlling if columns are created with typmodifiers or with check constraints.</para>
927          </refsection>
928
929          <refsection>
930                <title>Examples</title>
931
932                <programlisting>
933CREATE TABLE public.myspatial_table(gid serial, geom geometry);
934INSERT INTO myspatial_table(geom) VALUES(ST_GeomFromText('LINESTRING(1 2, 3 4)',4326) );
935-- This will now use typ modifiers.  For this to work, there must exist data
936SELECT Populate_Geometry_Columns('public.myspatial_table'::regclass);
937
938populate_geometry_columns
939--------------------------
940                        1
941                       
942                       
943\d myspatial_table
944
945                                   Table "public.myspatial_table"
946 Column |           Type            |                           Modifiers                           
947--------+---------------------------+---------------------------------------------------------------
948 gid    | integer                   | not null default nextval('myspatial_table_gid_seq'::regclass)
949 geom   | geometry(LineString,4326) |
950</programlisting>
951                   
952                <programlisting>-- This will change the geometry columns to use constraints if they are not typmod or have constraints already. 
953--For this to work, there must exist data
954CREATE TABLE public.myspatial_table_cs(gid serial, geom geometry);
955INSERT INTO myspatial_table_cs(geom) VALUES(ST_GeomFromText('LINESTRING(1 2, 3 4)',4326) );
956SELECT Populate_Geometry_Columns('public.myspatial_table_cs'::regclass, false);
957populate_geometry_columns
958--------------------------
959                        1
960\d myspatial_table_cs
961
962                          Table "public.myspatial_table_cs"
963 Column |   Type   |                            Modifiers                             
964--------+----------+------------------------------------------------------------------
965 gid    | integer  | not null default nextval('myspatial_table_cs_gid_seq'::regclass)
966 geom   | geometry |
967Check constraints:
968    "enforce_dims_geom" CHECK (st_ndims(geom) = 2)
969    "enforce_geotype_geom" CHECK (geometrytype(geom) = 'LINESTRING'::text OR geom IS NULL)
970    "enforce_srid_geom" CHECK (st_srid(geom) = 4326)</programlisting>
971          </refsection>
972
973<!--
974          <refsection>
975                <title>See Also</title>
976
977                <para><xref linkend="Probe_Geometry_Columns" /></para>
978          </refsection>
979-->
980
981        </refentry>
982
983        <refentry id="UpdateGeometrySRID">
984          <refnamediv>
985                <refname>UpdateGeometrySRID</refname>
986
987                <refpurpose>Updates the SRID of all features in a geometry
988                column, geometry_columns metadata and srid table constraint</refpurpose>
989          </refnamediv>
990
991          <refsynopsisdiv>
992                <funcsynopsis>
993                  <funcprototype>
994                        <funcdef>text <function>UpdateGeometrySRID</function></funcdef>
995
996                        <paramdef><type>varchar </type>
997                        <parameter>table_name</parameter></paramdef>
998
999                        <paramdef><type>varchar </type>
1000                        <parameter>column_name</parameter></paramdef>
1001
1002                        <paramdef><type>integer </type>
1003                        <parameter>srid</parameter></paramdef>
1004                  </funcprototype>
1005
1006                  <funcprototype>
1007                        <funcdef>text <function>UpdateGeometrySRID</function></funcdef>
1008
1009                        <paramdef><type>varchar </type>
1010                        <parameter>schema_name</parameter></paramdef>
1011
1012                        <paramdef><type>varchar </type>
1013                        <parameter>table_name</parameter></paramdef>
1014
1015                        <paramdef><type>varchar </type>
1016                        <parameter>column_name</parameter></paramdef>
1017
1018                        <paramdef><type>integer </type>
1019                        <parameter>srid</parameter></paramdef>
1020                  </funcprototype>
1021
1022                  <funcprototype>
1023                        <funcdef>text <function>UpdateGeometrySRID</function></funcdef>
1024
1025                        <paramdef><type>varchar </type>
1026                        <parameter>catalog_name</parameter></paramdef>
1027
1028                        <paramdef><type>varchar </type>
1029                        <parameter>schema_name</parameter></paramdef>
1030
1031                        <paramdef><type>varchar </type>
1032                        <parameter>table_name</parameter></paramdef>
1033
1034                        <paramdef><type>varchar </type>
1035                        <parameter>column_name</parameter></paramdef>
1036
1037                        <paramdef><type>integer </type>
1038                        <parameter>srid</parameter></paramdef>
1039                  </funcprototype>
1040                </funcsynopsis>
1041          </refsynopsisdiv>
1042
1043          <refsection>
1044                <title>Description</title>
1045
1046                <para>Updates the SRID of all features in a geometry column, updating
1047                constraints and reference in geometry_columns. Note: uses
1048                current_schema() on schema-aware pgsql installations if schema is not
1049                provided.</para>
1050                <para>&Z_support;</para>
1051                <para>&curve_support;</para>
1052          </refsection>
1053
1054          <refsection>
1055                <title>See Also</title>
1056
1057                <para><xref linkend="ST_SetSRID"/></para>
1058          </refsection>
1059        </refentry>
1060  </sect1>
Note: See TracBrowser for help on using the repository browser.