diff --git a/docs/core/architecture.md b/docs/core/architecture.md index 11e4cca9ae1e10d0ff2b58e22907f74843b74021..9e778c50f6e521ade998794479a985dc3fc7a6f6 100644 --- a/docs/core/architecture.md +++ b/docs/core/architecture.md @@ -57,7 +57,7 @@ The CiviCRM **data access objects** (DAOs) are PHP classes that ([e.g. `CRM/Pledge/DAO`](https://github.com/civicrm/civicrm-core/tree/master/CRM/Pledge/DAO)) expose the contents of the database. The release script generates each DAO automatically based -on the matching XML file in the [data schema](/framework/schema-definition.md). DAO objects tend to be instantiated in BAO classes. +on the matching XML file in the [data schema](/framework/database/schema-definition.md). DAO objects tend to be instantiated in BAO classes. The DAO classes all extend the core [DAO base class](https://github.com/civicrm/civicrm-core/blob/master/CRM/Core/DAO.php) diff --git a/docs/extensions/civix.md b/docs/extensions/civix.md index a57f995fcd5e7bcff4aa66d6be31cef5ed6248db..3a16f8f474baf913cd27d018fbb7f79365054ecb 100644 --- a/docs/extensions/civix.md +++ b/docs/extensions/civix.md @@ -191,7 +191,7 @@ to create a new entity. For this, you can use the command `civix generate:entity 1. Run `civix generate:entity MyEntity` (use CamelCase here). This creates a skeletal file for your XML schema, your BAO, and your API. It does NOT create a skeletal SQL file to create your table or DAO files at this time. -1. Edit the [XML schema definitions](/framework/schema-definition.md) in the `xml` folder to define your desired fields. +1. Edit the [XML schema definitions](/framework/database/schema-definition.md) in the `xml` folder to define your desired fields. 1. Generate a [DAO file](/core/architecture.md#dao) and SQL to create your table. *(For now, civix does not handle this part. Hopefully these steps will become easier at some point in the future.)* diff --git a/docs/framework/database/index.md b/docs/framework/database/index.md new file mode 100644 index 0000000000000000000000000000000000000000..bd40b193b51e8ba1001f9d740481fdf6ea1e3ae2 --- /dev/null +++ b/docs/framework/database/index.md @@ -0,0 +1,6 @@ +# CiviCRM Database Information + +CiviCRM has a complex Database structure which this chapter will examine in more depth. CiviCRM for various reasons has the Schema struture of its database written out in XML files store in `xml/templates/schema` These files are used to define all Core CiviCRM tables that are installed when CiviCRM is installed. CiviCRM maintains a number of tools and scripts such as `GenCode`, `bin/setup.sh`, `bin/regen.sh`, the purpose of these tools is to update any current database with the lastest information stored in the XML files, Re-create the installation .mysql files that live in `sql/civicrm*.mysql` which are not commited to the Git Repo but found in the Donwloadable package. Also They update the "DAO" Files which contain a reference of what files and what relationships are there in the Datbase. + +## Tools +<Insert documentation on how to use various tools> diff --git a/docs/framework/schema-definition.md b/docs/framework/database/schema-definition.md similarity index 100% rename from docs/framework/schema-definition.md rename to docs/framework/database/schema-definition.md diff --git a/docs/framework/database/schema-design.md b/docs/framework/database/schema-design.md new file mode 100644 index 0000000000000000000000000000000000000000..e0f955c4e8b3604ebc1c234400892afa3987c0b6 --- /dev/null +++ b/docs/framework/database/schema-design.md @@ -0,0 +1,30 @@ +## CiviCRM Schema Design + +## Why a Entity Relationship Diagram may *not* be helpful + +As some coders are visual learners, ER Diagrams maybe a waste of time for thsoe coders to understand the CivCRM Database modle and structure. Fundamentally CiviCRM's Schema diesgn is way too complex, with at least 150 tables and loads of Foriegn Key Constraints linking tables togeher any such graphic or design document that tries to map out the CiviCRM database design would most likely be more confusion than help, espeically for visual learners. + +## Aleternate Methods to ERDs to explore CiviCRM's Database Design + +Another method ofr viewing CiviCRM's Database model is to use one of various MySQL coding tools e.g. PHPMyAdmin or [MySql WOrkbench](https://www.mysql.com/products/workbench/). These tools allow coders to inspect the Table Structure more easily and look at all the constraints attached to tables very easily. + +## MySQL Workbench Workflow + +1. Look at the list of tables in the database. The table name generally gives you a good idea of the type of data it stores. +2. Pick one table and look closer. Let's look at `civicrm_country` (a relatively simple example) by opening the "Table inspector" for that table. + - We can look at the list of columns in the table. +  + We can see that columns have comments which explain (to some extent) the meaning of the data stored in the columns. From the Column Names and the comments we can start to get some idea of the relationship between tables. For example we can see that there is a column `address_format_id` which indicates to us that the table `civicrm_country` has a relationship to the table `civicrm_address_format` + - We can also Look at the Foriegn Keys that are relevant to this table +  + Here we can get more of a comprenshive picture of what tables `civicrm_country` relates to. We can tell that because we see not only what tables are referenced by `civicrm_country` but also the tables that reference `civicrm_country`. + +## General Characteristics of CiviCRM Tables + +When we look at CiviCRM Tables there are a few patterns that generally hold true: +- Every table has a id column which is Auto Increment and therefore unique key for that table +- Columns which reference other tables generally speaking will be named in the format of `other table name` + `_id`. For example in `civicrm_country` there is `address_format_id` which indicates that is references `civicrm_address_format.id` +- Many-to-many relationships use "join tables" as intermediary tables. For example, a contact can have many activity records, and an activity can have many contact records. So the table `civicrm_activity_contact` is used as the glue because it has foreign keys to both. +- In some places CiviCRM defines schema using a construct called [pseudoconstants](framework/database/schema-definition/#table-field-pseudoconstant) which produces some slightly more complex logic + - Lots of columns reference `civicrm_option_values` when they just need a simple (and user-configurable) list of options. For example, look at `civicrm_contribution` which has a column called `payment_instrument_id`. You'll notice there's no table called `civicrm_payment_instrument`. So in this case the `payment_instrument_id` column actually references the value column in `civicrm_option_values` (but only for records in `civicrm_option_values` with the appropriate `option_group_id`.) Here there is no foreign key, so referential integrity is managed at the application layer, not the database layer. + - Some tables use "dynamic foreign keys". For example, look at `civicrm_note` which has columns `entity_id` and `entity_table`. This is because a note can be attached to different entities (e.g. contact, contribution, etc). So two columns are used to indicate what the note references. Here again, the application layer is responsible for ensuring referential integrity, so you won't find any foreign keys. diff --git a/docs/img/mysql_workbench_civicrm_country_foreign_keys.png b/docs/img/mysql_workbench_civicrm_country_foreign_keys.png new file mode 100644 index 0000000000000000000000000000000000000000..6f81bda97ddf39144ff4101132a5c1ad4eefa562 Binary files /dev/null and b/docs/img/mysql_workbench_civicrm_country_foreign_keys.png differ diff --git a/docs/img/mysql_workbench_civicrm_country_tables.png b/docs/img/mysql_workbench_civicrm_country_tables.png new file mode 100644 index 0000000000000000000000000000000000000000..a69f99e9b70bf2a30a7fc06e6393d55b6e37fab8 Binary files /dev/null and b/docs/img/mysql_workbench_civicrm_country_tables.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 61fe930d9ff71ad68366ef9e802bd3e8679f4a59..b1086be302869c562d317f408021ff0084503038 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,8 +67,10 @@ pages: - Bootstrap Process: framework/bootstrap.md - Cache Reference: framework/cache.md # Components: /framework/components.md - # Database: /framework/database.md - - Schema definition: framework/schema-definition.md + - Database: + - Overview: framework/database/index.md + - XML Schema definition: framework/database/schema-definition.md + - Schema Design: framework/database/schema-design.md - Resources Reference: framework/resources.md - Region Reference: framework/region.md - Upgrade Reference: framework/upgrade.md diff --git a/redirects/internal.txt b/redirects/internal.txt index 33a44be2342b3fcb25371854062a132732a83450..988c9077653ffe9aa56de9a6405788d36c0ff020 100644 --- a/redirects/internal.txt +++ b/redirects/internal.txt @@ -5,3 +5,4 @@ best-practices/documentation-style-guide documentation/style-guide extensions/basics extensions api/general api hooks/hook_civicrm_trigger_info hooks/hook_civicrm_triggerInfo +framework/schema-definition framework/database/schema-definition