Rename-DbaDatabase

Synopsis

Renames database names, filegroups, logical files, and physical files using customizable templates with placeholder support.

Description

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:

• Database name is changed (optionally forcing users out)
• Filegroup names are changed accordingly
• Logical file names are changed accordingly
• Physical file names are changed accordingly
• If Move is specified, the database goes offline for file operations, then back online
• If Move is not specified, the database remains online (unless SetOffline), and you handle file moves manually

The function uses powerful template placeholders like for database name, for filegroup name, for current date, and for file type.
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 *”

Syntax

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>]

Examples

Example: 1

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

Example: 2

PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName HR2

Renames the HR database to HR2

Example: 3

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)

Example: 4

PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -DatabaseName "dbatools_<DBN>"

Renames the HR database to dbatools_HR

Example: 5

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)

Example: 6

PS C:\> Rename-DbaDatabase -SqlInstance sqlserver2014a -Database HR -FileGroupName "dbatools_<FGN>"

Renames every FileGroup within HR to “dbatools_[the original FileGroup name]"

Example: 7

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]"

Example: 8

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]"

Example: 9

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

Example: 10

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

Example: 11

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

Required Parameters

-SqlInstance

Target any number of instances, in order to return their build state.

-InputObject

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.

Optional Parameters

-SqlCredential

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.

-Database

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.

-ExcludeDatabase

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.

-AllDatabases

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.

-DatabaseName

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: (current database name), (current date in yyyyMMdd format).

-FileGroupName

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: (current filegroup name), (current database name), (current date in yyyyMMdd format). If distinct names cannot be generated, a counter is appended (0001,
0002, etc).

-LogicalName

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: (file type: ROWS, LOG, MMO, FS), (current logical name), (current filegroup name), (current database name), (current date in yyyyMMdd format). If
distinct names cannot be generated, a counter is appended (0001, 0002, etc).

-FileName

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: (current file name without directory or extension), (file type: ROWS, LOG, MMO, FS), (current logical name), (current filegroup name), (current
database name), (current date in yyyyMMdd format). If distinct names cannot be generated, a counter is appended (0001, 0002, etc).

-ReplaceBefore

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 “_Data” results in “PROD_HR_Data” instead of “PROD_HR_HR_DB_Data”.

-Force

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.

-Move

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.

-SetOffline

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.

-Preview

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.

-EnableException

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.

-WhatIf

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.

-Confirm

If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.