chore: simplify field type inside spec and add docs

Signed-off-by: Gabriele Quaresima <[email protected]>

api/v1/publication_types.go

@@ -68,15 +68,12 @@ type PublicationSpec struct {
 // +kubebuilder:validation:XValidation:rule="(has(self.allTables) && !has(self.objects)) || (!has(self.allTables) && has(self.objects))",message="allTables and objects are not compatible"
 type PublicationTarget struct {
 	// All tables should be publicated
-	AllTables *PublicationTargetAllTables `json:"allTables,omitempty"`
+	AllTables bool `json:"allTables,omitempty"`
 
 	// Just the following schema objects
 	Objects []PublicationTargetObject `json:"objects,omitempty"`
 }
 
-// PublicationTargetAllTables means all tables should be publicated
-type PublicationTargetAllTables struct{}
-
 // PublicationTargetObject is an object to publicate
 type PublicationTargetObject struct {
 	// The schema to publicate

config/crd/bases/postgresql.cnpg.io_publications.yaml

@@ -102,7 +102,7 @@ spec:
                 properties:
                   allTables:
                     description: All tables should be publicated
-                    type: object
+                    type: boolean
                   objects:
                     description: Just the following schema objects
                     items:

docs/src/cloudnative-pg.v1.md

@@ -4116,7 +4116,7 @@ desired state that was synchronized</p>
 <thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
 <tbody>
 <tr><td><code>allTables</code> <B>[Required]</B><br/>
-<a href="#postgresql-cnpg-io-v1-PublicationTargetAllTables"><i>PublicationTargetAllTables</i></a>
+<i>bool</i>
 </td>
 <td>
    <p>All tables should be publicated</p>
@@ -4132,19 +4132,6 @@ desired state that was synchronized</p>
 </tbody>
 </table>
 
-## PublicationTargetAllTables     {#postgresql-cnpg-io-v1-PublicationTargetAllTables}
-
-
-**Appears in:**
-
-- [PublicationTarget](#postgresql-cnpg-io-v1-PublicationTarget)
-
-
-<p>PublicationTargetAllTables means all tables should be publicated</p>
-
-
-
-
 ## PublicationTargetObject     {#postgresql-cnpg-io-v1-PublicationTargetObject}
 
 

docs/src/declarative_publication_subscription_management.md

@@ -0,0 +1,135 @@
+# Declarative Publication/Subscription Management 
+
+Declarative publication/subscription management enables users to set up
+logical replication via new Custom Resource Definitions (CRD)
+- `Database` ,
+- `Publication`,
+- `Subscription`,
+
+Database CRD is widely discussed in
+["Declarative database management"](declarative_database_management.md) section.
+
+Logical replication is set up between one source cluster with publication 
+and one destination cluster that is subscribed to that publication.
+
+### Example: Simple Publication Declaration
+
+A `Publication` object is managed by the instance manager of the source cluster's
+primary instance.
+Below is an example of a basic `Publication` configuration:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Publication
+metadata:
+  name: pub-one
+spec:
+  name: pub
+  dbname: cat
+  cluster:
+    name: source-cluster
+  target:
+    allTables: true
+```
+
+The `dbname` field specifies the database the publication is applied to.
+Once the reconciliation cycle is completed successfully, the `Publication` 
+status will show a `ready` field set to `true` and an empty `error` field.
+
+### Publication Deletion and Reclaim Policies
+
+A finalizer named `cnpg.io/deletePublication` is automatically added
+to each `Publication` object to control its deletion process.
+
+By default, the `publicationReclaimPolicy` is set to `retain`, which means
+that if the `Publication` object is deleted, the actual PostgreSQL publication
+is retained for manual management by an administrator.
+
+Alternatively, if the `publicationReclaimPolicy` is set to `delete`,
+the PostgreSQL publication will be automatically deleted when the `Publication`
+object is removed.
+
+### Example: Publication with Delete Reclaim Policy
+
+The following example illustrates a `Publication` object with a `delete`
+reclaim policy:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Publication
+metadata:
+  name: pub-one
+spec:
+  name: pub
+  dbname: cat
+  publicationReclaimPolicy: delete
+  cluster:
+    name: source-cluster
+  target:
+    allTables: true
+```
+
+In this case, when the `Publication` object is deleted, the corresponding PostgreSQL publication will also be removed automatically.
+
+
+### Example: Simple Subscription Declaration
+
+A `Subscription` object is managed by the instance manager of the destination cluster's
+primary instance.
+Below is an example of a basic `Subscription` configuration:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Subscription
+metadata:
+  name: sub-one
+spec:
+  name: sub
+  dbname: cat
+  publicationName: pub
+  cluster:
+    name: destination-cluster
+  externalClusterName: source-cluster
+```
+
+The `dbname` field specifies the database the publication is applied to.
+The `publicationName` field specifies the name of the publication the subscription refers to.
+The `externalClusterName` field specifies the external cluster the publication belongs to.
+
+Once the reconciliation cycle is completed successfully, the `Subscription`
+status will show a `ready` field set to `true` and an empty `error` field.
+
+### Subscription Deletion and Reclaim Policies
+
+A finalizer named `cnpg.io/deleteSubscription` is automatically added
+to each `Subscription` object to control its deletion process.
+
+By default, the `subscriptionReclaimPolicy` is set to `retain`, which means
+that if the `Subscription` object is deleted, the actual PostgreSQL publication
+is retained for manual management by an administrator.
+
+Alternatively, if the `subscriptionReclaimPolicy` is set to `delete`,
+the PostgreSQL publication will be automatically deleted when the `Publication`
+object is removed.
+
+### Example: Subscription with Delete Reclaim Policy
+
+The following example illustrates a `Subscription` object with a `delete`
+reclaim policy:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Subscription
+metadata:
+  name: sub-one
+spec:
+  name: sub
+  dbname: cat
+  publicationName: pub
+  subscriptionReclaimPolicy: delete
+  cluster:
+    name: destination-cluster
+  externalClusterName: source-cluster
+```
+
+In this case, when the `Subscription` object is deleted, the corresponding PostgreSQL publication will also be removed automatically.

internal/management/controller/publication_controller_sql.go

@@ -176,7 +176,7 @@ func (r *PublicationReconciler) dropPublication(ctx context.Context, obj *apiv1.
 }
 
 func toPublicationTargetSQL(obj *apiv1.PublicationTarget) string {
-	if obj.AllTables != nil {
+	if obj.AllTables {
 		return "FOR ALL TABLES"
 	}
 

tests/e2e/asserts_test.go

@@ -476,6 +476,30 @@ func AssertCreateTestDataWithDatabaseName(
 	})
 }
 
+// AssertCreateTestDataWithDatabaseName create test data in a given database.
+func AssertCreateTableWithDatabaseName(
+	env *testsUtils.TestingEnvironment,
+	namespace,
+	clusterName,
+	databaseName,
+	tableName string,
+) {
+	By(fmt.Sprintf("creating table in cluster %v", clusterName), func() {
+		forward, conn, err := testsUtils.ForwardPSQLConnection(
+			env,
+			namespace,
+			clusterName,
+			databaseName,
+			apiv1.ApplicationUserSecretSuffix,
+		)
+		Expect(err).ToNot(HaveOccurred())
+		query := fmt.Sprintf("CREATE TABLE IF NOT EXISTS %v ();", tableName)
+		_, err = conn.Exec(query)
+		Expect(err).ToNot(HaveOccurred())
+		forward.Close()
+	})
+}
+
 type TableLocator struct {
 	Namespace   string
 	ClusterName string

tests/e2e/declarative_pub_sub_test.go

@@ -169,6 +169,10 @@ var _ = Describe("Declarative publication and subscription test", Label(tests.La
 
 				AssertDatabaseExists(namespace, primaryPodInfo.Name, dbname, true)
 			})
+			By("creating empty table inside destination database", func() {
+				AssertCreateTableWithDatabaseName(env, namespace, destinationClusterName, dbname, tableName)
+			})
+
 			By("applying Publication CRD manifest", func() {
 				CreateResourceFromFile(namespace, pubManifest)
 				pubObjectName, err = env.GetResourceNameFromYAML(pubManifest)
@@ -219,7 +223,7 @@ var _ = Describe("Declarative publication and subscription test", Label(tests.La
 
 				assertSubscriptionExists(namespace, primaryPodInfo.Name, sub)
 			})
-			By("creating a new data in the source cluster database", func() {
+			By("creating new data in the source cluster database", func() {
 				AssertCreateTestDataWithDatabaseName(env, namespace, sourceClusterName, dbname, tableName)
 			})
 

tests/e2e/fixtures/declarative_pub_sub/pub.yaml.template

@@ -8,4 +8,4 @@ spec:
   cluster:
     name: source-cluster
   target:
-    allTables: {}
+    allTables: true