| Author | Simone Bizzotto (@niphold) |
| Availability | Windows, Linux, macOS |
Want to see the source code for this command? Check out Rename-DbaDatabase on GitHub.
Want to see the Bill Of Health for this command? Check out Rename-DbaDatabase.
Renames database names, filegroups, logical files, and physical files using customizable templates with placeholder support.
Systematically renames all database components using template-based naming conventions to enforce consistent standards across your SQL Server environment.
This function addresses the common challenge of standardizing database naming when inheriting inconsistent systems or implementing new naming policies.
The renaming process follows SQL Server's object hierarchy and executes in this order:
The function uses powerful template placeholders like
When naming conflicts occur, automatic counters are appended to ensure uniqueness.
If any step fails, the entire process stops to prevent partial renames that could leave your database in an inconsistent state.
Always backup your databases before using this function, and take a full backup of master after completion.
The function returns detailed objects showing all completed renames, with hidden properties providing human-readable summaries.
Store results in a variable for troubleshooting: "$result = Rename-DbaDatabase ....."
Use the -Preview parameter first to see exactly what changes would occur: "Rename-DbaDatabase .... -Preview | Select-Object *"
Rename-DbaDatabase -SqlInstance <DbaInstanceParameter[]>
[-SqlCredential <PSCredential>]
[-Database <Object[]>]
[-ExcludeDatabase <Object[]>]
[-AllDatabases]
[-DatabaseName <String>]
[-FileGroupName <String>]
[-LogicalName <String>]
[-FileName <String>]
[-ReplaceBefore]
[-Force]
[-Move]
[-SetOffline]
[-Preview]
[-EnableException]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Rename-DbaDatabase
[-SqlCredential <PSCredential>]
[-ExcludeDatabase <Object[]>]
[-AllDatabases]
[-DatabaseName <String>]
[-FileGroupName <String>]
[-LogicalName <String>]
[-FileName <String>]
[-ReplaceBefore]
[-Force]
[-Move]
[-SetOffline]
[-Preview]
-InputObject <Database[]>
[-EnableException]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName HR2 -Preview | Select-Object *
Shows the detailed result set you'll get renaming the HR database to HR2 without doing anything
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName HR2
Renames the HR database to HR2
PS C:\> Get-DbaDatabase -SqlInstance sqlserver2014a -Database HR | Rename-DbaDatabase -DatabaseName HR2
Same as before, but with a piped database (renames the HR database to HR2)
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName "dbatools_<DBN>"
Renames the HR database to dbatools_HR
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName "dbatools_<DBN>_<DATE>"
Renames the HR database to dbatools_HR_20170807 (if today is 07th Aug 2017)
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -FileGroupName "dbatools_<FGN>"
Renames every FileGroup within HR to "dbatools_[the original FileGroup name]"
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName "dbatools_<DBN>" -FileGroupName "<DBN>_<FGN>"
Renames the HR database to "dbatools_HR", then renames every FileGroup within to "dbatools_HR_[the original FileGroup name]"
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -FileGroupName "dbatools_<DBN>_<FGN>"
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName "dbatools_<DBN>"
Renames the HR database to "dbatools_HR", then renames every FileGroup within to "dbatools_HR_[the original FileGroup name]"
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName "dbatools_<DBN>" -FileName "<DBN>_<FGN>_<FNN>"
Renames the HR database to "dbatools_HR" and then all filenames as "dbatools_HR_[Name of the FileGroup]_[original_filename]"
The db stays online (watch out!). You can then proceed manually to move/copy files by hand, set the db offline and then online again to finish the rename process
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName "dbatools_<DBN>" -FileName "<DBN>_<FGN>_<FNN>" -SetOffline
Renames the HR database to "dbatools_HR" and then all filenames as "dbatools_HR_[Name of the FileGroup]_[original_filename]"
The db is then set offline (watch out!). You can then proceed manually to move/copy files by hand and then set it online again to finish the rename process
PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName "dbatools_<DBN>" -FileName "<DBN>_<FGN>_<FNN>" -Move
Renames the HR database to "dbatools_HR" and then all filenames as "dbatools_HR_[Name of the FileGroup]_[original_filename]"
The db is then set offline (watch out!). The function tries to do a simple rename and then sets the db online again to finish the rename process
Target any number of instances, in order to return their build state.
| Alias | |
| Required | True |
| Pipeline | false |
| Default Value |
Accepts database objects from the pipeline, typically from Get-DbaDatabase. Allows for advanced filtering and database selection before renaming.
Use this when you need complex database selection logic or when chaining database operations in a pipeline.
| Alias | |
| Required | True |
| Pipeline | true (ByValue) |
| Default Value |
Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
For MFA support, please use Connect-DbaInstance.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies which databases to include in the renaming operation. Accepts database names, wildcards, or arrays of database names.
Use this when you need to rename specific databases instead of all user databases on the instance.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies databases to exclude from the renaming operation. Accepts database names, wildcards, or arrays of database names.
Use this to protect specific databases when using -AllDatabases or when you want to process most databases except certain ones.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Applies the renaming operation to all user databases on the SQL Server instance. System databases are automatically excluded.
Use this switch when standardizing naming conventions across your entire instance rather than targeting specific databases.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Specifies a template for renaming database names using placeholder substitution. Creates new database names based on the template pattern.
Use this when you need to standardize database names according to organizational naming conventions. Common patterns include adding prefixes, suffixes, or date stamps.
Valid placeholders are:
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies a template for renaming filegroup names within databases using placeholder substitution. Note that the PRIMARY filegroup cannot be renamed due to SQL Server restrictions.
Use this when you need consistent filegroup naming across databases or when implementing data organization strategies that require specific filegroup names.
Valid placeholders are:
0002, etc).
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies a template for renaming the logical names of database files using placeholder substitution. Logical names are used internally by SQL Server to reference files.
Use this when you need consistent logical file naming for backup operations, maintenance scripts, or troubleshooting, as logical names are referenced in many SQL commands.
Valid placeholders are:
distinct names cannot be generated, a counter is appended (0001, 0002, etc).
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies a template for renaming physical database file names on disk using placeholder substitution. Changes only the file name, preserving the original directory and file extension.
Use this when you need to align physical file names with your database naming standards for easier file management, monitoring, and disaster recovery operations.
Valid placeholders are:
database name),
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Modifies how placeholder substitution works by removing old database, filegroup, and logical names from current names before applying templates. This prevents duplicate naming components in nested
scenarios.
Use this when your existing names already contain components that would be duplicated by the template placeholders, resulting in cleaner final names.
For example, with -ReplaceBefore, renaming database "HR_DB" to "PROD_HR" and using template "
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Terminates all active connections to target databases to allow renaming operations to proceed. Required when databases have active connections that would prevent rename operations.
Use this when you need to force database renames in production environments where applications may maintain persistent connections.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Automatically moves physical database files to match renamed file names. Sets the database offline, performs file operations, then brings the database back online.
Use this for a complete automated renaming solution when you want the function to handle all file operations. Requires PowerShell remoting access to the SQL Server's file system.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Forces the database offline after renaming operations to prepare for manual file moves. Terminates active connections and sets database state to offline.
Use this when you need to rename physical files but want to handle the file movement operations manually rather than having the function move them automatically.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Displays what renaming operations would be performed without executing any changes to the databases. Shows the complete rename plan including all affected components.
Use this first to verify your templates and parameters will produce the desired results before committing to actual database changes.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
| Alias | wi |
| Required | False |
| Pipeline | false |
| Default Value |
If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
| Alias | cf |
| Required | False |
| Pipeline | false |
| Default Value |