feat(cloud_sql/postgres): update to V2 sample (GoogleCloudPlatform#1633)

Author: jsimonweb

cloud_sql/postgres/pdo/README.md

@@ -28,7 +28,7 @@ Instructions are provided below for using the proxy with a TCP connection or a
 Unix domain socket. On Linux or macOS, you can use either option, but the
 Windows proxy requires a TCP connection.
 
-### Unix Socket mode
+### Launch proxy with Unix Domain Socket
 
 NOTE: this option is currently only supported on Linux and macOS. Windows users
 should use the TCP option.
@@ -37,22 +37,16 @@ To use a Unix socket, you'll need to create a directory and give access to the
 user running the proxy:
 
 ```bash
-sudo mkdir /path/to/the/new/directory
-sudo chown -R $USER /path/to/the/new/directory
+sudo mkdir /cloudsql
+sudo chown -R $USER /cloudsql
 ```
 
-You'll also need to initialize an environment variable pointing to the directory
-you just created:
-
-```bash
-export DB_SOCKET_DIR=/path/to/the/new/directory
-```
-
-Use these terminal commands to initialize other environment variables as well:
+Use these terminal commands to initialize environment variables:
 
 ```bash
 export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account/key.json
-export INSTANCE_CONNECTION_NAME='<MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>'
+export INSTANCE_CONNECTION_NAME='<PROJECT-ID>:<INSTANCE-REGION>:<INSTANCE-NAME>'
+export INSTANCE_UNIX_SOCKET='/cloudsql/<PROJECT-ID>:<INSTANCE-REGION>:<INSTANCE-NAME>'
 export DB_USER='<DB_USER_NAME>'
 export DB_PASS='<DB_PASSWORD>'
 export DB_NAME='<DB_NAME>'
@@ -66,22 +60,22 @@ safe.
 Then use the following command to launch the proxy in the background:
 
 ```bash
-./cloud_sql_proxy -dir=$DB_SOCKET_DIR --instances=$INSTANCE_CONNECTION_NAME --credential_file=$GOOGLE_APPLICATION_CREDENTIALS &
+./cloud_sql_proxy -dir=/cloudsql --instances=$INSTANCE_CONNECTION_NAME --credential_file=$GOOGLE_APPLICATION_CREDENTIALS &
 ```
 
-### TCP mode
+### Launch proxy with TCP
 
 To run the sample locally with a TCP connection, set environment variables and
 launch the proxy as shown below.
 
-#### Linux / macOS
+#### Linux / Mac OS
 
 Use these terminal commands to initialize environment variables:
 
 ```bash
 export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account/key.json
-export INSTANCE_CONNECTION_NAME='<MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>'
-export DB_HOST='127.0.0.1'
+export INSTANCE_CONNECTION_NAME='<PROJECT-ID>:<INSTANCE-REGION>:<INSTANCE-NAME>'
+export INSTANCE_HOST='127.0.0.1'
 export DB_USER='<DB_USER_NAME>'
 export DB_PASS='<DB_PASSWORD>'
 export DB_NAME='<DB_NAME>'
@@ -104,7 +98,7 @@ Use these PowerShell commands to initialize environment variables:
 
 ```bash
 $env:GOOGLE_APPLICATION_CREDENTIALS="<CREDENTIALS_JSON_FILE>"
-$env:DB_HOST="127.0.0.1"
+$env:INSTANCE_HOST="127.0.0.1"
 $env:DB_USER="<DB_USER_NAME>"
 $env:DB_PASS="<DB_PASSWORD>"
 $env:DB_NAME="<DB_NAME>
@@ -141,7 +135,7 @@ To run on App Engine Standard, create an App Engine project by following the
 setup for these
 [instructions](https://cloud.google.com/appengine/docs/standard/php7/quickstart#before-you-begin).
 
-First, update `app.standard.yaml` with the correct values to pass the
+First, update [app.standard.yaml](app.standard.yaml) with the correct values to pass the
 environment variables into the runtime.
 
 Next, the following command will deploy the application to your Google Cloud
@@ -156,17 +150,21 @@ To run on App Engine Flex, create an App Engine project by following the setup
 for these
 [instructions](https://cloud.google.com/appengine/docs/standard/php7/quickstart#before-you-begin).
 
-First, update `app.flex.yaml` with the correct values to pass the environment
+First, update [app.flex.yaml](app.flex.yaml) with the correct values to pass the environment
 variables into the runtime.
 
 To use a TCP connection instead of a Unix socket to connect your sample to your
-Cloud SQL instance on App Engine, make sure to uncomment the `DB_HOST`
+Cloud SQL instance on App Engine, make sure to uncomment the `INSTANCE_HOST`
 field under `env_variables`. Also make sure to remove the uncommented
 `beta_settings` and `cloud_sql_instances` fields and replace them with the
 commented `beta_settings` and `cloud_sql_instances` fields.
 
-Then, make sure that the service account
-`service-{PROJECT_NUMBER}>@gae-api-prod.google.com.iam.gserviceaccount.com` has
+Then, make sure that the App Engine default service account
+`<PROJECT-ID>@appspot.gserviceaccount.com` has
+the IAM role `Cloud SQL Client`.
+
+Also, make sure that the Cloud Build service account
+`cloudbuild@<PROJECT-ID>.iam.gserviceaccount.com` has
 the IAM role `Cloud SQL Client`.
 
 Next, the following command will deploy the application to your Google Cloud

cloud_sql/postgres/pdo/app.flex.yaml

@@ -19,23 +19,23 @@ env: flex
 # something like https://cloud.google.com/secret-manager/ to help keep secrets
 # secret.
 env_variables:
-  INSTANCE_CONNECTION_NAME: "<MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>"
-  DB_USER: my-db-user
-  DB_PASS: my-db-pass
-  DB_NAME: my-db
+  INSTANCE_UNIX_SOCKET: /cloudsql/<PROJECT-ID>:<INSTANCE-REGION>:<INSTANCE-NAME>
+  DB_USER: <YOUR_DB_USER_NAME>
+  DB_PASS: <YOUR_DB_PASSWORD>
+  DB_NAME: <YOUR_DB_NAME>
 
   # TCP domain socket setup; uncomment if using a TCP domain socket
-  # DB_HOST: 172.17.0.1
+  # INSTANCE_HOST: 172.17.0.1
 
 # Choose to enable either a TCP or Unix domain socket for your database
 # connection:
 # Enable a Unix domain socket:
 beta_settings:
-  cloud_sql_instances: "<MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>"
+  cloud_sql_instances: "<PROJECT-ID>:<INSTANCE-REGION>:<INSTANCE-NAME>"
 
 # Enable a TCP domain socket:
 # beta_settings:
-#   cloud_sql_instances: <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>=tcp:5432
+#   cloud_sql_instances: <PROJECT-ID>:<INSTANCE-REGION>:<INSTANCE-NAME>=tcp:5432
 
 runtime_config:
   document_root: .

cloud_sql/postgres/pdo/app.standard.yaml

@@ -17,10 +17,10 @@ runtime: php74
 # Remember - storing secrets in plaintext is potentially unsafe. Consider using
 # something like https://cloud.google.com/secret-manager/ to help keep secrets secret.
 env_variables:
-  INSTANCE_CONNECTION_NAME: <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
-  DB_USER: my-db-user
-  DB_PASS: my-db-pass
-  DB_NAME: my-db
+  INSTANCE_UNIX_SOCKET: /cloudsql/<PROJECT-ID>:<INSTANCE-REGION>:<INSTANCE-NAME>
+  DB_USER: <YOUR_DB_USER_NAME>
+  DB_PASS: <YOUR_DB_PASSWORD>
+  DB_NAME: <YOUR_DB_NAME>
 
 # Defaults to "serve index.php" and "serve public/index.php". Can be used to
 # serve a custom PHP front controller (e.g. "serve backend/index.php") or to

cloud_sql/postgres/pdo/src/DBInitializer.php

@@ -0,0 +1,90 @@
+<?php
+/*
+ * Copyright 2022 Google LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+# [START cloud_sql_postgres_pdo_connect_tcp]
+namespace Google\Cloud\Samples\CloudSQL\Postgres;
+
+use PDO;
+use PDOException;
+use RuntimeException;
+use TypeError;
+
+class DatabaseTcp
+{
+    public static function initTcpDatabaseConnection(): PDO
+    {
+        try {
+            // Note: Saving credentials in environment variables is convenient, but not
+            // secure - consider a more secure solution such as
+            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
+            // keep secrets safe.
+            $username = getenv('DB_USER'); // e.g. 'your_db_user'
+            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
+            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
+            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)
+
+            // Connect using TCP
+            $dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $instanceHost);
+
+            // Connect to the database
+            $conn = new PDO(
+                $dsn,
+                $username,
+                $password,
+                # [START_EXCLUDE]
+                # [START cloud_sql_postgres_pdo_timeout]
+                // Here we set the connection timeout to five seconds and ask PDO to
+                // throw an exception if any errors occur.
+                [
+                    PDO::ATTR_TIMEOUT => 5,
+                    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
+                ]
+                # [END cloud_sql_postgres_pdo_timeout]
+                # [END_EXCLUDE]
+            );
+        } catch (TypeError $e) {
+            throw new RuntimeException(
+                sprintf(
+                    'Invalid or missing configuration! Make sure you have set ' .
+                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
+                        'The PHP error was %s',
+                    $e->getMessage()
+                ),
+                $e->getCode(),
+                $e
+            );
+        } catch (PDOException $e) {
+            throw new RuntimeException(
+                sprintf(
+                    'Could not connect to the Cloud SQL Database. Check that ' .
+                        'your username and password are correct, that the Cloud SQL ' .
+                        'proxy is running, and that the database exists and is ready ' .
+                        'for use. For more assistance, refer to %s. The PDO error was %s',
+                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
+                    $e->getMessage()
+                ),
+                $e->getCode(),
+                $e
+            );
+        }
+
+        return $conn;
+    }
+}
+# [END cloud_sql_postgres_pdo_connect_tcp]