Differential D9911 Diff 23791 src/docs/contributor/database.diviner

Changeset View

Standalone View

src/docs/contributor/database.diviner

	Show First 20 Lines • Show All 109 Lines • ▼ Show 20 Lines
	Each globally referencable object in Phabricator has its associated PHID			Each globally referencable object in Phabricator has its associated PHID
	(Phabricator ID) which serves as a global identifier. We use PHIDs for			(Phabricator ID) which serves as a global identifier. We use PHIDs for
	referencing data in different databases.			referencing data in different databases.

	We use both autoincrementing IDs and global PHIDs because each is useful in			We use both autoincrementing IDs and global PHIDs because each is useful in
	different contexts. Autoincrementing IDs are chronologically ordered and allow			different contexts. Autoincrementing IDs are chronologically ordered and allow
	us to construct short, human-readable object names (like D2258) and URIs. Global			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			PHIDs allow us to represent relationships between different types of objects in
	a homogenous way.			a homogeneous way.

	For example, the concept of "subscribers" is more powerfully done with PHIDs			For example, the concept of "subscribers" is more powerfully done with PHIDs
	because we could theoretically have users, projects, teams, and more all as			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			"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			"type" column to avoid ID collision; using PHIDs does not require this
	additional column.			additional column.

	= Transactions =			= Transactions =
	Show All 16 Lines
	Phabricator uses schema denormalization for performance reasons sparingly. Try			Phabricator uses schema denormalization for performance reasons sparingly. Try
	to avoid it if possible.			to avoid it if possible.

	= Changing the Schema =			= Changing the Schema =

	There are three simple steps to update the schema:			There are three simple steps to update the schema:

	# Create a `.sql` file in `resources/sql/patches/`. This file should:			# Create a `.sql` file in `resources/sql/patches/`. This file should:
	- Contain the approprate MySQL commands to update the schema.			- Contain the appropriate MySQL commands to update the schema.
	- Be named as `YYYYMMDD.patchname.ext`. For example, `20130217.example.sql`.			- Be named as `YYYYMMDD.patchname.ext`. For example, `20130217.example.sql`.
	- Use `${NAMESPACE}` rather than `phabricator` for database names.			- Use `${NAMESPACE}` rather than `phabricator` for database names.
	- Use `COLLATE utf8_bin` for any columns that are to be used as identifiers,			- Use `COLLATE utf8_bin` for any columns that are to be used as identifiers,
	such as PHID columns. Otherwise, use `COLLATE utf8_general_ci`.			such as PHID columns. Otherwise, use `COLLATE utf8_general_ci`.
	- Name all indexes so it is possible to delete them later.			- Name all indexes so it is possible to delete them later.
	# Edit `src/infrastructure/storage/patch/PhabricatorBuiltinPatchList.php` and			# Edit `src/infrastructure/storage/patch/PhabricatorBuiltinPatchList.php` and
	add your patch to @{method@phabricator:PhabricatorBuiltinPatchList::getPatches}.			add your patch to @{method@phabricator:PhabricatorBuiltinPatchList::getPatches}.
	# Run `bin/storage upgrade`.			# Run `bin/storage upgrade`.
	Show All 16 Lines