Addition of detailed MTA deployment actions

guides/databases-postgres.md

@@ -311,6 +311,78 @@ When deploying to Cloud Foundry, this can be accomplished by providing a simple
 
 5. Finally, package and deploy that, for example using [MTA-based deployment](deployment/to-cf#build-mta).
 
+## Step by Step Guide to add PostgreSQL to an existing project and deploy to BTP
+**Prerequisites:** 
+1. An existing instance of PostgreSQL running. For this example the instance name `my-postgres-db` is used.
+2. Service definition(s) and data model are in place (content in /srv and /db folder)
+
+**Steps:**
+1. Addition of Postgres dependencies
+   - `npm install @cap-js/postgres`
+   - This automatically hooks itself into the production profile of CAP. Once the CAP service is deployed in the BTP and the production profile is active, the Postgres adapter is used.
+2. Addition of the standard CAP dependencies
+    - `cds add xsuaa,mta --for production`
+3. Modify the mta.yaml introducing the following changes
+    1.  Add the PG instance as existing service to the 'resource' section of the mta.yaml
+    ```yaml
+      - name: my-postgres-db
+        type: org.cloudfoundry.existing-service
+    ```
+    2. In order to deploy the data model to the PG instance as part of the standard deployment. A deployer task/module must be added. 
+          - Make sure to use the type `hdb` and NOT `nodejs` as the nodejs type will try to restart the service over and over again. 
+          - The deployer path points to a gen/pg directory we need to create as part of the deployment process. See next step.
+          - The deployer also defines the dependency/binding to the postgres instance to have the credentials available at deploy time.
+    ```yaml
+      - name: pg-db-deployer
+        type: hdb
+        path: gen/pg
+        parameters:
+            buildpack: nodejs_buildpack
+        requires:
+            - name: my-postgres-db
+    ```
+    3. To generate the content the deployer module uses, we reference a shell script in the `custom` builder section in the begining of the the mta.yaml. The complete section should look like this:
+    ```yaml
+      build-parameters:
+        before-all:
+          - builder: custom
+            commands:
+              - npx cds build --production
+              - ./scripts/pgbuild.sh
+    ```
+    4. The shell script specified in the previous step is a simple combination of all the commands outlined in the CAP documentation. It creates the necessary artifacts in the gen/pg directory.
+        - Create a directory /scripts in the root of the project
+        - Create a file pgbuild.sh in the /scripts directory and change the permissions to make it executable: `chmod +x pgbuild.sh`
+        - Add the following content to the pgbuild.sh file:
+        ```bash
+        #!/usr/bin/env bash
+
+        echo ** Starting Postgres build **
+
+        echo - creating dir gen/pg/db -
+        mkdir -p gen/pg/db
+
+        echo - compiling model -
+        cds compile '*' > gen/pg/db/csn.json
+
+        echo - copy .csv files -
+        cp -r db/data gen/pg/db/data
+
+        echo '{"dependencies": { "@sap/cds": "*", "@cap-js/postgres": "*"},  "scripts": {    "start": "cds-deploy",}}' > gen/pg/package.json
+
+        ```
+    5. Add dependencies to your CAP service module to a. create a binding to the postgres db and b. wait for the deployer to finish before deploying the service. 
+    ```yaml
+        requires:
+            - name: my-postgres-db
+            - name: pg-db-deployer
+    ```
+4. Deploy the service to the BTP
+    - `mbt build`
+    - `cf deploy mta_archives/<your-service>.mtar`
+
+
+
 ## Automatic Schema Evolution { #schema-evolution }
 
 When redeploying after you changed your CDS models, like adding fields, automatic schema evolution is applied. Whenever you  run `cds deploy` (or `cds-deploy`) it executes these steps: