ALTER TABLE – SQL Command

  • Article

Programmatically modifies the structure of a table.

ALTER TABLE TableName1 ADD | ALTER [COLUMN] FieldName1 FieldType 
   [(nFieldWidth [, nPrecision])] [NULL | NOT NULL]
   [CHECK lExpression1 [ERROR cMessageText1]] [DEFAULT eExpression1] 
   [PRIMARY KEY | UNIQUE] [REFERENCES TableName2 [TAG TagName1]]
   [NOCPTRANS] [NOVALIDATE]

-or-

ALTER TABLE TableName1 ALTER [COLUMN] FieldName2 [NULL | NOT NULL]
[SET DEFAULT eExpression2] [SET CHECK lExpression2 [ERROR cMessageText2]]
[DROP DEFAULT] [DROP CHECK] [NOVALIDATE]

-or-

ALTER TABLE TableName1 [DROP [COLUMN] FieldName3] 
   [SET CHECK lExpression3[ERRORcMessageText3]] [DROP CHECK] 
   [ADD PRIMARY KEY eExpression3 [FOR lExpression4] TAG TagName2] 
   [DROP PRIMARY KEY] 
   [ADD UNIQUE eExpression4 [[FOR lExpression5] TAG TagName3]]
   [DROP UNIQUE TAG TagName4] [ADD FOREIGN KEY [eExpression5] 
      [FOR lExpression6] TAG TagName4 REFERENCES TableName2 
      [TAG TagName5]]
   [DROP FOREIGN KEY TAG TagName6 [SAVE]]
   [RENAME COLUMN FieldName4 TO FieldName5] [NOVALIDATE]

Parameters

  • TableName1
    Specifies the name of the table whose structure is modified.

  • ADD [COLUMN] FieldName1
    Specifies the name of the field to add. A single table can contain up to 255 fields. If one or more fields allow null values, the limit is reduced by one to 254 fields.

  • ALTER [COLUMN] FieldName1
    Specifies the name of an existing field to modify.

  • FieldType [(nFieldWidth [, nPrecision])]
    Specifies the field type, field width, and field precision (number of decimal places) for a new or modified field.

    FieldType is a single letter indicating the field's data type. Some field data types require that you specify nFieldWidth or nPrecision or both.

    The following table lists the values for FieldType and indicates whether nFieldWidth and nPrecision are required:

    FieldType nFieldWidth nPrecision Description
    C N – Character field of width n
    D – – Date
    T – – DateTime
    N N D Numeric field of width n with d decimal places
    F N D Floating numeric field of width n with d decimal places
    I – – Integer
    B – D Double
    Y – – Currency
    L – – Logical
    M – – Memo
    G – – General
    P – – Picture

    nFieldWidth and nPrecision are ignored for D, T, I, Y, L, M, G, and P types. nPrecision defaults to zero (no decimal places) if nPrecision isn't included for the N, F, or B types.

  • NULL | NOT NULL
    Allows or precludes null values in the field. If one or more fields can contain null values, the maximum number of fields the table can contain is reduced by one, from 255 to 254.

    If you omit NULL and NOT NULL, the current setting of SET NULL determines whether null values are allowed in the field. However, if you omit NULL and NOT NULL and include the PRIMARY KEY or UNIQUE clause, the current setting of SET NULL is ignored and the field defaults to NOT NULL.

  • CHECK lExpression1
    Specifies a validation rule for the field. lExpression1 must evaluate to a logical expression; it can be a user-defined function or a stored procedure. When a blank record is appended, the validation rule is checked. An error is generated if the validation rule doesn't allow for a blank field value in an appended record.

  • ERROR cMessageText1
    Specifies the error message displayed when the field validation rule generates an error. The message is displayed only when data is changed within a Browse or Edit window.

  • DEFAULT eExpression1
    Specifies a default value for the field. The data type of eExpression1 must be the same as the data type for the field.

  • PRIMARY KEY
    Creates a primary index tag. The index tag has the same name as the field.

  • UNIQUE
    Creates a candidate index tag with the same name as the field.

    For more information about candidate indexes, see Working with Tables.

    Note   Candidate indexes (created by including the UNIQUE option, provided for ANSI compatibility in ALTER TABLE or CREATE TABLE) are not the same as indexes created with the UNIQUE option in the INDEX command. An index created with UNIQUE in the INDEX command allows duplicate index keys; candidate indexes do not allow duplicate index keys.

    Null values and duplicate records are not permitted in a field used for a primary or candidate index.

    If you are creating a new field with ADD COLUMN, Microsoft Visual FoxPro will not generate an error if you create a primary or candidate index for a field that supports null values. However, Visual FoxPro will generate an error if you attempt to enter a null or duplicate value into a field used for a primary or candidate index.

    If you are modifying an existing field and the primary or candidate index expression consists of fields in the table, Visual FoxPro checks the fields to see if they contain null values or duplicate records. If they do, Visual FoxPro generates an error and the table is not altered.

  • REFERENCES TableName2 TAG TagName1
    Specifies the parent table to which a persistent relationship is established. TAG TagName1 specifies the parent table's index tag on which the relationship is based. Index tag names can contain up to 10 characters.

  • NOCPTRANS
    Prevents translation to a different code page for character and memo fields. If the table is converted to another code page, the fields for which NOCPTRANS has been specified are not translated. NOCPTRANS can only be specified for character and memo fields.

    The following example creates a table named MYTABLE containing two character fields and two memo fields. The second character field char2 and the second memo field memo2 include NOCPTRANS to prevent translation.

    CREATE TABLE mytable (char1 C(10), char2 C(10) NOCPTRANS,;
   memo1 M, memo2 M NOCPTRANS)

  • ALTER [COLUMN] FieldName2
    Specifies the name of an existing field to modify. Note that multiple ALTER COLUMN clauses are required to change more than one property of a field in a single ALTER TABLE command. See the ALTER TABLE examples to see how the ALTER COLUMN clauses are structured.

  • SET DEFAULT eExpression2
    Specifies a new default value for an existing field. The data type of eExpression2 must be the same as the data type for the field.

  • SET CHECK lExpression2
    Specifies a new validation rule for an existing field. lExpression2 must evaluate to a logical expression, and may be a user-defined function or a stored procedure.

  • ERROR cMessageText2
    Specifies the error message displayed when the field validation rule generates an error. The message is displayed only when data is changed within a Browse or Edit window.

  • DROP DEFAULT
    Removes the default value for an existing field.

  • DROP CHECK
    Removes the validation rule for an existing field.

  • DROP [COLUMN] FieldName3
    Specifies a field to remove from the table. Removing a field from the table also removes the field's default value setting and field validation rule.

    If index key or trigger expressions reference the field, the expressions become invalid when the field is removed. In this case, an error isn't generated when the field is removed, but the invalid index key or trigger expressions will generate errors at run time.

  • SET CHECK lExpression3
    Specifies the table validation rule. lExpression3 must evaluate to a logical expression; it can be a user-defined function or a stored procedure.

  • ERROR cMessageText3
    Specifies the error message displayed when the table validation rule generates an error. The message is displayed only when data is changed within a Browse or Edit window.

  • DROP CHECK
    Removes the table's validation rule.

  • ADD PRIMARY KEY eExpression3 [FOR lExpression4] TAG TagName2
    Adds a primary index to the table. eExpression3 specifies the primary index key expression; TagName2 specifies the name of the primary index tag. Index tag names can contain up to 10 characters. If TAG TagName2 is omitted and eExpression3 is a single field, the primary index tag has the same name as the field specified in eExpression3.

    Include FOR lExpression4 to specify a condition whereby only records that satisfy the filter expression lExpression4 are available for display and access; primary index keys are created in the index file for just those records matching the filter expression. Note that you should avoid using the FOR clause to create a primary index; the uniqueness of a primary key is only enforced for those records that match the condition specified with FOR lExpression4. Instead, use the INDEX command with a FOR clause to create a filtered index.

    Rushmore optimizes an ALTER TABLE ... FOR lExpression4 command if lExpression4 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause.

    For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

  • DROP PRIMARY KEY
    Removes the primary index and its index tag. Because a table can have only one primary key, it isn't necessary to specify the name of the primary key. Removing the primary index also deletes any persistent relations based on the primary key.

  • ADD UNIQUE eExpression4 [TAG TagName3 [FOR lExpression5]]
    Adds a candidate index to the table. eExpression4 specifies the candidate index key expression; TagName3 specifies the name of the candidate index tag. Index tag names can contain up to 10 characters. If you omit TAG TagName3, and if eExpression4 is a single field, the candidate index tag has the same name as the field specified in eExpression4.

    Include FOR lExpression5 to specify a condition whereby only records that satisfy the filter expression lExpression5 are available for display and access; candidate index keys are created in the index file for just those records matching the filter expression.

    Rushmore optimizes an ALTER TABLE ... FOR lExpression5 command if lExpression5 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause.

    For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

  • DROP UNIQUE TAG TagName4
    Removes the candidate index and its index tag. Because a table can have multiple candidate keys, you must specify the name of the candidate index tag.

  • ADD FOREIGN KEY [eExpression5] TAG TagName4 [FOR lExpression6]
    Adds a foreign (non-primary) index to the table. eExpression5 specifies the foreign index key expression and TagName4 specifies the name of the foreign index tag. Index tag names can contain up to 10 characters.

    Include FOR lExpression6 to specify a condition whereby only records that satisfy the filter expression lExpression6 are available for display and access; foreign index keys are created in the index file for just those records matching the filter expression.

    Rushmore optimizes an ALTER TABLE ... FOR lExpression6 command if lExpression6 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause.

    For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

  • REFERENCES TableName2 [TAG TagName5]
    Specifies the parent table to which a persistent relationship is established. Include TAG TagName5 to establish a relationship based on an existing index tag for the parent table. Index tag names can contain up to 10 characters. If you omit TAG TagName5, the relationship is established using the parent table's primary index tag.

  • DROP FOREIGN KEY TAG TagName6 [SAVE]
    Deletes a foreign key whose index tag is TagName6. If you omit SAVE, the index tag is deleted from the structural index. Include SAVE to prevent the index tag from being deleted from the structural index.

  • RENAME COLUMN FieldName4 TO FieldName5
    Makes it possible for you to change the name of a field in the table. FieldName4 specifies the name of the field that is renamed. FieldName5 specifies the new name of the field.

    Caution   Exercise care when renaming table fields — index expressions, field and table validation rules, commands, functions, and so on may reference the original field names.

  • NOVALIDATE
    Specifies that Visual FoxPro allows changes to be made to the structure of the table that may violate the integrity of the data in the table. By default, Visual FoxPro prevents ALTER TABLE from making changes to the structure of the table that violate the integrity of the data in the table. Include NOVALIDATE to override this default behavior.

Remarks

ALTER TABLE can be used to modify the structure of a table that has not been added to a database. However, Visual FoxPro generates an error if you include the DEFAULT, FOREIGN KEY, PRIMARY KEY, REFERENCES, or SET clauses when modifying a free table.

ALTER TABLE may rebuild the table by creating a new table header and appending records to the table header. For example, changing a field's type or width may cause the table to be rebuilt.

After a table is rebuilt, field validation rules are executed for any fields whose type or width is changed. If you change the type or width of any field in the table, the table rule is executed.

If you modify field or table validation rules for a table that has records, Visual FoxPro tests the new field or table validation rules against the existing data and issues a warning on the first occurrence of a field or table validation rule or of a trigger violation.

ALTER TABLE may not produce consistent results when used with Visual FoxPro cursors created using the CREATE CURSOR command. In particular, you can create a Visual FoxPro cursor with features (long field names, for example) that would normally be available only with tables that are part of a database container. Because ALTER TABLE saves a temporary copy of the cursor, the rules that apply to free-tables then apply, and any features requiring database support are lost or changed in an unpredictable manner. Therefore, as a general rule, you should avoid using ALTER TABLE with Visual FoxPro cursors unless you have tested and understood the outcome.

Example

Example 1 adds a field called fax to the customer table and allows the field to have null values.

Example 2 makes the cust_id field the primary key of the customer table.

Example 3 adds a field validation rule to the quantity field of the orders table so that values in the quantity field must be non-negative.

Example 4 adds a one-to-many persistent relation between the customer and orders tables based on the primary key cust_id in the customer table and a new foreign key index cust_id in the orders table.

Example 5 removes the field validation rule from the quantity field in the orders table.

Example 6 removes the persistent relation between the customer and orders tables, but keeps the cust_id index tag in the orders table.

Example 7 adds a field called fax2 to the customer table and prevents the field from containing null values. The new structure of the table is displayed. Two ALTER COLUMN clauses are used to allow the field to have null values and set the default value for the field to the null value. Note that multiple ALTER COLUMN clauses are required to change more than one property of a field in a single ALTER TABLE command. The new field is then removed from the table to restore the table to its original state.

* Example 1
SET PATH TO (HOME(2) + 'Data\')     && Sets path to table
ALTER TABLE customer ADD COLUMN fax c(20) NULL

* Example 2
ALTER TABLE customer ADD PRIMARY KEY cust_id TAG cust_id

ALTER TABLE customer ALTER COLUMN cust_id c(5) PRIMARY KEY

* Example 3
ALTER TABLE orders;
    ALTER COLUMN quantity SET CHECK quantity >= 0;
    ERROR "Quantities must be non-negative"

* Example 4
ALTER TABLE orders;
   ADD FOREIGN KEY cust_id TAG cust_id REFERENCES customer

* Example 5
ALTER TABLE orders ALTER COLUMN quantity DROP CHECK

* Example 6
ALTER TABLE orders DROP FOREIGN KEY TAG cust_id SAVE

* Example 7
CLEAR
ALTER TABLE customer ADD COLUMN fax2 c(20) NOT NULL
DISPLAY STRUCTURE

ALTER TABLE customer;
   ALTER COLUMN fax2 NULL;
   ALTER COLUMN fax2 SET DEFAULT .NULL.

ALTER TABLE customer DROP COLUMN fax2

See Also

CREATE TABLE - SQL | INDEX | MODIFY STRUCTURE | OPEN DATABASE | SET OPTIMIZE | Using Rushmore to Speed Data Access