Coverage for dak/dakdb/__init__.py: 100%

1""" 

2Database update scripts for usage with ``dak update-db`` 

3 

4@contact: Debian FTP Master <ftpmaster@debian.org> 

5@copyright: 2008 Michael Casadevall <mcasadevall@debian.org> 

6@license: GNU General Public License version 2 or later 

7 

8Update scripts usually only need a module docstring (its first non-empty 

9line is shown to the user) and a module-level ``statements`` sequence (a 

10list or tuple) of SQL statements:: 

11 

12 statements = [ 

13 "ALTER TABLE suite ADD COLUMN mascot TEXT", 

14 ] 

15 

16Update scripts that need more than a fixed sequence of SQL statements 

17define the function ``do_update(c)`` instead, which is called with an 

18open cursor and can do whatever it wants using everything from dak and 

19daklib:: 

20 

21 def do_update(c: psycopg2.extensions.cursor) -> None: 

22 c.execute("SOME SQL STATEMENT") 

23 

24A script must not define both ``statements`` and ``do_update``. 

25 

26In both cases ``dak update-db`` prints the module docstring, runs the 

27statements or the function in a single transaction, updates 

28``db_revision`` in the ``config`` table and commits. On any error the 

29transaction is rolled back: a :exc:`psycopg2.ProgrammingError` is 

30reported as a :exc:`~daklib.dak_exceptions.DBUpdateError`; any other 

31exception is re-raised unchanged. ``do_update`` may raise 

32:exc:`~daklib.dak_exceptions.DBUpdateError` itself to abort the update 

33with a friendly message. 

34 

35"""