doc updates and notation update postgresql mirror scripts

Author: Mike Swantek

.gitignore

@@ -14,3 +14,4 @@ __pycache__
 # Local-only Bicep parameter overrides
 infra/*.local.bicepparam
 infra/*.local.bicepparam.json
+copy.main.bicepparam

README.md

@@ -223,6 +223,7 @@ Supporting documentation
 |----------|-------------|
 | [Deployment Guide](./docs/DeploymentGuide.md) | Complete deployment instructions |
 | [Post Deployment Steps](./docs/post_deployment_steps.md) | Verify your deployment |
+| [PostgreSQL Mirroring](./docs/postgresql_mirroring.md) | Create the Fabric connection and mirror PostgreSQL |
 | [Parameter Guide](./docs/PARAMETER_GUIDE.md) | Configure deployment parameters |
 | [Quota Check Guide](./docs/quota_check.md) | Check Azure OpenAI quota availability |
 

docs/postgresql_mirroring.md

@@ -0,0 +1,57 @@
+# PostgreSQL Mirroring to Fabric
+
+This guide explains how to complete PostgreSQL mirroring in Microsoft Fabric after deployment.
+
+## Why a Fabric Connection Is Required
+
+The Fabric mirroring API requires a Fabric "connection" object that stores the PostgreSQL endpoint and credentials. The mirror call only accepts a `connectionId` and database name, so a valid Fabric connection must exist before mirroring can be created.
+
+## Prerequisites
+
+- Deployment finished, and PostgreSQL Flexible Server exists.
+- Post-provision prep ran (it creates the `fabric_user` role and sets required PostgreSQL flags).
+- You can sign in to Fabric (app.fabric.microsoft.com) with access to the workspace.
+
+## Step 1: Confirm PostgreSQL Details
+
+Get the PostgreSQL server FQDN and database name:
+
+- FQDN: from `azd env get-value postgreSqlServerFqdn`
+- Database name: `postgres` (default) or your custom DB
+
+## Step 2: Create the Fabric Connection (UI)
+
+1. Open the Fabric workspace.
+2. Go to **Settings** -> **Manage connections and gateways**.
+3. Select **New connection** -> **PostgreSQL**.
+4. Enter:
+   - Server: PostgreSQL FQDN
+   - Database: your database name
+   - User: `fabric_user`
+   - Password: value from Key Vault secret `postgres-fabric-user-password`
+5. Save and copy the **Connection ID**.
+
+## Step 3: Set the Connection ID in azd
+
+```powershell
+azd env set-value fabricPostgresConnectionId "<connection-id>"
+azd env set-value POSTGRES_DATABASE_NAME "postgres"
+```
+
+## Step 4: Create the Mirror
+
+Run the mirror script:
+
+```powershell
+./scripts/automationScripts/FabricWorkspace/Mirror/create_postgresql_mirror.ps1
+```
+
+## Verify
+
+- In Fabric, a mirrored database named `pg-mirror-<env>` should appear.
+- Re-running the script is safe; it will skip if the mirror already exists.
+
+## Notes
+
+- The deployment now skips the mirror step until a valid Fabric connection exists, so `azd up` will no longer fail on this step.
+- If you rotate passwords, update the Fabric connection in the workspace.

infra/main.bicep

@@ -295,6 +295,8 @@ param postgreSqlVersion string = '16'
 
 @description('PostgreSQL storage size in GB.')
 param postgreSqlStorageSizeGB int = 32
+@description('Generated value used when postgreSqlAdminPassword is left as the placeholder token.')
+param generatedPostgreSqlAdminPassword string = newGuid()
 
 // ========================================
 // FABRIC CAPACITY DEPLOYMENT
@@ -327,6 +329,10 @@ var effectiveKeyVaultResourceId = !empty(keyVaultResourceId)
   ? keyVaultResourceId
   : resourceId('Microsoft.KeyVault/vaults', keyVaultName)
 
+var effectivePostgreSqlAdminPassword = postgreSqlAdminPassword == '$(secretOrRandomPassword)'
+  ? '${uniqueString(subscription().id, resourceGroup().id, postgreSqlServerName)}!${replace(generatedPostgreSqlAdminPassword, '-', '')}'
+  : postgreSqlAdminPassword
+
 resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
   name: last(split(effectiveKeyVaultResourceId, '/'))
 }
@@ -372,7 +378,7 @@ module postgreSqlFlexibleServer 'br/public:avm/res/db-for-postgre-sql/flexible-s
     skuName: postgreSqlSkuName
     tier: postgreSqlTier
     administratorLogin: postgreSqlAdminLogin
-    administratorLoginPassword: postgreSqlAdminPassword
+    administratorLoginPassword: effectivePostgreSqlAdminPassword
     managedIdentities: {
       systemAssigned: true
     }
@@ -387,7 +393,7 @@ module postgreSqlFlexibleServer 'br/public:avm/res/db-for-postgre-sql/flexible-s
 resource postgreSqlAdminSecret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = if (deployPostgreSql && enablePostgreSqlKeyVaultSecret) {
   name: '${keyVault.name}/${postgreSqlAdminSecretName}'
   properties: {
-    value: postgreSqlAdminPassword
+    value: effectivePostgreSqlAdminPassword
   }
 }
 

infra/main.bicepparam

@@ -74,7 +74,7 @@ param postgreSqlStorageSizeGB = 32
 
 param deployGroundingWithBing = false
 param deployAiFoundry = true
-param deployAiFoundrySubnet = true
+param deployAiFoundrySubnet = false
 param deployAppConfig = true
 param deployKeyVault = true
 param deployVmKeyVault = readEnvironmentVariable('DEPLOY_VM_KEY_VAULT', 'true') == 'true'
@@ -93,7 +93,7 @@ param sideBySideDeploy = readEnvironmentVariable('SIDE_BY_SIDE', 'true') == 'tru
 param deploySoftware = false
 param deployApim = false
 param deployAfProject = true
-param deployAAfAgentSvc = true
+param deployAAfAgentSvc = false
 param enableAgenticRetrieval = readEnvironmentVariable('ENABLE_AGENTIC_RETRIEVAL', 'false') == 'true'
 
 // ========================================

scripts/automationScripts/FabricWorkspace/mirror/create_postgresql_mirror.ps1

@@ -140,6 +140,20 @@ if (-not $fabricToken) { Warn "Cannot acquire Fabric API token; ensure az login.
 $fabricHeaders = New-SecureHeaders -Token $fabricToken
 $apiRoot = 'https://api.fabric.microsoft.com/v1'
 
+# Guard: skip until the Fabric PostgreSQL connection exists
+if ($ConnectionId) {
+  try {
+    $connections = Invoke-SecureRestMethod -Uri "$apiRoot/connections" -Headers $fabricHeaders -Method Get -Description "Fabric connections"
+    $match = $connections.value | Where-Object { $_.id -eq $ConnectionId }
+    if (-not $match) {
+      Warn "FABRIC_POSTGRES_CONNECTION_ID not found in Fabric. Create the connection and rerun."
+      exit 0
+    }
+  } catch {
+    Warn "Unable to validate Fabric connection ID; continuing with mirror attempt."
+  }
+}
+
 if ($postgreSqlSystemAssignedPrincipalId) {
   $roleAssignmentBody = @{
     principal = @{