Add Databases
=============
Databases hold structured data and the general understanding of what a database is holds here. We offer support for systems
that commonly back Drupal, Wordpress, and other common open source CMS and framework systems. The Databases are managed as
part of the project and may be moved around and created within the hosted environments with a click of a button.

.. note: screenshot starting width: 1200 x 675 or 1200 x 900
.. |Databases Icon| image:: ../../../shared/images/v2.6.2/portal/icon_databases.jpg
  :height: 16
  :align: middle
  :alt: Open the Pipelines dashboard

.. |Plus Icon Blue| image:: ../../../shared/images/v2.6.2/portal/icon_plus_blue.jpg
  :height: 12
  :align: middle
  :alt: Click to add a database group

.. |Project Databases| image:: ../../../shared/images/v2.6.2/portal/project_databases.jpg
  :width: 400
  :alt: The databases configuration page controls database configuration for each environment in the project

.. |Project Databases Disabled| image:: ../../../shared/images/v2.6.2/portal/project_databases_disabled.jpg
  :width: 400
  :alt: The databases are currently disabled and they may be enabled by unchecking the appropriate box

.. |Project Databases Example| image:: ../../../shared/images/v2.6.2/portal/project_databases_example.jpg
  :width: 400
  :alt: This example shows a newly created database group as an additional database

Prerequisites
+++++++++++++

You will need to log into Cascade as a Project Administrator to configure Databases. To check your permissions, please
navigate to the overview page of the project you wish to modify. If your display does not include the Databases icon
( |Databases Icon| ) in the left toolbar, your account does not have sufficient privileges to proceed. If you click the
Databases icon, you should see the Databases configuration page.

|Project Databases|

In addition to the correct permissions in Cascade, in order to import pre-existing databases to your hosting system,
additional access to the hosting systems are required. This tooling and access layer is managed by Contegix. If you have
questions or need access please contact your project technical lead or Contegix support to request access to upload files.


Enable Databases
++++++++++++++++
Please navigate to the overview page of the project you wish to modify and click the Databases icon ( |Databases Icon| )
in the left toolbar. If Databases are not currently enabled you will see a page like below.

|Project Databases Disabled|

#. Uncheck the checkbox titled "This project does not use databases" to enable databases.
#. Click the Save button in the banner that appears in the navigation area.

.. _TASK Add Additional Databases:

Add Additional Databases
++++++++++++++++++++++++
Please navigate to the overview page of the project you wish to modify and click the Databases icon ( |Databases Icon| )
in the left toolbar.

Take note of any instruction provided at the top of the page and keep in mind that Databases are managed in groups because
each Cascade project is connected to multiple environments, each one with their own copy of the Databases to use.

*Note:* You can add as many database groups as your application needs by repeating the instructions below. To access these
additional databases there is a pager provided to the right of the add button or on the margin of each asset group.

Step 1: Select a name
---------------------
Locate the plus icon (|Plus Icon Blue|) near the top middle of the form.

#. To select the name you wish to use, start typing in the area where the dropdown select is to the left of the plus
   icon (|Plus Icon Blue|), a search dropdown will appear listing the names of the other database groups.
#. Click the "Create [what you typed]" option from that list to create the database group.

To use the system default naming:

#. Click the plus icon (|Plus Icon Blue|) to open the add database group form.

Step 2: Adjust databases per environment
----------------------------------------
By default, each database generated by Cascade will have unique credentials and be generated based on the name provided
in Step 1.

For each environment in the database group, do the following:

#. Review the database name and credentials to ensure they are correct for your application.
#. If adjustments are desired, make them by editing the form values. Cascade will create grants on the databases when
   the databases are initialized later.

When you are satisfied with the database naming and credentials:

#. Click the save button in the banner to submit the form.
#. Proceed to Step 3 to create the databases and grants.

|Project Databases Example|

Step 3: Initialize databases
----------------------------
The final step is to initialize the databases.

#. Navigate to the project overview dashboard.
#. For each environment listed, find the "Initialize" button for each database and click it to create an empty database
   using the credentials you specified.

Step 4: Migrate databases (optional)
------------------------------------
For new projects this step is not necessary. For a pre-existing project or continuing efforts, database migration will be
needed to seed the hosting environments initially.

As mentioned previously in this guide, uploading databases to your hosting system is handled through conventional
means, and access to those endpoints is handled by Contegix support. We have support for SFTP, Rsync, and other common
tools. Please refer to the documentation provided to you and reach out to support if you have any questions.