apscheduler.jobstores.sqlalchemy

class apscheduler.jobstores.sqlalchemy.SQLAlchemyJobStore(url=None, engine=None, tablename='apscheduler_jobs', metadata=None, pickle_protocol=5, tableschema=None, engine_options=None)

Bases: BaseJobStore

Stores jobs in a database table using SQLAlchemy. The table will be created if it doesn’t exist in the database.

Plugin alias: sqlalchemy

Parameters:
  • url (str) – connection string (see SQLAlchemy documentation on this)

  • engine – an SQLAlchemy Engine to use instead of creating a new one based on url

  • tablename (str) – name of the table to store jobs in

  • metadata – a MetaData instance to use instead of creating a new one

  • pickle_protocol (int) – pickle protocol level to use (for serialization), defaults to the highest available

  • tableschema (str) – name of the (existing) schema in the target database where the table should be

  • engine_options (dict) – keyword arguments to create_engine() (ignored if engine is given)

add_job(job)

Adds the given job to this store.

Parameters:

job (Job) – the job to add

Raises:

ConflictingIdError – if there is another job in this store with the same ID

get_all_jobs()

Returns a list of all jobs in this job store. The returned jobs should be sorted by next run time (ascending). Paused jobs (next_run_time == None) should be sorted last.

The job store is responsible for setting the scheduler and jobstore attributes of the returned jobs to point to the scheduler and itself, respectively.

Return type:

list[Job]

get_due_jobs(now)

Returns the list of jobs that have next_run_time earlier or equal to now. The returned jobs must be sorted by next run time (ascending).

Parameters:

now (datetime.datetime) – the current (timezone aware) datetime

Return type:

list[Job]

get_next_run_time()

Returns the earliest run time of all the jobs stored in this job store, or None if there are no active jobs.

Return type:

datetime.datetime

lookup_job(job_id)

Returns a specific job, or None if it isn’t found..

The job store is responsible for setting the scheduler and jobstore attributes of the returned job to point to the scheduler and itself, respectively.

Parameters:

job_id (str|unicode) – identifier of the job

Return type:

Job

remove_all_jobs()

Removes all jobs from this store.

remove_job(job_id)

Removes the given job from this store.

Parameters:

job_id (str|unicode) – identifier of the job

Raises:

JobLookupError – if the job does not exist

shutdown()

Frees any resources still bound to this job store.

start(scheduler, alias)

Called by the scheduler when the scheduler is being started or when the job store is being added to an already running scheduler.

Parameters:
update_job(job)

Replaces the job in the store with the given newer version.

Parameters:

job (Job) – the job to update

Raises:

JobLookupError – if the job does not exist

API

class apscheduler.jobstores.sqlalchemy.SQLAlchemyJobStore(url=None, engine=None, tablename='apscheduler_jobs', metadata=None, pickle_protocol=pickle.HIGHEST_PROTOCOL)

Bases: BaseJobStore

Stores jobs in a database table using SQLAlchemy. The table will be created if it doesn’t exist in the database.

Plugin alias: sqlalchemy

Parameters:
  • url (str) – connection string (see SQLAlchemy documentation on this)

  • engine – an SQLAlchemy Engine to use instead of creating a new one based on url

  • tablename (str) – name of the table to store jobs in

  • metadata – a MetaData instance to use instead of creating a new one

  • pickle_protocol (int) – pickle protocol level to use (for serialization), defaults to the highest available

  • tableschema (str) – name of the (existing) schema in the target database where the table should be

  • engine_options (dict) – keyword arguments to create_engine() (ignored if engine is given)

add_job(job)

Adds the given job to this store.

Parameters:

job (Job) – the job to add

Raises:

ConflictingIdError – if there is another job in this store with the same ID

get_all_jobs()

Returns a list of all jobs in this job store. The returned jobs should be sorted by next run time (ascending). Paused jobs (next_run_time == None) should be sorted last.

The job store is responsible for setting the scheduler and jobstore attributes of the returned jobs to point to the scheduler and itself, respectively.

Return type:

list[Job]

get_due_jobs(now)

Returns the list of jobs that have next_run_time earlier or equal to now. The returned jobs must be sorted by next run time (ascending).

Parameters:

now (datetime.datetime) – the current (timezone aware) datetime

Return type:

list[Job]

get_next_run_time()

Returns the earliest run time of all the jobs stored in this job store, or None if there are no active jobs.

Return type:

datetime.datetime

lookup_job(job_id)

Returns a specific job, or None if it isn’t found..

The job store is responsible for setting the scheduler and jobstore attributes of the returned job to point to the scheduler and itself, respectively.

Parameters:

job_id (str|unicode) – identifier of the job

Return type:

Job

remove_all_jobs()

Removes all jobs from this store.

remove_job(job_id)

Removes the given job from this store.

Parameters:

job_id (str|unicode) – identifier of the job

Raises:

JobLookupError – if the job does not exist

shutdown()

Frees any resources still bound to this job store.

start(scheduler, alias)

Called by the scheduler when the scheduler is being started or when the job store is being added to an already running scheduler.

Parameters:
update_job(job)

Replaces the job in the store with the given newer version.

Parameters:

job (Job) – the job to update

Raises:

JobLookupError – if the job does not exist

Introduction

SQLAlchemyJobStore stores jobs in any relational database management system supported by SQLAlchemy. It can use either a preconfigured Engine or you can pass it a connection URL.

External dependencies

SQLAlchemy (+ the backend specific driver package)

Example

examples/jobstores/sqlalchemy_.py (view online).