Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Add syntax documentation for logical replication #23270

Merged
merged 14 commits into from
Jul 25, 2024
Merged

[docs] Add syntax documentation for logical replication #23270

Changes from 1 commit
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
b7f4a3d
Add syntax documentation for logical replication
dr0pdb Jul 24, 2024
0bd5e06
Fix missing semicolon in drop_replication_slot
dr0pdb Jul 24, 2024
4ba778d
Fix the description of USE_SNAPSHOT
dr0pdb Jul 24, 2024
0d70b3e
Improve language of assumptions in examples.
dr0pdb Jul 25, 2024
6b351ed
Fix grammar in create publication example.
dr0pdb Jul 25, 2024
4169886
Fix grammar in alter publication
dr0pdb Jul 25, 2024
8172bae
Improve grammar of SET table in alter publication
dr0pdb Jul 25, 2024
963b494
Improve grammar in limitation of create publication
dr0pdb Jul 25, 2024
9a147e9
Update docs/content/preview/api/ysql/the-sql-language/statements/stre…
dr0pdb Jul 25, 2024
328cfa5
Update docs/content/preview/api/ysql/the-sql-language/statements/ddl_…
dr0pdb Jul 25, 2024
6a01bc1
Update docs/content/preview/api/ysql/the-sql-language/statements/ddl_…
dr0pdb Jul 25, 2024
073deb5
Update docs/content/preview/api/ysql/the-sql-language/statements/ddl_…
dr0pdb Jul 25, 2024
08ac907
Describe the start replication example
dr0pdb Jul 25, 2024
929c2da
Include a full example in the start_replication case
dr0pdb Jul 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 21 additions & 3 deletions ...ent/preview/api/ysql/the-sql-language/statements/streaming_start_replication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,18 +38,36 @@ The log sequence number from where to start the streaming from.

The name of an option passed to the slot's logical decoding plugin.

The applicable options accepted by the command depends on the output plugin of the replication slot. They can be viewed in the respective documentation of the output plugin itself.

For `pgoutput` and `yboutput`, check the section [53.5.1. Logical Streaming Replication Parameters](https://www.postgresql.org/docs/11/protocol-logical-replication.html) in the PG documentation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to document somehow yboutput? Or say how/if it differes from pgoutput ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes but not in the syntax section. cc: @asrinivasanyb


For `wal2json`, refer to the [plugin documentation](https://github.com/eulerto/wal2json/tree/master?tab=readme-ov-file#parameters).

### *start_replication_option_value*

Optional value, in the form of a string constant, associated with the specified option.

## Example

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add brief summary - "Start replication from Replication Slot test_slot using LSN 0/2 and something something" (explain what is going on)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But what is 'pub'?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to document these options too https://www.postgresql.org/docs/current/protocol-logical-replication.html ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this example, we probably need a full example? So creating a table, a publication, and then starting replication.
And maybe even show the output of start_replication.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ddorian

Do we need to document these options too https://www.postgresql.org/docs/current/protocol-logical-replication.html ?

So these parameters depend on the output plugin chosen. These parameters are specific to pgoutput. I've added links to the respective documentation for pgoutput, yboutput and wal2json. If the user uses any other plugin, they have to find the documentation for that plugin.

In this example, we probably need a full example? So creating a table, a publication, and then starting replication.
And maybe even show the output of start_replication.

Good point. I've added one. We can't show the output of the start_replication as it streams data via copy protocol. The command doesn't output anything on the shell.

Assume that you have already created a replication slot `test_slot` with output plugin `pgoutput` or `yboutput`.
We need to follow a few steps before we can start streaming from a replication slot. Assume that a table with name `users` already exists in the database.

Create a publication `mypublication` which includes the table `users`.

```sql
yugabyte=# CREATE PUBLICATION mypublication FOR TABLE users;
```

Create a replication slot with name `test_slot` and output plugin `pgoutput`.

```sql
yugabyte=# CREATE_REPLICATION_SLOT test_slot LOGICAL pgoutput;
```

Start replication from the `test_slot` replication slot starting from LSN `0/2`. We also pass the `publication_names` parameter to the output plugin. `publication_names` is an output plugin parameter that is accepted by both `pgoutput` and `yboutput` to determine the tables to stream the data from.
Start replication from the `test_slot` replication slot starting from LSN `0/2`. We also pass the `publication_names` parameter with value `mypublication` to the output plugin. `publication_names` is an output plugin parameter that is accepted by both `pgoutput` and `yboutput` to determine the tables to stream the data from.

```sql
yugabyte=# START_REPLICATION test_slot LOGICAL 0/2 publication_names 'pub';
yugabyte=# START_REPLICATION test_slot LOGICAL 0/2 publication_names 'mypublication';
ddorian marked this conversation as resolved.
Show resolved Hide resolved
```

## See also
Expand Down