PostgreSQL 9.1.0 Documentation
Prev | Fast Backward |  | Fast Forward | Next

# ALTER FOREIGN TABLE

## Name

ALTER FOREIGN TABLE -- change the definition of a foreign table

## Synopsis

    ALTER FOREIGN TABLE name
        action [, ... ]
    ALTER FOREIGN TABLE name
        RENAME [ COLUMN ] column TO new_column
    ALTER FOREIGN TABLE name
        RENAME TO new_name
    ALTER FOREIGN TABLE name
        SET SCHEMA new_schema

    where action is one of:

        ADD [ COLUMN ] column type [ NULL | NOT NULL ]
        DROP [ COLUMN ] [ IF EXISTS ] column [ RESTRICT | CASCADE ]
        ALTER [ COLUMN ] column [ SET DATA ] TYPE type
        ALTER [ COLUMN ] column { SET | DROP } NOT NULL
        OWNER TO new_owner
        OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ])

## Description

`ALTER FOREIGN TABLE` changes the definition of an existing foreign table. There are several subforms:

`ADD COLUMN`

  This form adds a new column to the foreign table, using the same syntax as CREATE FOREIGN TABLE.

`DROP COLUMN [ IF EXISTS ]`

  This form drops a column from a foreign table. You will need to say `CASCADE` if anything outside the table depends on the column; for example, views. If `IF EXISTS` is specified and the column does not exist, no error is thrown. In this case a notice is issued instead.

`SET DATA TYPE`

  This form changes the type of a column of a foreign table.

`SET`/`DROP NOT NULL`

  Mark a column as allowing, or not allowing, null values.

`OWNER`

  This form changes the owner of the foreign table to the specified user.

`RENAME`

  The `RENAME` forms change the name of a foreign table or the name of an individual column in a foreign table.

`SET SCHEMA`

  This form moves the foreign table into another schema.

`OPTIONS ( [ ADD | SET | DROP ] `option` ['`value`'] [, ... ] )`

  Change options for the foreign table. `ADD`, `SET`, and `DROP` specify the action to be performed. `ADD` is assumed if no operation is explicitly specified. Option names must be unique; names and values are also validated using the foreign data wrapper library.

All the actions except `RENAME` and `SET SCHEMA` can be combined into a list of multiple alterations to apply in parallel. For example, it is possible to add several columns and/or alter the type of several columns in a single command.

You must own the table to use `ALTER FOREIGN TABLE`. To change the schema of a foreign table, you must also have `CREATE` privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have `CREATE` privilege on the table's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the table. However, a superuser can alter ownership of any table anyway.)

## Parameters

`name`

  The name (possibly schema-qualified) of an existing foreign table to alter.

`column`

  Name of a new or existing column.

`new_column`

  New name for an existing column.

`new_name`

  New name for the table.

`type`

  Data type of the new column, or new data type for an existing column.

`CASCADE`

  Automatically drop objects that depend on the dropped column (for example, views referencing the column).

`RESTRICT`

  Refuse to drop the column if there are any dependent objects. This is the default behavior.

`new_owner`

  The user name of the new owner of the table.

`new_schema`

  The name of the schema to which the table will be moved.

## Notes

The key word `COLUMN` is noise and can be omitted.

Consistency with the foreign server is not checked when a column is added or removed with `ADD COLUMN` or `DROP COLUMN`, a `NOT NULL` constraint is added, or a column type is changed with `SET DATA TYPE`. It is the user's responsibility to ensure that the table definition matches the remote side.

Refer to CREATE FOREIGN TABLE for a further description of valid parameters.

## Examples

To mark a column as not-null:

    ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL;

To change options of a foreign table:

    ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2, 'value2', DROP opt3 'value3');

## Compatibility

The forms `ADD`, `DROP`, and `SET DATA TYPE` conform with the SQL standard. The other forms are PostgreSQL extensions of the SQL standard. Also, the ability to specify more than one manipulation in a single `ALTER FOREIGN TABLE` command is an extension.

`ALTER FOREIGN TABLE DROP COLUMN` can be used to drop the only column of a foreign table, leaving a zero-column table. This is an extension of SQL, which disallows zero-column foreign tables.

Prev | Home | Next
ALTER FOREIGN DATA WRAPPER | Up | ALTER FUNCTION