From 82b116386b1f2cb7f29395b5a693643e2fe46ab7 Mon Sep 17 00:00:00 2001 From: Hari Krishna Sunder Date: Sat, 25 May 2024 11:11:16 -0700 Subject: [PATCH 01/10] Add cron docs --- .../pg-extensions/_index.md | 1 + .../pg-extensions/extension-pgcron.md | 34 +++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/_index.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/_index.md index e4d3ebee66b8..4f52c392d43a 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/_index.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/_index.md @@ -41,6 +41,7 @@ YugabyteDB supports the following [PostgreSQL modules](https://www.postgresql.or | [fuzzystrmatch](extension-fuzzystrmatch/) | Provides several functions to determine similarities and distance between strings. | | hstore | Implements the hstore data type for storing sets of key-value pairs in a single PostgreSQL value.
For more information, see [hstore](https://www.postgresql.org/docs/11/hstore.html) in the PostgreSQL documentation. | | [passwordcheck](extension-passwordcheck/) | Checks user passwords whenever they are set with CREATE ROLE or ALTER ROLE. If a password is considered too weak, it is rejected. | +| [pg_cron](extension-pgcron/) | Provides a simple cron-based job scheduler that runs inside the database. | | [pgcrypto](extension-pgcrypto/) | Provides various cryptographic functions. | | [pg_stat_statements](extension-pgstatstatements/) | Provides a means for tracking execution statistics of all SQL statements executed by a server. | | pg_trgm | Provides functions and operators for determining the similarity of alphanumeric text based on trigram matching, as well as index operator classes that support fast searching for similar strings.
For more information, see [pg_trgm](https://www.postgresql.org/docs/11/pgtrgm.html) in the PostgreSQL documentation. | diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md new file mode 100644 index 000000000000..cfdf3691bb88 --- /dev/null +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md @@ -0,0 +1,34 @@ +--- +title: pg_cron extension +headerTitle: pg_cron extension +linkTitle: pg_cron +description: Using the pg_cron extension in YugabyteDB +menu: + preview: + identifier: extension-pgcron + parent: pg-extensions + weight: 20 +type: docs +--- + +The [pg_cron](https://github.com/citusdata/pg_cron) extension provides a cron-based job scheduler that runs inside the database. It uses the same syntax as regular cron, but it allows you to schedule YSQL commands directly from the database. You can also use '[1-59] seconds' to schedule a job based on an interval. + +## Enable pg_cron +This feature is {{}}. You can enable the feature using the `enable_pg_cron` flag. As it is a preview flag, you have to add it to `allowed_preview_flags_csv`. + +By default, pg_cron will run on the `yugabyte` database. You can change this by setting `ysql_cron_database_name` to your desired database name. + +To create a single-node cluster with pg_cron using [yugabyted](../../../reference/configuration/yugabyted/), use the following command: + +```sh +./bin/yugabyted start --master_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --tserver_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --ui false +``` + + +After the flags are set, run the following command on the cron database with superuser privileges. + +```sql +CREATE EXTENSION pg_cron; +``` + +For more information on how to schedule jobs refer to the [pg_cron readme](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md) From 0431990188e139dac0ab67d39641944839f66cbb Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Mon, 27 May 2024 11:18:34 +1000 Subject: [PATCH 02/10] minor edits --- .../pg-extensions/extension-pgcron.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md index cfdf3691bb88..0a30e3c9041e 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md @@ -3,6 +3,7 @@ title: pg_cron extension headerTitle: pg_cron extension linkTitle: pg_cron description: Using the pg_cron extension in YugabyteDB +techPreview: /preview/releases/versioning/#feature-availability menu: preview: identifier: extension-pgcron @@ -11,24 +12,24 @@ menu: type: docs --- -The [pg_cron](https://github.com/citusdata/pg_cron) extension provides a cron-based job scheduler that runs inside the database. It uses the same syntax as regular cron, but it allows you to schedule YSQL commands directly from the database. You can also use '[1-59] seconds' to schedule a job based on an interval. +The [pg_cron](https://github.com/citusdata/pg_cron) extension provides a cron-based job scheduler that runs inside the database. It uses the same syntax as regular cron, and allows you to schedule YSQL commands directly from the database. You can also use '[1-59] seconds' to schedule a job based on an interval. ## Enable pg_cron -This feature is {{}}. You can enable the feature using the `enable_pg_cron` flag. As it is a preview flag, you have to add it to `allowed_preview_flags_csv`. -By default, pg_cron will run on the `yugabyte` database. You can change this by setting `ysql_cron_database_name` to your desired database name. +As pg_cron is in tech preview, you must first enable the feature by setting the `enable_pg_cron` preview flag to true, and adding it to the `allowed_preview_flags_csv` flag, for both YB-Master and TB-TServer. -To create a single-node cluster with pg_cron using [yugabyted](../../../reference/configuration/yugabyted/), use the following command: +For example, to create a single-node cluster with pg_cron enabled using [yugabyted](../../../reference/configuration/yugabyted/), use the following command: ```sh ./bin/yugabyted start --master_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --tserver_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --ui false ``` +By default, pg_cron runs on the `yugabyte` database. You can change this by setting the `ysql_cron_database_name` flag to your desired database name. -After the flags are set, run the following command on the cron database with superuser privileges. +After the flags are set, run the following command on the cron database with superuser privileges: ```sql CREATE EXTENSION pg_cron; ``` -For more information on how to schedule jobs refer to the [pg_cron readme](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md) +For information on how to schedule jobs, refer to the [pg_cron readme](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). From 34ff423ff247c47d16cb9160a432d14ccd9ed8ca Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Mon, 27 May 2024 11:28:40 +1000 Subject: [PATCH 03/10] links --- .../explore/ysql-language-features/pg-extensions/_index.md | 2 +- .../ysql-language-features/pg-extensions/extension-pgcron.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/_index.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/_index.md index 4f52c392d43a..cd15fec115f9 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/_index.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/_index.md @@ -41,7 +41,6 @@ YugabyteDB supports the following [PostgreSQL modules](https://www.postgresql.or | [fuzzystrmatch](extension-fuzzystrmatch/) | Provides several functions to determine similarities and distance between strings. | | hstore | Implements the hstore data type for storing sets of key-value pairs in a single PostgreSQL value.
For more information, see [hstore](https://www.postgresql.org/docs/11/hstore.html) in the PostgreSQL documentation. | | [passwordcheck](extension-passwordcheck/) | Checks user passwords whenever they are set with CREATE ROLE or ALTER ROLE. If a password is considered too weak, it is rejected. | -| [pg_cron](extension-pgcron/) | Provides a simple cron-based job scheduler that runs inside the database. | | [pgcrypto](extension-pgcrypto/) | Provides various cryptographic functions. | | [pg_stat_statements](extension-pgstatstatements/) | Provides a means for tracking execution statistics of all SQL statements executed by a server. | | pg_trgm | Provides functions and operators for determining the similarity of alphanumeric text based on trigram matching, as well as index operator classes that support fast searching for similar strings.
For more information, see [pg_trgm](https://www.postgresql.org/docs/11/pgtrgm.html) in the PostgreSQL documentation. | @@ -60,6 +59,7 @@ YugabyteDB supports the following additional extensions, some of which you must | [HypoPG](extension-hypopg/) | Pre-bundled | Create hypothetical indexes to test whether an index can increase performance for problematic queries without consuming any actual resources. | | Orafce | Pre-bundled | Provides compatibility with Oracle functions and packages that are either missing or implemented differently in YugabyteDB and PostgreSQL. This compatibility layer can help you port your Oracle applications to YugabyteDB.
For more information, see the [Orafce](https://github.com/orafce/orafce) documentation. | | [PGAudit](../../../secure/audit-logging/audit-logging-ysql/) | Pre-bundled | The PostgreSQL Audit Extension (pgaudit) provides detailed session and/or object audit logging via the standard PostgreSQL logging facility. | +| [pg_cron](extension-pgcron/) | Pre-bundled | Provides a cron-based job scheduler that runs inside the database. | | [pg_hint_plan](../../query-1-performance/pg-hint-plan/#root) | Pre-bundled | Tweak execution plans using "hints", which are descriptions in the form of SQL comments.
For more information, see the [pg_hint_plan](https://pghintplan.osdn.jp/pg_hint_plan.html) documentation. | | pg_stat_monitor | Pre-bundled | A PostgreSQL query performance monitoring tool, based on the PostgreSQL pg_stat_statements module.
For more information, see the [pg_stat_monitor](https://docs.percona.com/pg-stat-monitor/index.html) documentation. | | [pgvector](extension-pgvector) | Pre-bundled | Allows you to store and query vectors, for use in vector similarity searching. | diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md index 0a30e3c9041e..2202a07774a8 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md @@ -18,7 +18,7 @@ The [pg_cron](https://github.com/citusdata/pg_cron) extension provides a cron-ba As pg_cron is in tech preview, you must first enable the feature by setting the `enable_pg_cron` preview flag to true, and adding it to the `allowed_preview_flags_csv` flag, for both YB-Master and TB-TServer. -For example, to create a single-node cluster with pg_cron enabled using [yugabyted](../../../reference/configuration/yugabyted/), use the following command: +For example, to create a single-node cluster with pg_cron enabled using [yugabyted](../../../../reference/configuration/yugabyted/), use the following command: ```sh ./bin/yugabyted start --master_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --tserver_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --ui false @@ -32,4 +32,4 @@ After the flags are set, run the following command on the cron database with sup CREATE EXTENSION pg_cron; ``` -For information on how to schedule jobs, refer to the [pg_cron readme](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). +For information on how to schedule jobs, refer to the [pg_cron](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md) documentation. From 1f0439e1f55b3132131ae23ac8e3c4088f6adc9a Mon Sep 17 00:00:00 2001 From: Hari Krishna Sunder Date: Tue, 30 Jul 2024 16:40:40 -0700 Subject: [PATCH 04/10] Update doc --- .../pg-extensions/extension-pgcron.md | 30 +++++++++++++++---- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md index 2202a07774a8..2556511f0ef0 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md @@ -14,22 +14,42 @@ type: docs The [pg_cron](https://github.com/citusdata/pg_cron) extension provides a cron-based job scheduler that runs inside the database. It uses the same syntax as regular cron, and allows you to schedule YSQL commands directly from the database. You can also use '[1-59] seconds' to schedule a job based on an interval. -## Enable pg_cron +## pg_cron in YugabyteDB +YugabyteDB supports all features of the pg_cron extension. -As pg_cron is in tech preview, you must first enable the feature by setting the `enable_pg_cron` preview flag to true, and adding it to the `allowed_preview_flags_csv` flag, for both YB-Master and TB-TServer. +YugabyteDB is a distributed database that operates on multiple nodes. pg_cron only runs on one of these nodes called the pg_cron leader. Only the pg_cron leader schedules and runs the cron jobs. The queries executed by the job will take advantage of all available resources in the cluster. The leader is automatically elected by the database. If the pg_cron leader node fails, another node is automatically elected as the new leader to ensure it is highly available. -For example, to create a single-node cluster with pg_cron enabled using [yugabyted](../../../../reference/configuration/yugabyted/), use the following command: +## Installation + +### 1. Enable the pg_cron feature +To enable pg_cron, add `enable_pg_cron` to the `allowed_preview_flags_csv` flag and then set the `enable_pg_cron` flag to true on both YB-Master and TB-TServer. +For example, to create a single-node cluster with pg_cron enabled using [yugabyted](../../../../reference/configuration/yugabyted/), use the following command: ```sh ./bin/yugabyted start --master_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --tserver_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --ui false ``` +### 2. Set the pg_cron database (optional) By default, pg_cron runs on the `yugabyte` database. You can change this by setting the `ysql_cron_database_name` flag to your desired database name. +{{< note >}} +- The database can be created after setting the flag. +- In order to change the database after the extension is created, you must drop the extension before changing the flag. +{{< /note >}} -After the flags are set, run the following command on the cron database with superuser privileges: + +### 3. Create and use the pg_cron extension +Create the extension as superuser on the cron database. +You can grant access to other users to use the extension. ```sql CREATE EXTENSION pg_cron; +-- optionally, grant usage to regular users: +GRANT USAGE ON SCHEMA cron TO elephant; ``` -For information on how to schedule jobs, refer to the [pg_cron](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md) documentation. +For information on how to schedule jobs, refer to the [README](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). + +{{< note title="Note" >}} +- It may take up to 60 seconds for job changes to get reflected on the pg_cron leader. +- When a new pg_cron leader is elected, no jobs are run for the first minute. Any job that was inflight on the failed node will not be retied, as their outcome is not known. +{{< /note >}} \ No newline at end of file From 79495537ee6383a32472f49cb9ad051253b69cf3 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Tue, 30 Jul 2024 21:26:56 -0400 Subject: [PATCH 05/10] format, edit --- .../Yugabyte/spelling-exceptions.txt | 1 + .../pg-extensions/extension-pgcron.md | 27 ++++++++++++------- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/.github/vale-styles/Yugabyte/spelling-exceptions.txt b/.github/vale-styles/Yugabyte/spelling-exceptions.txt index 5924953d9191..89114dbe3ef3 100644 --- a/.github/vale-styles/Yugabyte/spelling-exceptions.txt +++ b/.github/vale-styles/Yugabyte/spelling-exceptions.txt @@ -445,6 +445,7 @@ Patroni performant PgBouncer pgLoader +pg_cron Phabricator phaser phasers diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md index 2556511f0ef0..a7b2c30eed78 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md @@ -15,6 +15,7 @@ type: docs The [pg_cron](https://github.com/citusdata/pg_cron) extension provides a cron-based job scheduler that runs inside the database. It uses the same syntax as regular cron, and allows you to schedule YSQL commands directly from the database. You can also use '[1-59] seconds' to schedule a job based on an interval. ## pg_cron in YugabyteDB + YugabyteDB supports all features of the pg_cron extension. YugabyteDB is a distributed database that operates on multiple nodes. pg_cron only runs on one of these nodes called the pg_cron leader. Only the pg_cron leader schedules and runs the cron jobs. The queries executed by the job will take advantage of all available resources in the cluster. The leader is automatically elected by the database. If the pg_cron leader node fails, another node is automatically elected as the new leader to ensure it is highly available. @@ -22,34 +23,40 @@ YugabyteDB is a distributed database that operates on multiple nodes. pg_cron on ## Installation ### 1. Enable the pg_cron feature + To enable pg_cron, add `enable_pg_cron` to the `allowed_preview_flags_csv` flag and then set the `enable_pg_cron` flag to true on both YB-Master and TB-TServer. For example, to create a single-node cluster with pg_cron enabled using [yugabyted](../../../../reference/configuration/yugabyted/), use the following command: + ```sh ./bin/yugabyted start --master_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --tserver_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --ui false ``` ### 2. Set the pg_cron database (optional) + By default, pg_cron runs on the `yugabyte` database. You can change this by setting the `ysql_cron_database_name` flag to your desired database name. -{{< note >}} -- The database can be created after setting the flag. -- In order to change the database after the extension is created, you must drop the extension before changing the flag. -{{< /note >}} +You can create the database after setting the flag. + +To change the database after the extension is created, you must first drop the extension, and then change the flag. ### 3. Create and use the pg_cron extension + Create the extension as superuser on the cron database. -You can grant access to other users to use the extension. ```sql CREATE EXTENSION pg_cron; --- optionally, grant usage to regular users: +``` + +You can grant access to other users to use the extension. For example: + +```sql GRANT USAGE ON SCHEMA cron TO elephant; ``` -For information on how to schedule jobs, refer to the [README](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). +For information on how to schedule jobs, refer to the [pg_cron documentation](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). + +When running jobs, keep in mind the following: -{{< note title="Note" >}} - It may take up to 60 seconds for job changes to get reflected on the pg_cron leader. -- When a new pg_cron leader is elected, no jobs are run for the first minute. Any job that was inflight on the failed node will not be retied, as their outcome is not known. -{{< /note >}} \ No newline at end of file +- When a new pg_cron leader is elected, no jobs are run for the first minute. Any job that was in flight on the failed node will not be retried, as their outcome is not known. From 54c97f0b46176de2b9a116e906008b268f346fb6 Mon Sep 17 00:00:00 2001 From: Hari Krishna Sunder Date: Tue, 30 Jul 2024 21:18:50 -0700 Subject: [PATCH 06/10] updates --- .../pg-extensions/extension-pgcron.md | 42 ++++++++++--------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md index a7b2c30eed78..d67aaacadec3 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md @@ -18,31 +18,28 @@ The [pg_cron](https://github.com/citusdata/pg_cron) extension provides a cron-ba YugabyteDB supports all features of the pg_cron extension. -YugabyteDB is a distributed database that operates on multiple nodes. pg_cron only runs on one of these nodes called the pg_cron leader. Only the pg_cron leader schedules and runs the cron jobs. The queries executed by the job will take advantage of all available resources in the cluster. The leader is automatically elected by the database. If the pg_cron leader node fails, another node is automatically elected as the new leader to ensure it is highly available. +YugabyteDB is a distributed database that operates on multiple nodes. pg_cron only runs on one of these nodes called the pg_cron leader. Only the pg_cron leader schedules and runs the cron jobs. The queries executed by the job will take advantage of all available resources in the cluster. The database will automatically elect the leader node and ensure pg_cron is highly available and tolerant to node failures. -## Installation +### Enable and configure +To enable pg_cron, add `enable_pg_cron` to the `allowed_preview_flags_csv` flag and set the `enable_pg_cron` flag to true on all YB-Masters and YB-TServers. -### 1. Enable the pg_cron feature - -To enable pg_cron, add `enable_pg_cron` to the `allowed_preview_flags_csv` flag and then set the `enable_pg_cron` flag to true on both YB-Master and TB-TServer. - -For example, to create a single-node cluster with pg_cron enabled using [yugabyted](../../../../reference/configuration/yugabyted/), use the following command: +The pg_cron extension is installed on only one database, which stores the extensions data. The default cron database is `yugabyte`. You can change it by setting the `ysql_cron_database_name` flag on all YB-TServers. +For example, to create a single-node [yugabyted](../../../../reference/configuration/yugabyted/) cluster with pg_cron on database 'db1', use the following command: ```sh -./bin/yugabyted start --master_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --tserver_flags "enable_pg_cron=true,allowed_preview_flags_csv=enable_pg_cron" --ui false +./bin/yugabyted start --master_flags "allowed_preview_flags_csv={enable_pg_cron},enable_pg_cron=true" --tserver_flags "allowed_preview_flags_csv={enable_pg_cron},enable_pg_cron=true,ysql_cron_database_name=db1" --ui false ``` -### 2. Set the pg_cron database (optional) - -By default, pg_cron runs on the `yugabyte` database. You can change this by setting the `ysql_cron_database_name` flag to your desired database name. - -You can create the database after setting the flag. +{{< note title="Note" >}} +- The database can be created after setting the flag. +- If you need to run jobs in multiple databases, use `cron.schedule_in_database()`. +- In order to change the database after the extension is created, you must first drop the extension and then change the flag value. +{{< /note >}} -To change the database after the extension is created, you must first drop the extension, and then change the flag. - -### 3. Create and use the pg_cron extension +### Create and use Create the extension as superuser on the cron database. +You can then grant access to other users to use the extension. ```sql CREATE EXTENSION pg_cron; @@ -54,9 +51,14 @@ You can grant access to other users to use the extension. For example: GRANT USAGE ON SCHEMA cron TO elephant; ``` -For information on how to schedule jobs, refer to the [pg_cron documentation](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). +```sql +-- Call a stored procedure every 5 seconds +SELECT cron.schedule('process-updates', '5 seconds', 'CALL process_updates()'); +``` -When running jobs, keep in mind the following: +For information on how to schedule jobs, refer to the [README](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). -- It may take up to 60 seconds for job changes to get reflected on the pg_cron leader. -- When a new pg_cron leader is elected, no jobs are run for the first minute. Any job that was in flight on the failed node will not be retried, as their outcome is not known. +{{< note title="Note" >}} +- It may take up to 60 seconds for job changes to get picked up by the pg_cron leader. +- When a new pg_cron leader node is elected, no jobs are run for the first minute. Any job that were in flight on the failed node will not be retied, as their outcome is not known. +{{< /note >}} \ No newline at end of file From 5734e38cd9b404c7d449473e66771dd81a8f33cd Mon Sep 17 00:00:00 2001 From: Hari Krishna Sunder Date: Tue, 30 Jul 2024 21:18:50 -0700 Subject: [PATCH 07/10] updates --- .../pg-extensions/extension-pgcron.md | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md index d67aaacadec3..681013b10ea2 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md @@ -18,9 +18,11 @@ The [pg_cron](https://github.com/citusdata/pg_cron) extension provides a cron-ba YugabyteDB supports all features of the pg_cron extension. +YugabyteDB is a distributed database that operates on multiple nodes. pg_cron only runs on one of these nodes called the pg_cron leader. Only the pg_cron leader schedules and runs the cron jobs. The queries executed by the job will take advantage of all available resources in the cluster. The database will automatically elect the leader node and ensure pg_cron is highly available and tolerant to node failures. YugabyteDB is a distributed database that operates on multiple nodes. pg_cron only runs on one of these nodes called the pg_cron leader. Only the pg_cron leader schedules and runs the cron jobs. The queries executed by the job will take advantage of all available resources in the cluster. The database will automatically elect the leader node and ensure pg_cron is highly available and tolerant to node failures. ### Enable and configure + To enable pg_cron, add `enable_pg_cron` to the `allowed_preview_flags_csv` flag and set the `enable_pg_cron` flag to true on all YB-Masters and YB-TServers. The pg_cron extension is installed on only one database, which stores the extensions data. The default cron database is `yugabyte`. You can change it by setting the `ysql_cron_database_name` flag on all YB-TServers. @@ -30,16 +32,16 @@ For example, to create a single-node [yugabyted](../../../../reference/configura ./bin/yugabyted start --master_flags "allowed_preview_flags_csv={enable_pg_cron},enable_pg_cron=true" --tserver_flags "allowed_preview_flags_csv={enable_pg_cron},enable_pg_cron=true,ysql_cron_database_name=db1" --ui false ``` -{{< note title="Note" >}} -- The database can be created after setting the flag. -- If you need to run jobs in multiple databases, use `cron.schedule_in_database()`. -- In order to change the database after the extension is created, you must first drop the extension and then change the flag value. -{{< /note >}} +You can create the database after setting the flag. +In order to change the database after the extension is created, you must first drop the extension and then change the flag value. + ### Create and use + Create the extension as superuser on the cron database. You can then grant access to other users to use the extension. +You can then grant access to other users to use the extension. ```sql CREATE EXTENSION pg_cron; @@ -56,9 +58,9 @@ GRANT USAGE ON SCHEMA cron TO elephant; SELECT cron.schedule('process-updates', '5 seconds', 'CALL process_updates()'); ``` -For information on how to schedule jobs, refer to the [README](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). +For information on how to schedule jobs, refer to the [pg_cron documentation](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). -{{< note title="Note" >}} +When running jobs, keep in mind the following: +- If you need to run jobs in multiple databases, use `cron.schedule_in_database()`. - It may take up to 60 seconds for job changes to get picked up by the pg_cron leader. -- When a new pg_cron leader node is elected, no jobs are run for the first minute. Any job that were in flight on the failed node will not be retied, as their outcome is not known. -{{< /note >}} \ No newline at end of file +- When a new pg_cron leader node is elected, no jobs are run for the first minute. Any job that were in flight on the failed node will not be retried, as their outcome is not known. \ No newline at end of file From 86ab4c1ea27880f7e34270299c5da3e066c31354 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Wed, 31 Jul 2024 09:41:04 -0400 Subject: [PATCH 08/10] edits --- .../pg-extensions/extension-pgcron.md | 38 ++++++++++--------- .../reference/configuration/yb-tserver.md | 8 ++++ 2 files changed, 28 insertions(+), 18 deletions(-) diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md index 681013b10ea2..edaa47c0d628 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md @@ -14,34 +14,29 @@ type: docs The [pg_cron](https://github.com/citusdata/pg_cron) extension provides a cron-based job scheduler that runs inside the database. It uses the same syntax as regular cron, and allows you to schedule YSQL commands directly from the database. You can also use '[1-59] seconds' to schedule a job based on an interval. -## pg_cron in YugabyteDB +YugabyteDB supports all features of the pg_cron extension. Although YugabyteDB is a distributed database that operates on multiple nodes, pg_cron only runs on one of these nodes, called the pg_cron leader. Only the pg_cron leader schedules and runs the cron jobs. The queries executed by jobs do take advantage of all available resources in the cluster. -YugabyteDB supports all features of the pg_cron extension. +If the pg_cron leader node fails, another node is automatically elected as the new leader to ensure it is highly available. This process is transparent, and you can connect to any node in a cluster to schedule jobs. -YugabyteDB is a distributed database that operates on multiple nodes. pg_cron only runs on one of these nodes called the pg_cron leader. Only the pg_cron leader schedules and runs the cron jobs. The queries executed by the job will take advantage of all available resources in the cluster. The database will automatically elect the leader node and ensure pg_cron is highly available and tolerant to node failures. -YugabyteDB is a distributed database that operates on multiple nodes. pg_cron only runs on one of these nodes called the pg_cron leader. Only the pg_cron leader schedules and runs the cron jobs. The queries executed by the job will take advantage of all available resources in the cluster. The database will automatically elect the leader node and ensure pg_cron is highly available and tolerant to node failures. +## Set up pg_cron -### Enable and configure +pg_cron in YugabyteDB is {{}}. Before you can use the feature, you must enable it by setting the `enable_pg_cron` flag. To do this, add `enable_pg_cron` to the `allowed_preview_flags_csv` flag and set the `enable_pg_cron` flag to true on all YB-Masters and YB-TServers. -To enable pg_cron, add `enable_pg_cron` to the `allowed_preview_flags_csv` flag and set the `enable_pg_cron` flag to true on all YB-Masters and YB-TServers. +The pg_cron extension is installed on only one database, which stores the extension data. The default cron database is `yugabyte`. You can change it by setting the `ysql_cron_database_name` flag on all YB-TServers. -The pg_cron extension is installed on only one database, which stores the extensions data. The default cron database is `yugabyte`. You can change it by setting the `ysql_cron_database_name` flag on all YB-TServers. +For example, to create a single-node [yugabyted](../../../../reference/configuration/yugabyted/) cluster with pg_cron on database 'db1', use the following command: -For example, to create a single-node [yugabyted](../../../../reference/configuration/yugabyted/) cluster with pg_cron on database 'db1', use the following command: ```sh ./bin/yugabyted start --master_flags "allowed_preview_flags_csv={enable_pg_cron},enable_pg_cron=true" --tserver_flags "allowed_preview_flags_csv={enable_pg_cron},enable_pg_cron=true,ysql_cron_database_name=db1" --ui false ``` -You can create the database after setting the flag. -In order to change the database after the extension is created, you must first drop the extension and then change the flag value. +You can create the database after setting the flag. +To change the database after the extension is created, you must first drop the extension and then change the flag value. - -### Create and use +## Enable pg_cron Create the extension as superuser on the cron database. -You can then grant access to other users to use the extension. -You can then grant access to other users to use the extension. ```sql CREATE EXTENSION pg_cron; @@ -53,14 +48,21 @@ You can grant access to other users to use the extension. For example: GRANT USAGE ON SCHEMA cron TO elephant; ``` +## Use pg_cron + +YugabyteDB supports all features and syntax of the pg_cron extension. + +For example, the following command calls a stored procedure every five seconds: + ```sql --- Call a stored procedure every 5 seconds SELECT cron.schedule('process-updates', '5 seconds', 'CALL process_updates()'); ``` -For information on how to schedule jobs, refer to the [pg_cron documentation](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). +If you need to run jobs in multiple databases, use `cron.schedule_in_database()`. When running jobs, keep in mind the following: -- If you need to run jobs in multiple databases, use `cron.schedule_in_database()`. + - It may take up to 60 seconds for job changes to get picked up by the pg_cron leader. -- When a new pg_cron leader node is elected, no jobs are run for the first minute. Any job that were in flight on the failed node will not be retried, as their outcome is not known. \ No newline at end of file +- When a new pg_cron leader node is elected, no jobs are run for the first minute. Any job that were in flight on the failed node will not be retried, as their outcome is not known. + +For more information on how to schedule jobs, refer to the [pg_cron documentation](https://github.com/yugabyte/yugabyte-db/blob/master/src/postgres/third-party-extensions/pg_cron/README.md). diff --git a/docs/content/preview/reference/configuration/yb-tserver.md b/docs/content/preview/reference/configuration/yb-tserver.md index 1151cb58814f..86b565546dc9 100644 --- a/docs/content/preview/reference/configuration/yb-tserver.md +++ b/docs/content/preview/reference/configuration/yb-tserver.md @@ -844,6 +844,14 @@ Default: `-1` (disables logging statement durations) Specifies the lowest YSQL message level to log. +##### --ysql_cron_database_name + +Specifies the database where pg_cron is to be installed. + +The [pg_cron extension](../../../explore/ysql-language-features/pg-extensions/extension-pgcron/) is installed on only one database (by default, `yugabyte`). + +To change the database after the extension is created, you must first drop the extension and then change the flag value. + ### YCQL The following flags support the use of the [YCQL API](../../../api/ycql/): From 0a9e1c97f5194f8571afed8db4dddaf386aa4ad3 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Wed, 31 Jul 2024 10:04:47 -0400 Subject: [PATCH 09/10] edits and add flag --- .../ysql-language-features/pg-extensions/extension-pgcron.md | 4 +--- docs/content/preview/reference/configuration/yb-tserver.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md index edaa47c0d628..6b2dfe9301ff 100644 --- a/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md +++ b/docs/content/preview/explore/ysql-language-features/pg-extensions/extension-pgcron.md @@ -22,7 +22,7 @@ If the pg_cron leader node fails, another node is automatically elected as the n pg_cron in YugabyteDB is {{}}. Before you can use the feature, you must enable it by setting the `enable_pg_cron` flag. To do this, add `enable_pg_cron` to the `allowed_preview_flags_csv` flag and set the `enable_pg_cron` flag to true on all YB-Masters and YB-TServers. -The pg_cron extension is installed on only one database, which stores the extension data. The default cron database is `yugabyte`. You can change it by setting the `ysql_cron_database_name` flag on all YB-TServers. +The pg_cron extension is installed on only one database, which stores the extension data. The default cron database is `yugabyte`. You can change it by setting the `ysql_cron_database_name` flag on all YB-TServers. You can create the database after setting the flag. For example, to create a single-node [yugabyted](../../../../reference/configuration/yugabyted/) cluster with pg_cron on database 'db1', use the following command: @@ -30,8 +30,6 @@ For example, to create a single-node [yugabyted](../../../../reference/configura ./bin/yugabyted start --master_flags "allowed_preview_flags_csv={enable_pg_cron},enable_pg_cron=true" --tserver_flags "allowed_preview_flags_csv={enable_pg_cron},enable_pg_cron=true,ysql_cron_database_name=db1" --ui false ``` -You can create the database after setting the flag. - To change the database after the extension is created, you must first drop the extension and then change the flag value. ## Enable pg_cron diff --git a/docs/content/preview/reference/configuration/yb-tserver.md b/docs/content/preview/reference/configuration/yb-tserver.md index 6c2e4362dc28..2f746ff13af9 100644 --- a/docs/content/preview/reference/configuration/yb-tserver.md +++ b/docs/content/preview/reference/configuration/yb-tserver.md @@ -859,7 +859,7 @@ Specifies the lowest YSQL message level to log. Specifies the database where pg_cron is to be installed. -The [pg_cron extension](../../../explore/ysql-language-features/pg-extensions/extension-pgcron/) is installed on only one database (by default, `yugabyte`). +The [pg_cron extension](../../../explore/ysql-language-features/pg-extensions/extension-pgcron/) is installed on only one database (by default, `yugabyte`). You can create the database after setting the flag. To change the database after the extension is created, you must first drop the extension and then change the flag value. From ee3ce6bdfd3478c72c47fa703aed1eae8c00a37b Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Wed, 31 Jul 2024 14:22:56 -0400 Subject: [PATCH 10/10] minor edit --- docs/content/preview/reference/configuration/yb-tserver.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/preview/reference/configuration/yb-tserver.md b/docs/content/preview/reference/configuration/yb-tserver.md index 2f746ff13af9..56f7a9867369 100644 --- a/docs/content/preview/reference/configuration/yb-tserver.md +++ b/docs/content/preview/reference/configuration/yb-tserver.md @@ -857,9 +857,9 @@ Specifies the lowest YSQL message level to log. ##### --ysql_cron_database_name -Specifies the database where pg_cron is to be installed. +Specifies the database where pg_cron is to be installed. You can create the database after setting the flag. -The [pg_cron extension](../../../explore/ysql-language-features/pg-extensions/extension-pgcron/) is installed on only one database (by default, `yugabyte`). You can create the database after setting the flag. +The [pg_cron extension](../../../explore/ysql-language-features/pg-extensions/extension-pgcron/) is installed on only one database (by default, `yugabyte`). To change the database after the extension is created, you must first drop the extension and then change the flag value.