Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 9cf701f

Browse files
peterepetere
committed
Start adding some more documentation about the number types. Make
bigserial and alias for serial8 for consistency with bigint/int8.
1 parent e8cb935 commit 9cf701f

File tree

2 files changed

+213
-40
lines changed

2 files changed

+213
-40
lines changed

‎doc/src/sgml/datatype.sgml

Lines changed: 210 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.58 2001/08/16 20:38:53 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.59 2001/08/24 20:03:41 petere Exp $
33
-->
44

55
<chapter id="datatype">
@@ -53,6 +53,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.58 2001/08/16 20:38:53 tg
5353
<entry>signed eight-byte integer</entry>
5454
</row>
5555

56+
<row>
57+
<entry><type>bigserial</type></entry>
58+
<entry><type>serial8</type></entry>
59+
<entry>autoincrementing eight-byte integer</entry>
60+
</row>
61+
5662
<row>
5763
<entry><type>bit</type></entry>
5864
<entry></entry>
@@ -203,12 +209,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.58 2001/08/16 20:38:53 tg
203209
<entry>autoincrementing four-byte integer</entry>
204210
</row>
205211

206-
<row>
207-
<entry><type>serial8</type></entry>
208-
<entry></entry>
209-
<entry>autoincrementing eight-byte integer</entry>
210-
</row>
211-
212212
<row>
213213
<entry><type>text</type></entry>
214214
<entry></entry>
@@ -346,8 +346,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.58 2001/08/16 20:38:53 tg
346346
<tgroup cols="4">
347347
<thead>
348348
<row>
349-
<entry>Type Name</entry>
350-
<entry>Storage</entry>
349+
<entry>Type name</entry>
350+
<entry>Storage size</entry>
351351
<entry>Description</entry>
352352
<entry>Range</entry>
353353
</row>
@@ -370,46 +370,46 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.58 2001/08/16 20:38:53 tg
370370
<entry>bigint</entry>
371371
<entry>8 bytes</entry>
372372
<entry>Very large range fixed-precision</entry>
373-
<entry>about 18 decimal places</entry>
373+
<entry>about 18 decimal digits</entry>
374374
</row>
375375

376376
<row>
377377
<entry>decimal</entry>
378378
<entry>variable</entry>
379-
<entry>User-specified precision</entry>
379+
<entry>user-specified precision, exact</entry>
380380
<entry>no limit</entry>
381381
</row>
382382
<row>
383383
<entry>numeric</entry>
384384
<entry>variable</entry>
385-
<entry>User-specified precision</entry>
385+
<entry>user-specified precision, exact</entry>
386386
<entry>no limit</entry>
387387
</row>
388388

389389
<row>
390390
<entry>real</entry>
391391
<entry>4 bytes</entry>
392-
<entry>Variable-precision</entry>
393-
<entry>6 decimal places</entry>
392+
<entry>variable-precision, inexact</entry>
393+
<entry>6 decimal digits precision</entry>
394394
</row>
395395
<row>
396396
<entry>double precision</entry>
397397
<entry>8 bytes</entry>
398-
<entry>Variable-precision</entry>
399-
<entry>15 decimal places</entry>
398+
<entry>variable-precision, inexact</entry>
399+
<entry>15 decimal digits precision</entry>
400400
</row>
401401

402402
<row>
403-
<entry>serial4</entry>
403+
<entry>serial</entry>
404404
<entry>4 bytes</entry>
405-
<entry>Identifier or cross-reference</entry>
405+
<entry>autoincrementing integer</entry>
406406
<entry>1 to 2147483647</entry>
407407
</row>
408408

409409
<row>
410-
<entry>serial8</entry>
410+
<entry>bigserial</entry>
411411
<entry>8 bytes</entry>
412-
<entry>Identifier or cross-reference</entry>
412+
<entry>autoincrementing integer</entry>
413413
<entry>1 to 9223372036854775807</entry>
414414
</row>
415415
</tbody>
@@ -422,15 +422,187 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.58 2001/08/16 20:38:53 tg
422422
<xref linkend="sql-syntax-constants">. The numeric types have a
423423
full set of corresponding arithmetic operators and
424424
functions. Refer to <xref linkend="functions"> for more
425-
information.
425+
information. The following sections describe the types in detail.
426426
</para>
427427

428-
<para>
429-
The <type>bigint</type> type may not function correctly on all platforms,
430-
since it relies on compiler support for eight-byte integers. On a machine
431-
without such support, <type>bigint</type> acts the same
432-
as <type>integer</type> (but still takes up eight bytes of storage).
433-
</para>
428+
<sect2 id="datatype-int">
429+
<title>The Integer Types</title>
430+
431+
<para>
432+
The types <type>smallint</type>, <type>integer</type>,
433+
<type>bigint</type> store whole numbers, that is, numbers without
434+
fractional components, of various ranges. Attempts to store
435+
values outside of the allowed range will result in an error.
436+
</para>
437+
438+
<para>
439+
The type <type>integer</type> is the usual choice, as it offers
440+
the best balance between range, storage size, and performance.
441+
The <type>smallint</type> type is generally only used if disk
442+
space is at a premium. The <type>bigint</type> type should only
443+
be used if the <type>integer</type> range is not sufficient,
444+
because the latter is definitely faster.
445+
</para>
446+
447+
<para>
448+
The <type>bigint</type> type may not function correctly on all
449+
platforms, since it relies on compiler support for eight-byte
450+
integers. On a machine without such support, <type>bigint</type>
451+
acts the same as <type>integer</type> (but still takes up eight
452+
bytes of storage). However, we are not aware of any reasonable
453+
platform where this is actually the case.
454+
</para>
455+
456+
<note>
457+
<para>
458+
If you have a column of type <type>smallint</type> or
459+
<type>bigint</type> with an index, you may encounter problems
460+
getting the system to use that index. For instance, a clause of
461+
the form
462+
<programlisting>
463+
... WHERE smallint_column = 42
464+
</programlisting>
465+
will not use an index, because the system assigns type
466+
<type>integer</type> to the 42, and PostgreSQL currently cannot
467+
use an index when two different data types are involved. A
468+
workaround is to single-quote the constant, thus:
469+
<programlisting>
470+
... WHERE smallint_column = '42'
471+
</programlisting>
472+
This will cause the system to delay the type resolution and will
473+
assign the right type to the constant.
474+
</para>
475+
</note>
476+
477+
<para>
478+
SQL only specifies the integer types <type>integer</type> (or
479+
<type>int</type>) and <type>smallint</type>. The type
480+
<type>bigint</type>, and the type names <type>int2</type>,
481+
<type>int4</type>, and <type>int8</type> are extensions, which
482+
are shared with various other RDBMS products.
483+
</para>
484+
485+
</sect2>
486+
487+
<sect2 id="datatype-numeric-decimal">
488+
<title>Arbitrary Precision Numbers</title>
489+
490+
<para>
491+
The type <type>numeric</type> can store numbers of practically
492+
unlimited size and precision, while being able to store all
493+
numbers and carry out all calculations exactly. It is especially
494+
recommended for storing monetary amounts and other quantities
495+
where exactness is required. However, the <type>numeric</type>
496+
type is very slow compared to the floating point types described
497+
in the next section.
498+
</para>
499+
500+
<para>
501+
In what follows we use these terms: The
502+
<firstterm>scale</firstterm> of a <type>numeric</type> is the
503+
count of decimal digits in the fractional part, to the right of
504+
the decimal point. The <firstterm>precision</firstterm> of a
505+
<type>numeric</type> is the total count of significant digits in
506+
the whole number, that is, the number of digits to both sides of
507+
the decimal point. So the number 23.5141 has a precision of 6
508+
and a scale of 4. Integers can be considered to have a scale of
509+
zero.
510+
</para>
511+
512+
<para>
513+
Both the precision and the scale of the numeric type can be
514+
configured. To declare a column of type <type>numeric</type> use
515+
the syntax
516+
<programlisting>
517+
NUMERIC(<replaceable>precision</replaceable>, <replaceable>scale</replaceable>)
518+
</programlisting>
519+
The precision must be positive, the scale zero or positive.
520+
Alternatively,
521+
<programlisting>
522+
NUMERIC(<replaceable>precision</replaceable>)
523+
</programlisting>
524+
selects a scale of 0. Merely specifying
525+
<programlisting>
526+
NUMERIC
527+
</programlisting>
528+
uses a default precision and scale, which is currently (30,6).
529+
(The SQL standard requires a default scale of 0. We find this a
530+
bit useless. If you're concerned about portability, always
531+
specify the precision and scale explicitly.)
532+
</para>
533+
534+
<para>
535+
If the precision or scale of a value is greater than the declared
536+
precision or scale of a column, the system will attempt to round
537+
the value. If the value cannot be rounded so as to satisfy the
538+
declared limits, an error is raised.
539+
</para>
540+
541+
<para>
542+
The types <type>decimal</type> and <type>numeric</type> are
543+
equivalent. Both types are part of the SQL standard.
544+
</para>
545+
</sect2>
546+
547+
548+
<sect2 id="datatype-float">
549+
<title>Floating Point Types</title>
550+
551+
<para>
552+
The data types <type>real</type> and <type>double
553+
precision</type> are inexact, variable precision numeric types.
554+
In practice, these types are usually implementations of IEEE 754
555+
binary floating point (single and double precision,
556+
respectively), to the extent that the underlying processor,
557+
operating system, and compiler support it.
558+
</para>
559+
560+
<para>
561+
Inexact means that some values cannot be converted exactly to the
562+
internal format and are stored as approximations, so that storing
563+
and printing back out a value may show slight discrepancies.
564+
Managing these errors and how they propagate through calculations
565+
is the subject of an entire branch of mathematics and computer
566+
science and will not be discussed further here, except for the
567+
following points:
568+
<itemizedlist>
569+
<listitem>
570+
<para>
571+
If you require exact storage and calculations (such as for
572+
monetary amounts), use the <type>numeric</type> type instead.
573+
</para>
574+
</listitem>
575+
576+
<listitem>
577+
<para>
578+
If you want to do complicated calculations with these types
579+
for anything important, especially if you rely on certain
580+
behavior in boundary cases (infinity, underflow), you should
581+
evaluate the implementation carefully.
582+
</para>
583+
</listitem>
584+
585+
<listitem>
586+
<para>
587+
Comparing two floating point values for equality may or may
588+
not work as expected.
589+
</para>
590+
</listitem>
591+
</itemizedlist>
592+
</para>
593+
594+
<para>
595+
Normally, the <type>real</type> type has a range of at least
596+
-1E+37 to +1E+37 with a precision of at least 6. The
597+
<type>double precision</type> type normally has a range of around
598+
-1E+308 to +1E+308 with a precision of at least 15. Values that
599+
are too large or too small will cause an error. Rounding may
600+
take place if the precision of an input number is too high.
601+
Numbers too close to zero that are not representable as distinct
602+
from zero will cause an underflow error.
603+
</para>
604+
605+
</sect2>
434606

435607
<sect2 id="datatype-serial">
436608
<title>The Serial Types</title>
@@ -463,17 +635,17 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.58 2001/08/16 20:38:53 tg
463635
in tables.
464636
In the current implementation, specifying
465637

466-
<programlisting>
638+
<programlisting>
467639
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
468-
</programlisting>
640+
</programlisting>
469641

470642
is equivalent to specifying:
471643

472-
<programlisting>
644+
<programlisting>
473645
CREATE SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq;
474646
CREATE TABLE <replaceable class="parameter">tablename</replaceable>
475-
(<replaceable class="parameter">colname</replaceable> integer DEFAULT nextval('<replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq') UNIQUE NOT NULL;
476-
</programlisting>
647+
(<replaceable class="parameter">colname</replaceable> integer DEFAULT nextval('<replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq') UNIQUE NOT NULL);
648+
</programlisting>
477649

478650
Thus, we have created an integer column and arranged for its default
479651
values to be assigned from a sequence generator. UNIQUE and NOT NULL
@@ -492,22 +664,22 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable>
492664
<para>
493665
The type names <type>serial</type> and <type>serial4</type> are
494666
equivalent: both create <type>integer</type> columns. The type
495-
name <type>serial8</type> works just the same way, except that it
496-
creates a <type>bigint</type> column. <type>serial8</type> should
497-
be used if you anticipate use of more than 2^31 identifiers over
498-
the lifetime of the table.
667+
names <type>bigserial</type> and <type>serial8</type> works just
668+
the same way, except that it creates a <type>bigint</type>
669+
column. <type>serial8</type> should be used if you anticipate
670+
use of more than 2^31 identifiers over the lifetime of the table.
499671
</para>
500672

501673
<para>
502674
Implicit sequences supporting the <type>serial</type> are
503675
not automatically dropped when a table containing a serial type
504676
is dropped. So, the following commands executed in order will likely fail:
505677

506-
<programlisting>
678+
<programlisting>
507679
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
508680
DROP TABLE <replaceable class="parameter">tablename</replaceable>;
509681
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
510-
</programlisting>
682+
</programlisting>
511683

512684
The sequence will remain in the database until explicitly dropped using
513685
<command>DROP SEQUENCE</command>.

‎src/backend/parser/analyze.c

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
* Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
77
* Portions Copyright (c) 1994, Regents of the University of California
88
*
9-
* $Header: /cvsroot/pgsql/src/backend/parser/analyze.c,v 1.196 2001/08/21 16:36:03 tgl Exp $
9+
* $Header: /cvsroot/pgsql/src/backend/parser/analyze.c,v 1.197 2001/08/24 20:03:45 petere Exp $
1010
*
1111
*-------------------------------------------------------------------------
1212
*/
@@ -732,7 +732,8 @@ transformCreateStmt(ParseState *pstate, CreateStmt *stmt)
732732
is_serial = true;
733733
column->typename->name = pstrdup("int4");
734734
}
735-
else if (strcmp(column->typename->name, "serial8") == 0)
735+
else if (strcmp(column->typename->name, "bigserial") == 0 ||
736+
strcmp(column->typename->name, "serial8") == 0)
736737
{
737738
is_serial = true;
738739
column->typename->name = pstrdup("int8");

0 commit comments

Comments
 (0)