Answers.Body: <blockquote>
    <p>What is the installation canary?</p>
  </blockquote>
  
  <p>The <code>civicrm_install_canary</code> is fundamentally a test to see how well we control/understand the installation process. It's part of a bigger topic, so bear with me in giving the context.</p>
  
  <p>The crux of the CiviCRM installation process has traditionally been two steps: </p>
  
  <ul>
  <li>Copy a config template and edit it (<code>civicrm.settings.php.tpl</code> => <code>civicrm.settings.php</code>).</li>
  <li>Load a SQL file into the database (<code>civicrm.mysql</code> <em>and</em> either <code>civicrm_data.mysql</code> or <code>civicrm_generated.mysql</code>).</li>
  </ul>
  
  <p>When you use tools like <code>sites/all/modules/civicrm/install/index.php</code> or the Joomla installer or <code>setup.sh</code> or <code>civibuild</code> or <code>provision_civicrm</code>, these are basically all wrappers which do those two steps (plus <em>random-other-things</em>).</p>
  
  <p>There are several installation-related things which aren't addressed by those two standardized steps, leading to some pain-points, e.g.</p>
  
  <ul>
  <li>System requirements are not enforced or communicated consistently across installers.</li>
  <li>If you install from <code>git</code> (instead of <code>.tar.gz</code> or <code>.zip</code>), then you need to run extra commands (<code>GenCode</code>).</li>
  <li>You cannot automatically activate CiviCRM extensions during installation.</li>
  <li>SQL triggers are generated using PHP logic. (The triggers should be generated during installation... and also when setting up custom-data or extensions...)</li>
  <li>If you want to use a different language, then you need to load localized <code>.mysql</code> files. The pre-generation process for this slows down developmental builds and produces slightly stale translations for users.</li>
  <li>PHP's MySQL API's have become a bit hostile to pre-generating SQL files.</li>
  </ul>
  
  <p>For a long time, changing this was blocked because we simply didn't have a reliable way to add PHP logic during all installations... until someone proposed that we could do a bit of install logic during the first page-request. Sometime (maybe 4.7.0?) we introduced <code>SystemInstallEvent</code>.</p>
  
  <p>Originally, the only thing <code>SystemInstallEvent</code> did was prove its own validity. The event should fire exactly once. If it fires a second time, then that's an error. Specifically, the <code>SystemInstallEvent</code> triggers the <code>InstallationCanary</code> which creates the table <code>civicrm_install_canary</code> (and failing if it already exists).</p>
  
  <p>Eventually, we added <code>DatabaseInitializer</code> which also listens for <code>SystemInstallEvent</code>. During the first page-request, it runs the <code>System.flush</code> to ensure that triggers, caches, etal are current.</p>
  
  <blockquote>
    <p>Does it mean that the installation has been failed irreparable, and that the backup must be restored.</p>
  </blockquote>
  
  <p>The system is probably OK. If you're getting an error, here are a few things to know:</p>
  
  <ol>
  <li>On a new system (before the first page-view), the expected pre-condition is that the setting <code>installed</code> is untrue/undefined. The table <code>civicrm_install_canary</code> does not exist.</li>
  <li>On an active system (after the first page-view), the expected post-condition is that the setting <code>installed</code> is true. The table <code>civicrm_install_canary</code> does exist.</li>
  <li>If your system satisfies either pre-condition or post-condition, then it should be fine. You only get an error from a mix.</li>
  <li>You might want to do a system flush and enable triggers, e.g.
  
  <ul>
  <li>Using Drupal website: <code>http://mysite.example.com/civicrm/clearcache?triggerRebuild=1</code></li>
  <li>Using drush CLI: <code>drush cvapi system.flush triggers=1</code></li>
  <li>Using <a href="https://github.com/civicrm/cv" rel="noreferrer">cv</a> CLI: <code>cv api system.flush triggers=1</code></li>
  </ul></li>
  </ol>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-10-28T21:46:17.060Z
Answers.Text: Theory: You might hit the error if you mix old database dumps incorrectly. For example, if (a) start out on v4.5.0 and make database dump, (b) upgrade to latest, and (c) uncleanly reload the database dump from v4.5.0, then (d) you might get an error. The trick: when reloading the database, you need to consistently clear out old tables. This is generally true whenever you mix DB dumps from different versions (regardless of the canary).
Answers.UserDisplayName: Tim Otten
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-11-03T15:34:18.460Z
Answers.Text: How does one run GenCode if you install from Git?  I was interested to see it, since during development one may have to pull code from GitHub and I found Joomla failed after doing so.
Answers.UserDisplayName: Stephen Palmstrom
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-11-03T17:08:40.987Z
Answers.Text: You generally create `bin/setup.conf` (see template in `bin`) and then run `./bin/setup.sh -g`. It should work in Drupal+WordPress. But there's a general caveat that the civicrm-joomla initialization is pretty complicated and makes it hard to get full parity in git/dev experience. For Joomla-based dev, I suggest opening a new question.
Answers.UserDisplayName: Tim Otten
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-10-28T21:43:33.607Z
Answers.LastActivityDate: 2016-10-29T17:06:05.753Z
Answers.LastEditDate: 2016-10-29T17:06:05.753Z
Answers.UserDisplayName: Tim Otten
Body: <p>One of my CiviCRM instances database has the table <code>civicrm_install_canary</code>, another has not. In code it is marked as a mechanism that check whether the install has run before. But how does this mechanism work. Does it mean that the installation has been failed irreparable, and that the backup must be restored. Is er een method to fix it, or can it maybe restored (or ignored)?</p>
  
  <p>The installation canary is part of the current code base (CiviCRM 4.7.12).</p>
  
Tags: <database><installation>
Title: What is the installation canary?
ThreadText: # What is the installation canary?
  
  (Asked by: username_0 on 2016-10-28)
  
  One of my CiviCRM instances database has the table `civicrm_install_canary`, another has not. In code it is marked as a mechanism that check whether the install has run before. But how does this mechanism work. Does it mean that the installation has been failed irreparable, and that the backup must be restored. Is er een method to fix it, or can it maybe restored (or ignored)?
  
  The installation canary is part of the current code base (CiviCRM 4.7.12).
  
  **Tags:** database, installation
  
  
  ---
  
  ## 1 answers
  
  ### Answer by username_1 on 2016-10-28. Score: 11 | Accepted answer
  
  > What is the installation canary?
  
  The `civicrm_install_canary` is fundamentally a test to see how well we control/understand the installation process. It's part of a bigger topic, so bear with me in giving the context.
  
  The crux of the CiviCRM installation process has traditionally been two steps:
  
  * Copy a config template and edit it (`civicrm.settings.php.tpl` => `civicrm.settings.php`).
  * Load a SQL file into the database (`civicrm.mysql` *and* either `civicrm_data.mysql` or `civicrm_generated.mysql`).
  
  When you use tools like `sites/all/modules/civicrm/install/index.php` or the Joomla installer or `setup.sh` or `civibuild` or `provision_civicrm`, these are basically all wrappers which do those two steps (plus *random-other-things*).
  
  There are several installation-related things which aren't addressed by those two standardized steps, leading to some pain-points, e.g.
  
  * System requirements are not enforced or communicated consistently across installers.
  * If you install from `git` (instead of `.tar.gz` or `.zip`), then you need to run extra commands (`GenCode`).
  * You cannot automatically activate CiviCRM extensions during installation.
  * SQL triggers are generated using PHP logic. (The triggers should be generated during installation... and also when setting up custom-data or extensions...)
  * If you want to use a different language, then you need to load localized `.mysql` files. The pre-generation process for this slows down developmental builds and produces slightly stale translations for users.
  * PHP's MySQL API's have become a bit hostile to pre-generating SQL files.
  
  For a long time, changing this was blocked because we simply didn't have a reliable way to add PHP logic during all installations... until someone proposed that we could do a bit of install logic during the first page-request. Sometime (maybe 4.7.0?) we introduced `SystemInstallEvent`.
  
  Originally, the only thing `SystemInstallEvent` did was prove its own validity. The event should fire exactly once. If it fires a second time, then that's an error. Specifically, the `SystemInstallEvent` triggers the `InstallationCanary` which creates the table `civicrm_install_canary` (and failing if it already exists).
  
  Eventually, we added `DatabaseInitializer` which also listens for `SystemInstallEvent`. During the first page-request, it runs the `System.flush` to ensure that triggers, caches, etal are current.
  
  > Does it mean that the installation has been failed irreparable, and that the backup must be restored.
  
  The system is probably OK. If you're getting an error, here are a few things to know:
  
  1. On a new system (before the first page-view), the expected pre-condition is that the setting `installed` is untrue/undefined. The table `civicrm_install_canary` does not exist.
  2. On an active system (after the first page-view), the expected post-condition is that the setting `installed` is true. The table `civicrm_install_canary` does exist.
  3. If your system satisfies either pre-condition or post-condition, then it should be fine. You only get an error from a mix.
  4. You might want to do a system flush and enable triggers, e.g.
     * Using Drupal website: `http://mysite.example.com/civicrm/clearcache?triggerRebuild=1`
     * Using drush CLI: `drush cvapi system.flush triggers=1`
     * Using [cv](https://github.com/civicrm/cv) CLI: `cv api system.flush triggers=1`
  
  > **Comments:**
  > **username_1**: Theory: You might hit the error if you mix old database dumps incorrectly. For example, if (a) start out on v4.5.0 and make database dump, (b) upgrade to latest, and (c) uncleanly reload the database dump from v4.5.0, then (d) you might get an error. The trick: when reloading the database, you need to consistently clear out old tables. This is generally true whenever you mix DB dumps from different versions (regardless of the canary).  
  > **username_2**: How does one run GenCode if you install from Git?  I was interested to see it, since during development one may have to pull code from GitHub and I found Joomla failed after doing so.  
  > **username_1**: You generally create `bin/setup.conf` (see template in `bin`) and then run `./bin/setup.sh -g`. It should work in Drupal+WordPress. But there's a general caveat that the civicrm-joomla initialization is pretty complicated and makes it hard to get full parity in git/dev experience. For Joomla-based dev, I suggest opening a new question.  
  
  ---
  
  