From 689c98c47c33eb3243e94d5b3b39e8c2bb5fba4d Mon Sep 17 00:00:00 2001 From: Bob Trahan Date: Thu, 4 Oct 2012 15:26:16 -0700 Subject: [PATCH] Update database.schema doc to include how to upgrade the schema Summary: plus update the phid section a little Test Plan: read it, looked good. Reviewers: epriestley Reviewed By: epriestley CC: aran, Korvin Maniphest Tasks: T1287 Differential Revision: https://secure.phabricator.com/D3629 --- src/docs/developer/database.diviner | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/src/docs/developer/database.diviner b/src/docs/developer/database.diviner index 3dfbd9c0c6..5f915525d8 100644 --- a/src/docs/developer/database.diviner +++ b/src/docs/developer/database.diviner @@ -103,7 +103,7 @@ no inconsistencies can arise. It will just slow us down. Each globally referencable object in Phabricator has its associated PHID (Phabricator ID) which serves as a global identifier. We use PHIDs for -referencing data in different databases. PHIDs are stored in table `phid`. +referencing data in different databases. We use both autoincrementing IDs and global PHIDs because each is useful in different contexts. Autoincrementing IDs are chronologically ordered and allow @@ -111,6 +111,12 @@ us to construct short, human-readable object names (like D2258) and URIs. Global PHIDs allow us to represent relationships between different types of objects in a homogenous way. +For example, the concept of "subscribers" is more powerfully done with PHIDs +because we could theoretically have users, projects, teams, and more all +as "subscribers" of other objects. Using an ID column we would need to add a +"type" column to avoid ID collision; using PHIDs does not require this +additional column. + = Transactions = Transactional code should be written using transactions. Example of such code is @@ -131,6 +137,25 @@ systems (which we don't support anyway). Phabricator uses schema denormalization for performance reasons sparingly. Try to avoid it if possible. += Changing the Schema = + +There are three simple steps to update the schema: + +- Create a `.sql` file in `resources/sql/patches/`. This file should: + - Contain the approprate MySQL commands to update the schema. + - Use `${NAMESPACE}` rather than `Phabricator` for database and table names. + - Use `COLLATE utf8_bin` for any columns that are to be used as identifiers, +such as PHID columns. Otherwise, use `COLLATE utf8_general_ci`. +- Edit `src/infrastructure/storage/patch/PhabricatorBuiltinPatchList.php` and +add your patch to @{method@phabricator:PhabricatorBuiltinPatchList::getPatches}. +- Run `bin/storage/upgrade`. + +See the +[[https://secure.phabricator.com/rPb39175342dc5bee0c2246b05fa277e76a7e96ed3 +| commit adding policy storage for Paste ]] for a reasonable example of the code +changes. + = See Also = * @{class:LiskDAO} +* @{class:PhabricatorPHID}