CREATE EVENT

Sintassi

CREATE [OR REPLACE]
    [DEFINER = { utente | CURRENT_USER | role | CURRENT_ROLE }]
    EVENT 
    [IF NOT EXISTS]
    nome_evento    
    ON SCHEDULE schedule
    [ON COMPLETION [NOT] PRESERVE]
    [ENABLE | DISABLE | DISABLE ON SLAVE]
    [COMMENT 'comment0']
    DO istruzione_sql;

schedule:
    AT timestamp [+ INTERVAL interval] ...
  | EVERY intervallo 
    [STARTS timestamp [+ INTERVAL interval] ...] 
    [ENDS timestamp [+ INTERVAL interval] ...]

intervallo:
    quantità {YEAR | QUARTER | MONTH | DAY | HOUR | MINUTE |
              WEEK | SECOND | YEAR_MONTH | DAY_HOUR | DAY_MINUTE |
              DAY_SECOND | HOUR_MINUTE | HOUR_SECOND | MINUTE_SECOND}

Spiegazione

Questa istruzione crea e pianifica un Evento. E' necessario il privilegio EVENT sullo schema nel quale si desidera creare l'Evento.

I requisiti minimi per poter eseguire CREATE EVENT sono i seguenti:

• Le parole chiave CREATE EVENT più il nome dell'evento, che identifica univocamente il nome dell'Evento nello schema corrente. (Prima di MySQL 5.1.12, il nome dell'Evento doveva essere univoco solo tra gli Eventi creati dallo stesso utente su un dato database)
• Una clausola ON SCHEDULE, che stabilisce quando e quanto spesso l'Evento verrà eseguito.
• Una clausola DO, che contiene l'istruzione SQL che l'Evento dovrà eseguire.

Ecco un esempio di istruzione CREATE EVENT minimale:

CREATE EVENT myevent
    ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 HOUR
    DO
      UPDATE myschema.mytable SET mycol = mycol + 1;

L'istruzione precedente crea un evento chiamato myevent. Questo evento viene eseguito una sola volta — un'ora dopo la sua creazione — ed esegue un'istruzione SQL che incrementa di 1 il valore della colonna mycol nella tabella myschema.mytable.

Il nome dell'Evento deve essere un identificatore valido di MySQL con una lunghezza massima di 64 caratteri. Può essere racchiuso tra i backtick, e può essere qualificato con il nome dello schema. Gli Eventi sono associati a un utente MySQL (il definer) e a uno schema, e il nome deve essere univoco all'interno dello schema. In generale, le regole che governano i nomi degli Eventi sono le stesse che regolano i nomi delle Stored Routine. Si veda http://dev.mysql.com/doc/refman/5.1/en/identifiers.html.

Se non viene indicato uno schema come parte di nome_evento, viene usato lo schema corrente.

La clausola ON SCHEDULE serve a specificato quando l'Evento deve essere eseguito.

Se si desidera eseguire l'Evento una sola volta (one time Event), è possibile utilizzare la parola chiave AT, seguita da un timestamp. Se si specifica CURRENT_TIMESTAMP, l'Event agirà appena creato. Per comodità, si può aggiungere al timestamp uno o più intervalli. Si può anche specificare un timestamp nel passato, in modo che l'evento esista ma non sia eseguito, finché non lo si modifica con ALTER EVENT.

L'esempio seguente mostra come creare un Evento che verrà eseguito domani a una data ora:

CREATE EVENT example ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 DAY + INTERVAL 3 HOUR DO something;

E' anche possibile specificare che l'Evento deve essere eseguito a intervalli regolari (recurring Event). In questo caso, si usa la clausola EVERY seguita dall'intervallo.

Se un Evento è recurring, è possibile specificare quando deve essere eseguito per la prima volta tramite la clausola STARTS e un tempo massimo per la sua ultima esecuzione tramite la clausola ENDS. STARTS e ENDS devono essere seguite da un timestamp e, opzionalmente, da uno o più intervalli. La clausola ENDS può specificare un timestamp nel passato, in modo che l'evento esista ma non sia eseguito, finché non lo si modifica con ALTER EVENT.

Nel seguente esempio, il prossimo mese un Evento recurring verrà eseguito ogni ora per una settimana:

CREATE EVENT example ON SCHEDULE EVERY 1 HOUR STARTS CURRENT_TIMESTAMP + 1 MONTH ENDS CURRENT_TIMESTAMP + 1 MONTH + 1 WEEK DO some_task;

Gli intervalli consistono di una quantità e un'unità di tempo. Le unità temporali sono le stesse utilizzate per altre istruzioni e funzioni temporali, ad eccezione dei microsecondi che non possono essere usati per gli eventi. Per le unità di tempo semplici, come HOUR e MINUTE, la quantità è un numero intero,per esempio '10 MINUTE'. Per le unità composte, come HOUR_MINUTE e HOUR_SECOND, la quantità deve essere una stringa contenente tutti i valori semplici necessari e i loro separatori, per esempio '2:30' e '2:30:30'.

La clausola ON COMPLETION specifica se l'evento deve essere eliminato o meno dopo la sua esecuzione (cioè dopo che i timestamp specificati in AT o ENDS sono passati). Per default, gli Eventi vengono eliminati alla loro scadenza. Per affermare esplicitamente che questo è il comportamento desiderato, è possibile utilizzare ON COMPLETION NOT PRESERVE. Se invece si desidera che l'evento sia conservato, si può specificare ON COMPLETION PRESERVE.

Se si specifica ON COMPLETION NOT PRESERVE, e un timestamp nel passato per la clausola AT o ENDS, l'Evento viene immediatamente eliminato. In questi casi si ottiene una Note 1558: "Event execution time is in the past and ON COMPLETION NOT PRESERVE is set. The event was dropped immediately after creation".

Gli eventi sono abilitati per default. Se si desidera impedire che MariaDB esegua un Evento, è possibile specificare DISABLE. Quando questo è pronto per essere attivato, si può abilitarlo con ALTER EVENT. Un'altra opzione è DISABLE ON SLAVE, che impedisce agli slave di eseguire l'evento.

La clausola COMMENT serve ad associare un commento all'Evento. La lunghezza massima per i commenti è di 64 caratteri. Il commento è una stringa, perciò deve essere virgolettato. Per visualizzare i commenti degli Eventi, è possibile interrogare la tabella EVENTS nel database INFORMATION_SCHEMA (colonna EVENT_COMMENT).