PostgreSQL 9.3.2 Documentation
Prev | Up |  | Next

# ALTER FOREIGN TABLE

## Name

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

## Synopsis

    ALTER FOREIGN TABLE [ IF EXISTS ] name
        action [, ... ]
    ALTER FOREIGN TABLE [ IF EXISTS ] name
        RENAME [ COLUMN ] column_name TO new_column_name
    ALTER FOREIGN TABLE [ IF EXISTS ] name
        RENAME TO new_name
    ALTER FOREIGN TABLE [ IF EXISTS ] name
        SET SCHEMA new_schema

    where action is one of:

        ADD [ COLUMN ] column_name data_type [ COLLATE collation ] [ column_constraint [ ... ] ]
        DROP [ COLUMN ] [ IF EXISTS ] column_name [ RESTRICT | CASCADE ]
        ALTER [ COLUMN ] column_name [ SET DATA ] TYPE data_type
        ALTER [ COLUMN ] column_name SET DEFAULT expression
        ALTER [ COLUMN ] column_name DROP DEFAULT
        ALTER [ COLUMN ] column_name { SET | DROP } NOT NULL
        ALTER [ COLUMN ] column_name SET STATISTICS integer
        ALTER [ COLUMN ] column_name SET ( attribute_option = value [, ... ] )
        ALTER [ COLUMN ] column_name RESET ( attribute_option [, ... ] )
        ALTER [ COLUMN ] column_name OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ])
        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. Unlike the case when adding a column to a regular table, nothing happens to the underlying storage: this action simply declares that some new column is now accessible through the 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.

`IF EXISTS`

  Do not throw an error if the foreign table does not exist. A notice is issued in this case.

`SET DATA TYPE`

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

`SET`/`DROP DEFAULT`

  These forms set or remove the default value for a column. Default values only apply in subsequent `INSERT` or `UPDATE` commands; they do not cause rows already in the table to change.

`SET`/`DROP NOT NULL`

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

`SET STATISTICS`

  This form sets the per-column statistics-gathering target for subsequent ANALYZE operations. See the similar form of ALTER TABLE for more details.

`SET ( `attribute_option` = `value` [, ... ] )`
`RESET ( `attribute_option` [, ... ] )`

  This form sets or resets per-attribute options. See the similar form of ALTER TABLE for more details.

`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 or one of its columns. `ADD`, `SET`, and `DROP` specify the action to be performed. `ADD` is assumed if no operation is explicitly specified. Duplicate option names are not allowed (although it's OK for a table option and a column option to have the same name). Option 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.) To add a column or alter a column type, you must also have `USAGE` privilege on the data type.

## Parameters

`name`

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

`column_name`

  Name of a new or existing column.

`new_column_name`

  New name for an existing column.

`new_name`

  New name for the table.

`data_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