Upsun Flex: postgresql replication

Author: catplat

sites/upsun/src/add-services/postgresql.md renamed to sites/upsun/src/add-services/postgresql/_index.md

@@ -8,6 +8,10 @@ PostgreSQL is a high-performance, standards-compliant relational SQL database.
 
 See the [PostgreSQL documentation](https://www.postgresql.org/docs/9.6/index.html) for more information.
 
+{{% note theme="info" title="Note" %}}
+The [example](#usage-example) provided later in this topic is specific to using only a **primary** database. For details about using read-only replicas to improve performance of read-heavy applications, see the [PostgreSQL read-only replication](/add-services/postgresql/postgresql-readonly-replication.md) topic.
+{{% /note %}}
+
 ## Supported versions
 
 You can select the major version. But the latest compatible minor version is applied automatically and can’t be overridden.
@@ -111,6 +115,10 @@ export APP_POSTGRESQL_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.postgresql[0]
 
 ## Usage example
 
+{{% note theme="info" %}}
+Use the steps and sample code below if your application will connect to a **primary** PostgreSQL database. For details about using read-only replicas to improve performance of read-heavy applications, see the [PostgreSQL read-only replication](/add-services/postgresql/postgresql-readonly-replication.md) topic.
+{{% /note %}}
+
 ### 1. Configure the service
 
 To define the service, use the ``postgresql`` type:
@@ -400,7 +408,7 @@ A file very similar to this is generated automatically for your when using the `
 
 Access the service using the {{< vendor/name >}} CLI by running `{{< vendor/cli >}} sql`.
 
-You can also access it from your app container via [SSH](../development/ssh/_index.md).
+You can also access it from your app container via [SSH](/development/ssh/_index.md).
 From your [relationship data](#relationship-reference), you need: `POSTGRESQL_USERNAME`, `POSTGRESQL_HOST`, and `POSTGRESQL_PORT`.
 Then run the following command:
 
@@ -481,7 +489,7 @@ Taking a backup or a database export before doing so is strongly recommended.
 ## Sanitizing data
 
 To ensure people who review code changes can't access personally identifiable information stored in your database,
-[sanitize your preview environments](../development/sanitize-db/postgresql.md).
+[sanitize your preview environments](/development/sanitize-db/postgresql.md).
 
 ## Set locale for database
 

sites/upsun/src/add-services/postgresql/postgresql-readonly-replication.md

@@ -0,0 +1,108 @@
+---
+title: "PostgreSQL read-only replication"
+sidebarTitle: "Read-only replication"
+description: Configure and access read-only PostgreSQL replicas to ease the load on a primary database.
+---
+
+You can improve the performance of read-heavy applications by defining read-only replicas of your PostgreSQL database and then connecting your applications to those replicas. 
+
+Examples of read-heavy applications include: 
+- Listing pages or dashboards
+- Reporting or analytics jobs
+- Background jobs that frequently query data
+
+{{< note theme="info" title="Note" >}}
+- **Replication is asynchronous**: Delays of a few milliseconds might occur between writes on the primary database and reads on the replica database.
+- **Replicas are read-only**: This restriction ensures data consistency and integrity. Attempts to modify data will result in an SQL error.
+{{< /note >}}
+
+### Replica scope and sharing services {#replica-scope-sharing-services}
+PostgreSQL services (which provide access to databases and replicas) defined in a project cannot be accessed by or shared with applications in other projects. 
+
+
+
+## 1. Configure the primary and replica services 
+
+The following code fragment defines two MariaDB services: a primary and a replica. You can use this fragment as a template by copying it into your `services.yaml` or `application.yaml` file. 
+
+Be sure to: 
+- Replace `<VERSION>` with the [supported PostgreSQL version](/add-services/postgresql/_index.md#supported-versions) that you need. Use the same version number for the primary and replica services.
+- **Important:** Use `replicator` as the endpoint name when you define the replica service. This is a special endpoint name that the replica service uses to connect to the database.
+
+```yaml {configFile="services"}
+services:
+  db:
+    type: postgresql:<VERSION>
+    configuration:
+      extensions:
+        - postgis
+      endpoints:
+        replicator:
+          replication: true
+
+  db-replica1:
+    type: postgres-replica:<VERSION>
+    configuration:
+      endpoints:
+        postgresql:
+          default_database: main
+      extensions:
+        - postgis
+    relationships: 
+      primary: db:replicator # Do not change the name `primary`. The service expects to receive this name.
+
+  db-replica2:
+    type: postgres-replica:<VERSION>
+    configuration:
+      endpoints:
+        postgresql:
+          default_database: main
+      extensions:
+        - postgis
+    relationships: 
+      primary: db:replicator # Do not change the name `primary`. The service expects to receive this name.
+```
+
+
+### How it works
+
+Using the sample code fragment above: 
+
+1. After you define the replicator endpoints, the primary service creates a `replicator` user that has permission to replicate the database. You must specify `replicator` as the endpoint name, as described at the start of this topic. 
+
+    ```yaml
+    endpoints:
+      replicator:
+        replication: true
+    ```
+
+2. In the replica services (in this example, db-replica1 and db-replica2), defining the relationship `primary: db:replicator` ensures that the service can connect to the primary database as the `replicator` user. 
+
+    ```yaml
+    relationships:
+      primary: db:replicator
+    ```
+    
+The `db-replica1` and `db-replica2` replica services continuously stream data from the primary endpoint, maintaining a read-only copy of the primary database content. Write operations are not permitted on the replicas. 
+
+
+## 2. Define the relationship between the application and the replicas
+
+Even if your application won't access the replication endpoint, you must expose the endpoint to an application as a relationship so that you can connect to it over SSH.
+
+Add a new relationship to your application container, as shown below:
+
+```yaml {configFile="app"}
+name: myapp
+
+[...]
+
+# Relationships enable an app container's access to a service.
+relationships:
+  # More information: https://fixed.docs.upsun.com/anchors/fixed/app/reference/relationships/
+  database:
+    service: db
+    endpoint: main
+  database-readonly:
+    service: db-replica
+```