The RENAME TO
statement is part of ALTER DATABASE
, and changes the name of a database.
Synopsis
Required privileges
Only members of the admin
role can rename databases. By default, the root
user belongs to the admin
role.
Parameters
Parameter | Description |
---|---|
name |
The first instance of name is the current name of the database. The second instance is the new name for the database. The new name must be unique and follow these identifier rules. You cannot rename a database if it is set as the current database or if sql_safe_updates = true . |
Limitations
If an ALTER DATABASE ... RENAME
statement is issued on a single gateway node and a successful result is returned, it is possible to observe the old database names in transactions on other gateway nodes for a short amount of time after the rename is executed. This issue is specific to databases, which have their metadata stored in an incoherent cache, unlike tables. Note that this issue is resolved in v20.2.
Additionally, it is not possible to rename a database if:
- The database is referenced by a view. For more details, see View Dependencies.
The database is explicitly specified in a reference to a sequence. In this case, you can drop the column in the table that references the sequence, or you can modify the reference so that it does not specify the database name.
For example, suppose you create a database
db
, and in that database, a sequenceseq
:> CREATE DATABASE db; USE db; CREATE SEQUENCE seq;
Then you reference the sequence in a table
tab
:> CREATE TABLE tab ( id UUID DEFAULT gen_random_uuid(), count INT DEFAULT nextval('db.seq') );
Attempting to rename the database will result in an error:
> SET sql_safe_updates=false; ALTER DATABASE db RENAME TO mydb;
ERROR: cannot rename database because relation "db.public.tab" depends on relation "db.public.seq" SQLSTATE: 2BP01 HINT: you can drop the column default "count" of "db.public.seq" referencing "db.public.tab" or modify the default to not reference the database name "db"
In order to rename the database
db
, you need to drop or change the reference in the default value for theseq
column to not explicitly name the databasedb
:> ALTER TABLE tab ALTER COLUMN count SET DEFAULT nextval('seq');
> USE defaultdb; ALTER DATABASE db RENAME TO mydb;
Examples
Rename a database
> CREATE DATABASE db1;
> SHOW DATABASES;
database_name
-----------------
db1
defaultdb
movr
postgres
system
(5 rows)
> ALTER DATABASE db1 RENAME TO db2;
> SHOW DATABASES;
database_name
-----------------
db2
defaultdb
movr
postgres
system
(5 rows)
Rename fails (new name already in use)
> ALTER DATABASE db2 RENAME TO movr;
ERROR: the new database name "movr" already exists
SQLSTATE: 42P04