From f8e35db9053b4da1c9cf025fcd97427549d6facb Mon Sep 17 00:00:00 2001 From: "Seongho.Bak" Date: Wed, 26 Aug 2026 11:50:24 +0900 Subject: [PATCH 1/3] docs: explain LISTEN channel identifier quoting --- docs/docs/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/api.md b/docs/docs/api.md index 4a4c889c4..83c0c127a 100644 --- a/docs/docs/api.md +++ b/docs/docs/api.md @@ -294,13 +294,13 @@ Returns an unsubscribe function to unsubscribe from the channel. ##### Example ```ts -const unsub = await pg.listen('test', (payload) => { +const unsub = await pg.listen('"name-with-hyphen"', (payload) => { console.log('Received:', payload) }) -await pg.query("NOTIFY test, 'Hello, world!'") +await pg.query(`NOTIFY "name-with-hyphen", 'Hello, world!'`) ``` -Channel names are case sensitive if double-quoted (`pg.listen('"TeST"')`). Otherwise channel name will be lower cased (`pg.listen('TeStiNG')` == `pg.listen('testing')`). +Channel names follow PostgreSQL identifier rules. Unquoted identifiers are folded to lowercase, so `pg.listen('TeStiNG')` listens on the same channel as `pg.listen('testing')`. Double-quoted identifiers preserve case and allow special characters such as hyphens, spaces, and `&`. Include the double quotes in the string passed to `listen()`, as shown above, and use the matching quoted identifier in the `NOTIFY` statement. ### unlisten From 6c797fd616441cefbd22b99c45994ab1eef8e15c Mon Sep 17 00:00:00 2001 From: "Seongho.Bak" Date: Wed, 26 Aug 2026 12:52:32 +0900 Subject: [PATCH 2/3] docs: clarify cleanup for quoted LISTEN channels --- docs/docs/api.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/docs/api.md b/docs/docs/api.md index 83c0c127a..713c63b21 100644 --- a/docs/docs/api.md +++ b/docs/docs/api.md @@ -289,18 +289,19 @@ Close the database, ensuring it is shut down cleanly. Subscribe to a [pg_notify](https://www.postgresql.org/docs/current/sql-notify.html) channel. The callback will receive the payload from the notification. -Returns an unsubscribe function to unsubscribe from the channel. +Returns an unsubscribe function to unsubscribe from the channel. When an identifier requires double quotes, keep the quoted string and pass it directly to `unlisten()` for cleanup, as shown below. ##### Example ```ts -const unsub = await pg.listen('"name-with-hyphen"', (payload) => { +await pg.listen('"name-with-hyphen"', (payload) => { console.log('Received:', payload) }) await pg.query(`NOTIFY "name-with-hyphen", 'Hello, world!'`) +await pg.unlisten('"name-with-hyphen"') ``` -Channel names follow PostgreSQL identifier rules. Unquoted identifiers are folded to lowercase, so `pg.listen('TeStiNG')` listens on the same channel as `pg.listen('testing')`. Double-quoted identifiers preserve case and allow special characters such as hyphens, spaces, and `&`. Include the double quotes in the string passed to `listen()`, as shown above, and use the matching quoted identifier in the `NOTIFY` statement. +Channel names follow PostgreSQL identifier rules. Unquoted identifiers are folded to lowercase, so `pg.listen('TeStiNG')` listens on the same channel as `pg.listen('testing')`. Double-quoted identifiers preserve case and allow special characters such as hyphens, spaces, and `&`. Include the double quotes in the strings passed to `listen()` and `unlisten()`, as shown above, and use the matching quoted identifier in the `NOTIFY` statement. ### unlisten From 49c93620b089e6224afea41a97f2c8e9b7a6f7ff Mon Sep 17 00:00:00 2001 From: "Seongho.Bak" Date: Wed, 26 Aug 2026 13:05:30 +0900 Subject: [PATCH 3/3] docs: scope quoted LISTEN cleanup limitation --- docs/docs/api.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/docs/api.md b/docs/docs/api.md index 713c63b21..861739b8b 100644 --- a/docs/docs/api.md +++ b/docs/docs/api.md @@ -289,7 +289,7 @@ Close the database, ensuring it is shut down cleanly. Subscribe to a [pg_notify](https://www.postgresql.org/docs/current/sql-notify.html) channel. The callback will receive the payload from the notification. -Returns an unsubscribe function to unsubscribe from the channel. When an identifier requires double quotes, keep the quoted string and pass it directly to `unlisten()` for cleanup, as shown below. +`listen()` returns an unsubscribe function for ordinary unquoted channel names. Quoted identifiers are supported for subscribing and receiving notifications, but cleanup is not reliable in either `PGlite` or `PGliteWorker`; do not use the returned function or `unlisten()` for quoted names. Use an unquoted identifier when per-channel cleanup is required. The quoted example below is suitable only when the listener can remain active for the lifetime of the PGlite instance. ##### Example @@ -298,10 +298,9 @@ await pg.listen('"name-with-hyphen"', (payload) => { console.log('Received:', payload) }) await pg.query(`NOTIFY "name-with-hyphen", 'Hello, world!'`) -await pg.unlisten('"name-with-hyphen"') ``` -Channel names follow PostgreSQL identifier rules. Unquoted identifiers are folded to lowercase, so `pg.listen('TeStiNG')` listens on the same channel as `pg.listen('testing')`. Double-quoted identifiers preserve case and allow special characters such as hyphens, spaces, and `&`. Include the double quotes in the strings passed to `listen()` and `unlisten()`, as shown above, and use the matching quoted identifier in the `NOTIFY` statement. +Channel names follow PostgreSQL identifier rules. Unquoted identifiers are folded to lowercase, so `pg.listen('TeStiNG')` listens on the same channel as `pg.listen('testing')`. Double-quoted identifiers preserve case and allow special characters such as hyphens, spaces, and `&`. Include the double quotes in the string passed to `listen()`, as shown above, and use the matching quoted identifier in the `NOTIFY` statement. ### unlisten