The order of the write cycle

The write cycle calls methods of the table object. The base class is SQL table, and each of its hook methods does nothing. To add behaviour, write a subclass and override the hooks you need. Then name the subclass in the table declaration, with the x table class attribute. Here the invoice table gets an invoice number before the INSERT, when the caller did not give one. The hook changes the record it receives. That change reaches the SQL statement.

This is the insert cycle, in the order the code runs it. First, check pkey assigns a missing key. So every later step already sees the key. Second, protect validate can refuse the values. Third come the field triggers declared on the columns for the inserting event. Lesson 22 covers them. Fourth, the table hook trigger on inserting. Fifth, trigger assign counters, a hook for counter values. Sixth, protect draft. It runs only when the table has a draft field and your subclass defines protect draft. Its return value is written into the draft field. Then the INSERT statement runs, with RETURNING for the values the database decides. After the statement come the inserted field triggers, then the table hook trigger on inserted. Both after-steps run in the same transaction as the INSERT.

The update cycle has no key check. It starts with protect update, which can refuse the update as a whole. Then protect validate checks the values. Then the updating field triggers and the table hook trigger on updating. Every hook of the update receives the old record as a keyword argument. Remember from lesson 20 that the old record is the one you passed, or None. Note one difference from insert. In update, protect draft runs before trigger assign counters. After the UPDATE statement, update related applies the on update actions of the relations that point to this table. Lesson 23 covers them. Last come the updated field triggers and trigger on updated.

The delete cycle starts with the deletable attribute of the table. Then protect delete, the deleting field triggers and trigger on deleting. Then delete related applies the on delete actions of the relations that point to this table. This happens before the DELETE statement, so dependent rows are handled first. The DELETE must remove exactly one row. After it come the deleted field triggers, trigger on deleted, and finally trigger release counters.

This output comes from an invoice subclass that records each call. The date column declares a field trigger for all six events. The invoice table has no draft field, so protect draft does not appear. The three blocks match the three lists of the previous slides.

A hook refuses a write by raising an exception. The table method exception builds it for you. You give it a name from this table, the record and a message. The exception text names the table and the key of the record. Any Python error raised during a write has one more effect. The connection becomes rollback-only. A commit then raises transaction state error, until you call rollback. This prevents a commit of a write that stopped halfway.

A hook may write other tables. The nested write runs its own full cycle, on the same connection and in the same transaction. Here, inserting an invoice inserts a note. Inside a write, current trigger describes the operation in progress. It is available on the table and on the database. It has five fields: event, table, record, old record and parent. Event is insert, update or delete. Parent is the operation that caused this one, or None at the top level. So the note hook can see that it runs inside the insert of an invoice. Outside any write, current trigger is None. The record a hook receives is the caller's object. A change made by a before-hook is visible to the caller after the command returns.

A hook cannot finish the transaction it runs in. Commit and rollback on the connection in use raise transaction state error while a write is in progress. The caller of the outermost command decides when to commit.

Before the SQL statement run the key check, the protections, the field triggers, the table hook, the counters and the draft check. After the statement run the field triggers and the table hook, with the relation actions of update in between. Delete runs its relation actions before the statement. Hooks refuse with self dot exception, they can write other tables, and they never commit. The next lesson looks at the field triggers in detail.