Create a SQL Server Agent Schedule with T-SQL

When using T-SQL, you can use the sp_add_schedule stored procedure to add a SQL Server Agent schedule.

This procedure creates the schedule, but it doesn’t attach it to any jobs. To attach it to a job, you must use the sp_attach_schedule procedure.

You can also use sp_add_jobschedule to create the schedule and attach it all with the same procedure.

Example of the sp_add_schedule Procedure

Here’s an example that uses sp_add_schedule to create a new schedule:

EXEC sp_add_schedule 
    @schedule_name = N'RunDailyAM',
    @freq_type = 4,
    @freq_interval = 4,
    @active_start_time = 041000;
GO

This stored procedure accepts more arguments than i’ve included in this example, but these are some of the more common ones. See the tables below for an outline of the accepted values.

@schedule_name is a required argument, but the others are optional, and have default settings in case you don’t provide them.

We can now use sp_attach_schedule to attach that schedule to an existing job:


EXEC sp_attach_schedule  
   @job_name = N'BackupPetHotelDB',  
   @schedule_name = N'RunDailyAM';  
GO

When you use sp_attach_schedule, you must provide the name of the job or its ID (but not both), as well as the schedule name or ID (but not both).

Example of the sp_add_jobschedule Procedure

Here’s an example that uses sp_add_jobschedule to create a new schedule and attach it to a job, all in one go:

EXEC sp_add_jobschedule 
    @job_name = N'BackupMusicDB',
    @name = N'Weekly_Sun_3AM',
    @freq_type = 8,
    @freq_interval = 1,
    @freq_recurrence_factor = 1,
    @active_start_time = 30000;

With this procedure the @job_name argument provides the job name, and the @name argument provides the name that you want to give to the schedule.

Parameter Values

The way schedule data is stored in the msdb database makes it a little bit tricky when it comes to scheduling jobs with T-SQL.

Date/time values are stored as int types. Frequency type is expressed as an int, as is the interval values, and various other options.

Below is an overview of the accepted values for the parameters provided in the above examples.

@freq_type

This argument specifies when a job is to be executed. It accepts the following values:

ValueDescription
1Once
4Daily
8Weekly
16Monthly
32Monthly, relative to freq_interval
64Run when SQL Agent service starts
128Run when the computer is idle

@freq_interval

This argument specifies the days that a job is executed.

This argument depends on the value of the @freq_type argument, as outlined in the following table:

Value of freq_typeEffect on freq_interval
1 (once)freq_interval is unused.
4 (daily)Every freq_interval days.
8 (weekly)freq_interval is one or more of the following (combined with an OR logical operator):

1 (Sunday)

2 (Monday)

4 (Tuesday)

8 (Wednesday)

16 (Thursday)

32 (Friday)

64 (Saturday)
16 (monthly)On the freq_interval day of the month.
32 (monthly relative)freq_interval is one of the following:

1 (Sunday)

2 (Monday)

3 (Tuesday)

4 (Wednesday)

5 (Thursday)

6 (Friday)

7 (Saturday)

8 (Day)

9 (Weekday)

10 (Weekend day)
64 (when SQLServerAgent service starts)freq_interval is unused.
128freq_interval is unused.

@freq_recurrence_factor

This specifies the number of weeks or months between the scheduled execution of a job.

This is int, with a default of 0, and is used only if freq_type is 816, or 32.

@active_start_time

Specifies the time on any day between the @active_start_date and the @active_end_date arguments to begin execution of a job. @active_start_time is int, with a default of 000000, which indicates 12:00:00 A.M. on a 24-hour clock, and must be entered using the form HHMMSS.

@active_start_date

Although not included in my examples above, the @active_start_date argument allows you to specify the date on which execution of a job can begin. This is int, with a default of NULL, which indicates today’s date. The date is formatted as YYYYMMDD.

@active_end_date

You can also provide an @active_end_date argument, which specifies the date on which execution of a job can stop.

@active_end_date is int, with a default of 99991231, which indicates December 31, 9999. The date is formatted as YYYYMMDD.

More Info

See Microsoft’s documentation for sp_add_schedule and/or Microsoft’s documentation for sp_add_jobschedule for more details on the various arguments and their accepted values.