Add database table page; fix broken link (#107)

* Add database table page; fix broken link * add spell check errors to custom_wordlist * add rename-database-table to how-to/index.rst * fix reference link to rename-database-table page in live-patching.rst explanation doc * format rename-database-table to show as sql code --------- Co-authored-by: Jared Nielsen <[email protected]> Co-authored-by: Alvaro Crespo <[email protected]>
canonical · Oct 9, 2024 · c690ef5 · c690ef5
1 parent 5b319ab
commit c690ef5
Show file tree

Hide file tree

Showing 5 changed files with 72 additions and 3 deletions.
diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt
@@ -123,6 +123,7 @@ DecoratedResultSet
 DecoratedResultSets
 defense
 defense
+del
 deps
 Desc
 dev
@@ -163,6 +164,7 @@ fastdowntime
 fastnodowntime
 favicons
 FK
+fk
 flavor
 FooBar
 foofunc
@@ -207,6 +209,7 @@ IBranchMergeProposal
 IBranchTarget
 ICanonicalUrlData
 ICodeReviewMessage
+idx
 iframe
 iharness
 IMailDelivery
@@ -226,7 +229,11 @@ IPv
 IPython
 IRangeFactory
 irc
+IrcId
+ircid
 IRCMeetings
+IrcNickname
+ircnickname
 iter
 Javadoc
 javascript
@@ -305,6 +312,7 @@ natively
 NavigationMenu
 NavigationMenus
 newsampledata
+nextval
 nfs
 NPM
 NTP
@@ -347,6 +355,7 @@ pgbouncer
 pgSQL
 pgsql
 pipx
+pkey
 plaintext
 png
 po
@@ -558,6 +567,8 @@ unproxied
 unsuffixed
 untriaged
 untrusted
+upd
+updatable
 upstreams
 url
 urls

diff --git a/custom_conf.py b/custom_conf.py
@@ -128,7 +128,6 @@
     'Trunk/Glue',  # needs update
     '/Background', 
     '/Concepts',  # needs update
-    'Database/TableRenamePatch',  # needs update
     'Debugging#Profiling%20page%20requests',  # needs update
     'Debugging#Special%20URLs',  # needs update
     'JavascriptUnitTesting/MockIo',  # needs update

diff --git a/explanation/live-patching.rst b/explanation/live-patching.rst
@@ -126,8 +126,7 @@ Table Renaming
 
 Because code is being deployed separately from database updates, we need
 to maintain a fully updateable working alias for the old table name to
-the new table name. See
-`Database/TableRenamePatch <Database/TableRenamePatch>`__ for an example
+the new table name. See :doc:`Rename Database Table <../how-to/rename-database-table>` for an example
 database patch.
 
 Adding columns

diff --git a/how-to/index.rst b/how-to/index.rst
@@ -41,4 +41,5 @@ If you have a running instance of Launchpad, there are common tasks you might ne
    :maxdepth: 2
 
    operating-launchpad
+   rename-database-table
 
diff --git a/how-to/rename-database-table.rst b/how-to/rename-database-table.rst
@@ -0,0 +1,59 @@
+=========================
+Renaming a Database Table
+=========================
+
+Renaming a table involves a few steps:
+
+1. Rename the table
+2. Rename dependent objects, like constraints, indexes, and sequences.
+3. Create a writable view using the old name so deployed code keeps working.
+
+For example:
+
+.. code-block:: sql
+
+    -- Copyright 2011 Canonical Ltd.
+    -- This software is licensed under the GNU Affero General Public License version 3 (see the file LICENSE).
+    SET client_min_messages=ERROR;
+
+    -- Rename the table
+    ALTER TABLE IrcId RENAME TO IrcNickname;
+
+    -- And rename sequences, constraints, and indexes to match.
+    ALTER SEQUENCE ircid_id_seq RENAME TO ircnickname_id_seq;
+    ALTER TABLE IrcNickname
+        -- With Slony 1.2.22, renaming the primary key fails. Leave these
+        -- with the old names for now.
+        -- DROP CONSTRAINT ircid_pkey,
+        -- ADD CONSTRAINT ircnickname_pkey PRIMARY KEY (id),
+        DROP CONSTRAINT ircid_person_fk,
+        ADD CONSTRAINT ircnickname_person_fk
+            FOREIGN KEY (person) REFERENCES Person;
+    ALTER INDEX ircid_person_idx RENAME TO ircnickname_person_idx;
+
+    -- Create a view with the old table name for backwards compatibility.
+    CREATE OR REPLACE VIEW IrcId AS SELECT * FROM IrcNickname;
+
+    -- Make the backwards compatibility view updatable.
+    CREATE OR REPLACE RULE IrcId_ins AS ON INSERT TO IrcId DO INSTEAD
+        INSERT INTO IrcNickname VALUES (
+            COALESCE(NEW.id, nextval('ircnickname_id_seq')),
+            NEW.person,
+            NEW.network,
+            NEW.nickname)
+        RETURNING IrcNickname.*;
+
+    CREATE OR REPLACE RULE IrcId_upd AS ON UPDATE TO IrcId DO INSTEAD
+        UPDATE IrcNickname SET
+            id = NEW.id,
+            person = NEW.person,
+            network = NEW.network,
+            nickname = NEW.nickname
+        WHERE id = OLD.id
+        RETURNING IrcNickname.*;
+
+    CREATE OR REPLACE RULE IrcId_del AS ON DELETE TO IrcId DO INSTEAD
+        DELETE FROM IrcNickname WHERE id = OLD.id
+        RETURNING IrcNickname.*;
+
+    INSERT INTO LaunchpadDatabaseRevision VALUES (2208, 85, 0);