commands

^

Set-DbaAgentSchedule

Author Sander Stad (@sqlstad, sqlstad.nl)
Availability Windows, Linux, macOS

 

Want to see the source code for this command? Check out Set-DbaAgentSchedule on GitHub.
Want to see the Bill Of Health for this command? Check out Set-DbaAgentSchedule.

Synopsis

Modifies properties of existing SQL Agent job schedules

Description

Modifies the timing, frequency, and other properties of existing SQL Agent job schedules without recreating them. You can update schedule frequency (daily, weekly, monthly), change start/end times and dates, enable or disable schedules, and rename them. The function works with schedules already attached to jobs and validates all timing parameters to prevent invalid configurations.

Syntax

Set-DbaAgentSchedule
    [-SqlInstance] <DbaInstanceParameter[]>
    [[-SqlCredential] <PSCredential>]
    [-Job] <Object[]>
    [-ScheduleName] <String>
    [[-NewName] <String>]
    [-Enabled]
    [-Disabled]
    [[-FrequencyType] <Object>]
    [[-FrequencyInterval] <Object[]>]
    [[-FrequencySubdayType] <Object>]
    [[-FrequencySubdayInterval] <Int32>]
    [[-FrequencyRelativeInterval] <Object>]
    [[-FrequencyRecurrenceFactor] <Int32>]
    [[-StartDate] <String>]
    [[-EndDate] <String>]
    [[-StartTime] <String>]
    [[-EndTime] <String>]
    [-EnableException]
    [-Force]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

 

Examples

 

Example: 1
PS C:\> Set-DbaAgentSchedule -SqlInstance sql1 -Job Job1 -ScheduleName daily -Enabled

Changes the schedule for Job1 with the name 'daily' to enabled

Example: 2
PS C:\> Set-DbaAgentSchedule -SqlInstance sql1 -Job Job1 -ScheduleName daily -NewName weekly -FrequencyType Weekly -FrequencyInterval Monday, Wednesday, Friday

Changes the schedule for Job1 with the name daily to have a new name weekly

Example: 3
PS C:\> Set-DbaAgentSchedule -SqlInstance sql1 -Job Job1, Job2, Job3 -ScheduleName daily -StartTime '230000'

Changes the start time of the schedule for Job1 to 11 PM for multiple jobs

Example: 4
PS C:\> Set-DbaAgentSchedule -SqlInstance sql1, sql2, sql3 -Job Job1 -ScheduleName daily -Enabled

Changes the schedule for Job1 with the name daily to enabled on multiple servers

Example: 5
PS C:\> sql1, sql2, sql3 | Set-DbaAgentSchedule -Job Job1 -ScheduleName daily -Enabled

Changes the schedule for Job1 with the name 'daily' to enabled on multiple servers using pipe line

Required Parameters

-SqlInstance

The target SQL Server instance or instances. You must have sysadmin access and server version must be SQL Server version 2000 or greater.

Alias
Required True
Pipeline true (ByValue)
Default Value
-Job

Specifies the name of the SQL Agent job that contains the schedule to modify. You can provide multiple job names to update schedules across different jobs.
Use this when you need to change schedule properties for specific jobs without affecting other jobs that might share the same schedule name.

Alias
Required True
Pipeline true (ByValue)
Default Value
-ScheduleName

Specifies the name of the existing schedule to modify within the specified job. Schedule names are case-sensitive.
Use this to target the specific schedule when a job has multiple schedules attached to it.

Alias
Required True
Pipeline true (ByValue)
Default Value

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.

Alias
Required False
Pipeline false
Default Value
-NewName

Renames the schedule to the specified new name. The new name must be unique within the job's schedules.
Use this when you need to rename schedules for better organization or to follow naming conventions.

Alias
Required False
Pipeline false
Default Value
-Enabled

Activates the schedule so the job will run according to its configured timing. This overrides any disabled state.
Use this to reactivate schedules that were previously disabled without changing their timing configuration.

Alias
Required False
Pipeline false
Default Value False
-Disabled

Deactivates the schedule so the job will not run, even if it meets the timing criteria. The schedule configuration remains unchanged.
Use this to temporarily stop jobs without deleting their schedules during maintenance windows or troubleshooting.

Alias
Required False
Pipeline false
Default Value False
-FrequencyType

Sets the overall pattern for when the job should execute. This is the primary schedule type that determines how often the job runs.
Use 'Daily' for jobs that run every day or every few days, 'Weekly' for jobs on specific weekdays, 'Monthly' for jobs on specific dates, 'MonthlyRelative' for jobs like "first Monday of the month",
'Once' for one-time execution, 'AgentStart' to run when SQL Agent starts, or 'OnIdle' when server is idle.
This parameter works with FrequencyInterval to create the complete schedule pattern.

Alias
Required False
Pipeline false
Default Value
Accepted Values Once,OneTime,Daily,Weekly,Monthly,MonthlyRelative,AgentStart,AutoStart,IdleComputer,OnIdle,1,4,8,16,32,64,128
-FrequencyInterval

Specifies which days or intervals the job should run based on the FrequencyType. The values depend on the schedule type you choose.
For 'Daily': Use a number (1-365) for every N days or 'EveryDay'. For 'Weekly': Use day names like Monday, Tuesday or shortcuts like 'Weekdays', 'Weekend'. For 'Monthly': Use day numbers 1-31. For
'MonthlyRelative': Use day names for "first Monday" type schedules.
This parameter works together with FrequencyType to define the exact timing pattern for your job schedule.

Alias
Required False
Pipeline false
Default Value
-FrequencySubdayType

Defines the unit of time for running jobs multiple times within a single day. This controls what the FrequencySubdayInterval value represents.
Use 'Once' for jobs that run only once per day, 'Hours' for jobs that repeat every few hours, 'Minutes' for jobs that run every few minutes, or 'Seconds' for very frequent execution.
This parameter is only relevant when you need jobs to execute more than once per day at regular intervals.

Alias
Required False
Pipeline false
Default Value
Accepted Values 1,Once,Time,2,Seconds,Second,4,Minutes,Minute,8,Hours,Hour
-FrequencySubdayInterval

Specifies how many units of the FrequencySubdayType to wait between job executions within a day. For example, 2 with 'Hours' means every 2 hours.
Use this to control the frequency of recurring jobs throughout the day, such as every 15 minutes for monitoring jobs or every 4 hours for maintenance tasks.
Valid ranges are 1-59 for seconds/minutes and 1-23 for hours.

Alias
Required False
Pipeline false
Default Value 0
-FrequencyRelativeInterval

Specifies which occurrence of the day within the month for MonthlyRelative schedules. Controls whether you want the first, second, third, fourth, or last occurrence.
Use this for schedules like "first Monday of every month" (First + Monday) or "last Friday of every month" (Last + Friday). Only applies when FrequencyType is 'MonthlyRelative'.
Common values are 'First', 'Second', 'Third', 'Fourth', or 'Last'.

Alias
Required False
Pipeline false
Default Value
Accepted Values Unused,First,Second,Third,Fourth,Last
-FrequencyRecurrenceFactor

Controls how often the schedule repeats by specifying the interval between occurrences. For weekly schedules, this is the number of weeks between runs; for monthly schedules, it's the number of
months.
Use this to create schedules like "every 2 weeks on Monday" (FrequencyRecurrenceFactor=2) or "every 3 months on the 15th" (FrequencyRecurrenceFactor=3). Only applies to Weekly, Monthly, and
MonthlyRelative frequency types.
Must be at least 1, and is commonly used for less frequent maintenance tasks or reports.

Alias
Required False
Pipeline false
Default Value 0
-StartDate

Sets the earliest date when the schedule becomes active and the job can start running. Must be in yyyyMMdd format (e.g., '20240315').
Use this to delay job execution until a future date or to replace an existing start date. The schedule will not run before this date even if other timing conditions are met.

Alias
Required False
Pipeline false
Default Value
-EndDate

Sets the last date when the schedule will be active and can execute the job. Must be in yyyyMMdd format and cannot be before StartDate.
Use this to automatically disable schedules after a specific date, useful for temporary jobs or time-limited maintenance tasks. After this date, the schedule remains but will not execute.

Alias
Required False
Pipeline false
Default Value
-StartTime

Sets the daily start time when the job can begin executing, using 24-hour format HHMMSS (e.g., '080000' for 8:00 AM, '143000' for 2:30 PM).
Use this to schedule jobs during specific maintenance windows or business hours. For jobs with subday frequency, this is when the recurring pattern starts each day.

Alias
Required False
Pipeline false
Default Value
-EndTime

Sets the daily end time when the job can no longer start executing, using 24-hour format HHMMSS (e.g., '180000' for 6:00 PM, '235959' for just before midnight).
Use this to prevent jobs from starting during peak business hours or to ensure long-running jobs complete before critical operations begin. For recurring jobs, this stops new executions but doesn't
kill running jobs.

Alias
Required False
Pipeline false
Default Value
-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.

Alias
Required False
Pipeline false
Default Value False
-Force

Bypasses some parameter validation errors by applying sensible defaults and removes any existing schedules with the same name before creating new ones.
Use this when you want to overwrite existing schedules or when working with edge cases where strict validation might prevent legitimate schedule modifications.
Be cautious as this can remove existing schedules without prompting.

Alias
Required False
Pipeline false
Default Value False
-WhatIf

Shows what would happen if the command were to run. No actions are actually performed.

Alias wi
Required False
Pipeline false
Default Value
-Confirm

Prompts you for confirmation before executing any changing operations within the command.

Alias cf
Required False
Pipeline false
Default Value