cloud: add Starter PostgreSQL Compatible docs - #23907
qiqi-power wants to merge 20 commits into
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
ti-chi-bot
Bot
added
contribution
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository: pingcap/docs/.coderabbit.yaml Review profile: ASSERTIVE Plan: Advanced Run ID: 📒 Files selected for processing (1)
Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review. 📝 WalkthroughWalkthroughThe PR documents PostgreSQL-compatible TiDB Cloud Starter in Limited Public Preview. It adds guides for creation, connectivity, migration, SQL support, administration, monitoring, extensions, vector search, full-text search, and operational limits. Existing Starter documentation now distinguishes compatibility modes. ChangesPostgreSQL-compatible Starter documentation
Priority: ⬇️ Low Estimated code review effort: 3 (Moderate) | ~25 minutes Change: Other Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Full details: Description checkExplanation The description includes the template, CLA confirmation, and v8.5 selection, but the required change summary is empty. It therefore does not provide enough information about the purpose or scope of the pull request. ✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 18
Caution
Some comments are outside the diff and can’t be posted inline due to GitHub limitations.
🟡 Minor · Extend the backup-setting instructions to… · backup-and-restore-serverless.md:60
tidb-cloud/backup-and-restore-serverless.md:60
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winExtend the backup-setting instructions to PostgreSQL-compatible Starter.
The new note states that PostgreSQL-compatible Starter supports configurable backup settings. This section still says the procedure applies only to Essential instances. Update Line 60 to include PostgreSQL-compatible Starter and Starter instances with configurable backup settings.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: pingcap/docs/.coderabbit.yaml
Review profile: ASSERTIVE
Plan: Advanced
Run ID: 2a80beba-a179-4c14-a2ef-a205d3b55ee6
📒 Files selected for processing (25)
tidb-cloud/backup-and-restore-serverless.mdtidb-cloud/connect-via-standard-connection-serverless.mdtidb-cloud/create-tidb-cluster-serverless.mdtidb-cloud/pg-on-starter/Import-with-psql.mdtidb-cloud/pg-on-starter/built-in-monitoring-pg.mdtidb-cloud/pg-on-starter/pg-advanced-sql.mdtidb-cloud/pg-on-starter/pg-auth-roles.mdtidb-cloud/pg-on-starter/pg-built-in-functions.mdtidb-cloud/pg-on-starter/pg-data-types.mdtidb-cloud/pg-on-starter/pg-ddl.mdtidb-cloud/pg-on-starter/pg-dml-queries.mdtidb-cloud/pg-on-starter/pg-extensions-overview.mdtidb-cloud/pg-on-starter/pg-full-text-search.mdtidb-cloud/pg-on-starter/pg-limits-constraints.mdtidb-cloud/pg-on-starter/pg-parquet-import.mdtidb-cloud/pg-on-starter/pg-quickstart.mdtidb-cloud/pg-on-starter/pg-row-level-security.mdtidb-cloud/pg-on-starter/pg-session-parameters.mdtidb-cloud/pg-on-starter/pg-sql-reference-overview.mdtidb-cloud/pg-on-starter/pg-system-catalog.mdtidb-cloud/pg-on-starter/pg-transactions-copy.mdtidb-cloud/pg-on-starter/pg-vector-search.mdtidb-cloud/pg-on-starter/postgresql-compatibility.mdtidb-cloud/select-cluster-tier.mdtidb-cloud/tidb-cloud-intro.md
Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.
| @@ -0,0 +1,291 @@ | |||
| --- | |||
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use a lowercase filename.
This new file is named Import-with-psql.md. Rename it to import-with-psql.md and update references.
As per path instructions, new file names must use lowercase words separated by hyphens.
Source: Path instructions
| ```shell | ||
| pg_dump \ | ||
| --data-only \ | ||
| --no-owner \ | ||
| --no-privileges \ | ||
| "<SOURCE_DATABASE_URL>" \ | ||
| | psql "<TARGET_DATABASE_URL>" -v ON_ERROR_STOP=1 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Do not hide pg_dump failures in the pipeline.
Without pipefail, the shell reports the status of the final psql command. If pg_dump fails after emitting a valid prefix, the command can appear successful after importing only part of the data. Run this pipeline in a shell that supports pipefail, or export and validate the dump before importing.
Committable change
+set -o pipefail
pg_dump \📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```shell | |
| pg_dump \ | |
| --data-only \ | |
| --no-owner \ | |
| --no-privileges \ | |
| "<SOURCE_DATABASE_URL>" \ | |
| | psql "<TARGET_DATABASE_URL>" -v ON_ERROR_STOP=1 | |
| ```shell | |
| set -o pipefail | |
| pg_dump \ | |
| --data-only \ | |
| --no-owner \ | |
| --no-privileges \ | |
| "<SOURCE_DATABASE_URL>" \ | |
| | psql "<TARGET_DATABASE_URL>" -v ON_ERROR_STOP=1 |
| CREATE FUNCTION create_order(p_item TEXT) | ||
| RETURNS BIGINT AS $$ | ||
| DECLARE | ||
| new_id BIGINT; | ||
| BEGIN | ||
| INSERT INTO orders (item) | ||
| VALUES (p_item) | ||
| RETURNING id INTO new_id; |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Align create_order with the documented orders table.
tidb-cloud/pg-on-starter/pg-ddl.md defines orders with id, user_id, and amount; it has no item column. A reader who follows both pages cannot create this function successfully.
Committable replacement
-CREATE FUNCTION create_order(p_item TEXT)
+CREATE FUNCTION create_order(p_user_id BIGINT, p_amount NUMERIC)
@@
- INSERT INTO orders (item)
- VALUES (p_item)
+ INSERT INTO orders (user_id, amount)
+ VALUES (p_user_id, p_amount)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| CREATE FUNCTION create_order(p_item TEXT) | |
| RETURNS BIGINT AS $$ | |
| DECLARE | |
| new_id BIGINT; | |
| BEGIN | |
| INSERT INTO orders (item) | |
| VALUES (p_item) | |
| RETURNING id INTO new_id; | |
| CREATE FUNCTION create_order(p_user_id BIGINT, p_amount NUMERIC) | |
| RETURNS BIGINT AS $$ | |
| DECLARE | |
| new_id BIGINT; | |
| BEGIN | |
| INSERT INTO orders (user_id, amount) | |
| VALUES (p_user_id, p_amount) | |
| RETURNING id INTO new_id; |
| A `CASE` expression, such as `NEW.status := CASE WHEN ... END`, can still be used in an assignment. | ||
|
|
||
| ### AFTER trigger formatting | ||
|
|
||
| In an `AFTER` trigger function, keep a bare `RETURN NEW;` or `RETURN OLD;` on its own line. | ||
|
|
||
| For example: | ||
|
|
There was a problem hiding this comment.
🔒 Security & Privacy | 🛡️ Analyzed with Security Review | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
sed -n '320,355p' tidb-cloud/pg-on-starter/pg-row-level-security.md
rg -n "search_path|ALTER FUNCTION|SET search_path|SECURITY DEFINER" tidb-cloud/pg-on-starterRepository: pingcap/docs
Length of output: 2185
🏁 Script executed:
#!/bin/bash
set -eu
cat -n tidb-cloud/pg-on-starter/pg-row-level-security.md | sed -n '323,353p'
cat -n tidb-cloud/pg-on-starter/pg-session-parameters.md | sed -n '118,145p'
printf '\n-- function search_path controls in Starter docs --\n'
rg -n -C 2 "CREATE FUNCTION|SET search_path|function-local|ALTER FUNCTION|SET clause|configuration parameter" tidb-cloud/pg-on-starter/pg-*.mdRepository: pingcap/docs
Length of output: 7234
Security Misconfiguration
Exploitability: Moderate
CWE: CWE-427
Schema-qualify the SECURITY DEFINER example. RETURNS SETOF posts is fixed when the function is created, so the caller's search_path does not redirect the return type. However, SELECT * FROM posts can resolve through the caller-controlled search path while running with the owner's privileges. Use the trusted schema for both references.
Use schema-qualified references
| A `CASE` expression, such as `NEW.status := CASE WHEN ... END`, can still be used in an assignment. | |
| ### AFTER trigger formatting | |
| In an `AFTER` trigger function, keep a bare `RETURN NEW;` or `RETURN OLD;` on its own line. | |
| For example: | |
| CREATE FUNCTION list_all_posts() | |
| RETURNS SETOF public.posts | |
| LANGUAGE SQL | |
| SECURITY DEFINER | |
| AS $$ | |
| SELECT * FROM public.posts | |
| $$; |
| | `INTEGER` | `INT`, `INT4` | 4-byte signed integer. | | ||
| | `BIGINT` | `INT8` | 8-byte signed integer. | | ||
| | `DOUBLE PRECISION` | `FLOAT8` | 8-byte IEEE 754 floating-point number. | | ||
| | `NUMERIC` | `NUMERIC(p,s)`, `DECIMAL` | Exact numeric value with optional precision and scale. | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Move NUMERIC(p,s) out of the alias column.
NUMERIC(p,s) is parameterized type syntax, not a type alias. Listing it as an alias can mislead users about the accepted type name.
Apply this replacement
-| `NUMERIC` | `NUMERIC(p,s)`, `DECIMAL` | Exact numeric value with optional precision and scale. |
+| `NUMERIC` | `DECIMAL` | Exact numeric value. Use `NUMERIC(p,s)` to specify precision and scale. |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | `NUMERIC` | `NUMERIC(p,s)`, `DECIMAL` | Exact numeric value with optional precision and scale. | | |
| | `NUMERIC` | `DECIMAL` | Exact numeric value. Use `NUMERIC(p,s)` to specify precision and scale. | |
Source: Path instructions
| You can configure HNSW index build parameters when creating an index: | ||
|
|
||
| ```sql | ||
| CREATE INDEX idx_documents_embedding |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use a unique name for the tuned HNSW example.
The page already creates idx_documents_embedding in Lines [94-96]. Running this example afterward on the same documents table fails because the index name already exists.
Apply this replacement
-CREATE INDEX idx_documents_embedding
+CREATE INDEX idx_documents_embedding_tuned📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| CREATE INDEX idx_documents_embedding | |
| CREATE INDEX idx_documents_embedding_tuned |
Source: Path instructions
|
|
||
| Arbitrary custom or third-party PostgreSQL extensions cannot be installed. Only extensions explicitly supported by TiDB Cloud are available. | ||
|
|
||
| For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](<link>). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Replace the placeholder extension link.
The link target is a placeholder rather than a repository page. It will produce a broken link for the supported extensions reference.
Apply this replacement
-For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](<link>).
+For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](/tidb-cloud/pg-on-starter/pg-extensions-overview.md).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](<link>). | |
| For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](/tidb-cloud/pg-on-starter/pg-extensions-overview.md). |
Source: Path instructions
| - TiDB Cloud Starter | ||
|
|
||
| {{{ .starter }}} is a fully managed, multi-tenant TiDB offering. It delivers an instant, autoscaling MySQL-compatible database and offers a generous free quota and consumption based billing once free limits are exceeded. | ||
| {{{ .starter }}} is a fully managed, multi-tenant TiDB offering. It delivers an instant, autoscaling database with MySQL compatibility, while PostgreSQL compatibility is available in limited Public Preview. It offers a generous free quota and consumption based billing once free limits are exceeded. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Scope the billing statement to MySQL-compatible Starter.
The current wording implies that PostgreSQL-compatible Starter receives consumption-based billing after quota exhaustion. The other changed pages state that PostgreSQL-compatible Starter rejects new connections and throttles existing connections instead. Qualify the billing behavior to MySQL-compatible Starter.
Committable change
- {{{ .starter }}} is a fully managed, multi-tenant TiDB offering. It delivers an instant, autoscaling database with MySQL compatibility, while PostgreSQL compatibility is available in limited Public Preview. It offers a generous free quota and consumption based billing once free limits are exceeded.
+ {{{ .starter }}} is a fully managed, multi-tenant TiDB offering. It delivers an instant, autoscaling database with MySQL compatibility, while PostgreSQL compatibility is available in Limited Public Preview. MySQL-compatible {{{ .starter }}} offers a generous free quota and consumption-based billing once free limits are exceeded.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| {{{ .starter }}} is a fully managed, multi-tenant TiDB offering. It delivers an instant, autoscaling database with MySQL compatibility, while PostgreSQL compatibility is available in limited Public Preview. It offers a generous free quota and consumption based billing once free limits are exceeded. | |
| {{{ .starter }}} is a fully managed, multi-tenant TiDB offering. It delivers an instant, autoscaling database with MySQL compatibility, while PostgreSQL compatibility is available in Limited Public Preview. MySQL-compatible {{{ .starter }}} offers a generous free quota and consumption-based billing once free limits are exceeded. |
🧰 Tools
🪛 LanguageTool
[grammar] ~79-~79: Use a hyphen to join words.
Context: ...rs a generous free quota and consumption based billing once free limits are excee...
(QB_NEW_EN_HYPHEN)
ti-chi-bot
Bot
removed
the
missing-translation-status
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: pingcap/docs/.coderabbit.yaml
Review profile: ASSERTIVE
Plan: Advanced
Run ID: 933ff1bb-f744-470c-afa6-fb14d68f3e75
📒 Files selected for processing (3)
tidb-cloud/connect-via-standard-connection-serverless.mdtidb-cloud/select-cluster-tier.mdtidb-cloud/tidb-cloud-intro.md
Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.
| > - PostgreSQL-compatible {{{ .starter }}} currently supports public endpoints only. Private endpoints are not supported. | ||
| > - For MySQL-compatible {{{ .starter }}} and {{{ .essential }}} instances, you can also choose **Private Endpoint** in the **Connection Type** drop-down list. For more information, see the following documents: |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🔎 Supported by static analysis
🤖 get_repo_knowledge executed:
get_repo_knowledge pingcap/docs /tmp/coderabbit-repo-knowledge/pingcap-docs-9c73f70c/learnings /tmp/coderabbit-repo-knowledge/pingcap-docs-9c73f70c/conventions
Length of output: 4069
🏁 Script executed:
#!/bin/bash
set -e
printf '%s\n' '--- tracked candidate files ---'
git ls-files 'tidb-cloud/*standard*connection*serverless*' 'tidb-cloud/*private*endpoint*serverless*' 'tidb-cloud/*branch*overview*' | sed -n '1,120p'
printf '%s\n' '--- cited source sections ---'
for f in \
tidb-cloud/connect-via-standard-connection-serverless.md \
tidb-cloud/set-up-private-endpoint-connections-serverless.md \
tidb-cloud/branch-overview.md
do
if [ -f "$f" ]; then
printf '\n### %s\n' "$f"
wc -l "$f"
rg -n -C 5 'PostgreSQL-compatible|MySQL-compatible|Private Endpoint|private endpoint|Starter|starter|branch|Branch' "$f" | sed -n '1,260p'
fi
done
printf '%s\n' '--- related Japanese paths and matching passages ---'
rg -l -i 'private.?endpoint|postgresql.?compatible|mysql.?compatible|branch' tidb-cloud | rg -i 'connect|private|branch|serverless|mysql|postgres' | sed -n '1,120p'
rg -n -i -C 3 'PostgreSQL-compatible|MySQL-compatible|Private Endpoint|private endpoint' tidb-cloud --glob '*.md' | sed -n '1,320p'Repository: pingcap/docs
Length of output: 50370
🏁 Script executed:
#!/bin/bash
set -e
printf '%s\n' '--- compatibility-specific restrictions ---'
rg -n -i -C 4 'PostgreSQL-compatible|MySQL-compatible|private endpoint|private endpoints|branch(es)?' tidb-cloud \
--glob '*.md' \
--glob '!connect-via-standard-connection-serverless.md' \
--glob '!set-up-private-endpoint-connections-serverless.md' \
--glob '!branch-overview.md' \
| rg -i -C 3 'PostgreSQL-compatible|MySQL-compatible|private endpoint|private endpoints|branch' \
| sed -n '1,260p'
printf '%s\n' '--- private guide focused sections ---'
sed -n '1,70p;137,151p' tidb-cloud/set-up-private-endpoint-connections-serverless.md
printf '%s\n' '--- branch guide focused sections ---'
sed -n '1,22p;38,50p' tidb-cloud/branch-overview.md
printf '%s\n' '--- compatibility overview ---'
sed -n '35,75p' tidb-cloud/select-cluster-tier.md
printf '%s\n' '--- branch management references ---'
rg -n -i -C 3 'PostgreSQL-compatible|MySQL-compatible|branch' tidb-cloud/branch-manage.md tidb-cloud/ticloud-branch-*.md tidb-cloud/terraform-use-serverless-branch-resource.md | sed -n '1,260p'Repository: pingcap/docs
Length of output: 50370
Update the linked guides with the compatibility restrictions.
tidb-cloud/set-up-private-endpoint-connections-serverless.md describes private endpoints for generic Starter instances, and tidb-cloud/branch-overview.md describes branches for generic Starter instances. State that these features apply to MySQL-compatible Starter, not PostgreSQL-compatible Starter. The English and Japanese links and the branch sentence already include the required qualification.
📍 Affects 1 file
tidb-cloud/connect-via-standard-connection-serverless.md#L36-L37(this comment)tidb-cloud/connect-via-standard-connection-serverless.md#L48-L49tidb-cloud/connect-via-standard-connection-serverless.md#L52-L55
Source: Path instructions
|
Read through this and the extension list and compatibility scope look solid. One suggestion and one small heads up. The preview notes across these pages explain well what the feature can and cannot do, but they do not yet say what users can expect from us operationally while it is in Limited Public Preview. Three things would round that out.
A short "Support during the preview" section on On the small one, the failing |
| + **Transactions**: `BEGIN`, `COMMIT`, `ROLLBACK`, savepoints, and autocommit. | ||
| + **Data types**: Boolean, integer, bigint, double precision, numeric, text, varchar, bytea, timestamp/timestamptz, date, time, interval, UUID, JSON/JSONB, arrays, serial/bigserial, vector, tsvector, and tsquery. | ||
| + **PL/pgSQL**: Functions, procedures, control flow, and dynamic `EXECUTE`, with some limitations. `WHILE`, `FOREACH`, and cursors are not supported. `EXCEPTION` and nested blocks require a `DO` block. | ||
| + **Triggers**: `BEFORE` and `AFTER` triggers on `INSERT`, `UPDATE`, and `DELETE`, with some limitations. For more information, see [PL/pgSQL](#plpgsql). |
There was a problem hiding this comment.
| + **Triggers**: `BEFORE` and `AFTER` triggers on `INSERT`, `UPDATE`, and `DELETE`, with some limitations. For more information, see [PL/pgSQL](#plpgsql). | |
| + **Triggers**: `BEFORE` and `AFTER` triggers on `INSERT`, `UPDATE`, and `DELETE`, with some limitations. For more information, see [Triggers](#triggers). |
|
|
||
| The effective isolation level is `REPEATABLE READ`. | ||
|
|
||
| If your application relies on true serializability, use explicit row locking such as `SELECT ... FOR UPDATE` or database constraints to protect application invariants. |
There was a problem hiding this comment.
| If your application relies on true serializability, use explicit row locking such as `SELECT ... FOR UPDATE` or database constraints to protect application invariants. | |
| If your application relies on PostgreSQL `SERIALIZABLE` semantics, review and redesign your transaction logic as needed. Explicit row locking or database constraints can protect specific invariants, but they do not provide PostgreSQL Serializable Snapshot Isolation (SSI) semantics. |
There was a problem hiding this comment.
Reason: Explicit row locking and database constraints are not a general substitute for PostgreSQL SERIALIZABLE isolation. The original wording could incorrectly imply that using SELECT ... FOR UPDATE or constraints restores the serializability guarantee lost when SERIALIZABLE is downgraded to REPEATABLE READ.
|
|
||
| | PostgreSQL type | Behavior | | ||
| | --- | --- | | ||
| | `SMALLINT` / `INT2` | Accepted, but stored internally as a 32-bit integer. | |
There was a problem hiding this comment.
| | `SMALLINT` / `INT2` | Accepted, but stored internally as a 32-bit integer. | | |
| | `SMALLINT` / `INT2` | Not supported. Use `INTEGER` instead. | |
There was a problem hiding this comment.
Reason: This conflicts with pg-data-types.md in the same PR, which explicitly lists SMALLINT and INT2 as unsupported and recommends using INTEGER instead. Please confirm which is correct.
| | PostgreSQL type | Behavior | | ||
| | --- | --- | | ||
| | `SMALLINT` / `INT2` | Accepted, but stored internally as a 32-bit integer. | | ||
| | `REAL` / `FLOAT4` | Accepted, but stored internally as double precision. | |
There was a problem hiding this comment.
| | `REAL` / `FLOAT4` | Accepted, but stored internally as double precision. | | |
| | `REAL` / `FLOAT4` | Not supported. Use `DOUBLE PRECISION` instead. | |
There was a problem hiding this comment.
Reason: This conflicts with pg-data-types.md in the same PR, which explicitly lists REAL and FLOAT4 as unsupported and recommends using DOUBLE PRECISION instead. Please confirm which is correct.
| | --- | --- | | ||
| | `SMALLINT` / `INT2` | Accepted, but stored internally as a 32-bit integer. | | ||
| | `REAL` / `FLOAT4` | Accepted, but stored internally as double precision. | | ||
| | `CHAR(n)` / `CHARACTER(n)` | Accepted, but stored internally as `VARCHAR`. Fixed-length padding semantics differ from PostgreSQL. | |
There was a problem hiding this comment.
| | `CHAR(n)` / `CHARACTER(n)` | Accepted, but stored internally as `VARCHAR`. Fixed-length padding semantics differ from PostgreSQL. | | |
| | `CHAR(n)` / `CHARACTER(n)` | Not supported. Use `VARCHAR(n)` instead. | |
There was a problem hiding this comment.
Reason: This conflicts with pg-data-types.md in the same PR, which explicitly lists CHAR(n) and CHARACTER(n) as unsupported and recommends using VARCHAR(n) instead. Please confirm which is correct.
|
|
||
| ### `COPY` | ||
|
|
||
| `COPY FROM` supports text and CSV formats over the PostgreSQL wire protocol. |
There was a problem hiding this comment.
| `COPY FROM` supports text and CSV formats over the PostgreSQL wire protocol. | |
| `COPY ... FROM STDIN` supports text and CSV formats over the PostgreSQL wire protocol. |
There was a problem hiding this comment.
Reason: The dedicated pg-transactions-copy.md page documents client streaming through COPY ... FROM STDIN. Naming STDIN explicitly avoids implying that all PostgreSQL COPY FROM forms are supported.
|
|
||
| HNSW is the supported approximate nearest-neighbor index type for vector workloads. It has additional structural and query-shape requirements. | ||
|
|
||
| PostgreSQL vector index types that are not provided by TiDB Cloud, such as IVFFlat, are not available. |
There was a problem hiding this comment.
| PostgreSQL vector index types that are not provided by TiDB Cloud, such as IVFFlat, are not available. | |
| Other pgvector index types that are not provided by TiDB Cloud, such as IVFFlat, are not available. |
|
|
||
| Arbitrary custom or third-party PostgreSQL extensions cannot be installed. Only extensions explicitly supported by TiDB Cloud are available. | ||
|
|
||
| For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](<link>). |
There was a problem hiding this comment.
| For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](<link>). | |
| For the list of available extensions and extension-specific limitations, see [PostgreSQL Extensions](/tidb-cloud/starter/pg-extensions-overview.md). |
| > | ||
| > PostgreSQL-compatible TiDB Cloud Starter is currently available in limited public preview. To request access, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). | ||
| > | ||
| > After preview access is enabled, the **Compatibility Mode** section is displayed when you create a Starter instance. |
There was a problem hiding this comment.
| > After preview access is enabled, the **Compatibility Mode** section is displayed when you create a Starter instance. | |
| > After preview access is enabled, the **Compatibility Mode** section is displayed when you create a TiDB Cloud Starter instance. |
| ```sql | ||
| INSERT INTO users (name, email) | ||
| VALUES | ||
| ('Alice', 'alice@example.com'), |
There was a problem hiding this comment.
The preceding single-row example has already inserted Alice with alice@example.com. Because users.email is defined as UNIQUE in pg-ddl.md, running these examples sequentially would make this multi-row insert fail with a uniqueness conflict. Using Charlie also makes the later UPDATE ... WHERE name = 'Charlie' examples operate on an existing row.
| ('Alice', 'alice@example.com'), | |
| ('Charlie', 'charlie@example.com'), |
|
|
||
| ```sql | ||
| DELETE FROM users | ||
| WHERE id = 1; |
There was a problem hiding this comment.
Both DELETE examples currently target id = 1. If readers run the examples sequentially, the first DELETE removes that row, so the following DELETE ... RETURNING example returns nothing. Using a different existing row keeps the examples runnable in sequence.
| WHERE id = 1; | |
| WHERE name = 'Bob'; |
|
|
||
| ```sql | ||
| DELETE FROM users | ||
| WHERE id = 1 |
There was a problem hiding this comment.
The immediately preceding DELETE example already deletes id = 1, so using the same condition here would not demonstrate RETURNING when the examples are run sequentially. Charlie is available from the earlier insert example and is therefore a clearer target.
| WHERE id = 1 | |
| WHERE name = 'Charlie' |
| For example: | ||
|
|
||
| ```sql | ||
| CREATE TABLE orders ( |
There was a problem hiding this comment.
The related pg-ddl.md example already creates an orders table, and this page otherwise reuses objects such as users and orders from that schema. Reusing CREATE TABLE orders here would fail if users follow the examples across the SQL reference. A distinct table name avoids the conflict while still demonstrating ON DELETE CASCADE.
| CREATE TABLE orders ( | |
| CREATE TABLE orders_with_cascade ( |
|
|
||
| ## Joins | ||
|
|
||
| The following join forms are supported: |
There was a problem hiding this comment.
EXISTS and NOT EXISTS are subquery predicates commonly used to express semi-join and anti-join semantics, not SQL join forms. LATERAL is also a modifier for a FROM item rather than a standalone join type. The broader wording accurately covers all entries in the table.
| The following join forms are supported: | |
| The following joins and related query patterns are supported: |
|
|
||
| The following join forms are supported: | ||
|
|
||
| | Join type | Supported | |
There was a problem hiding this comment.
The table contains EXISTS and NOT EXISTS patterns in addition to actual join types, so Join type is not accurate for every row.
| | Join type | Supported | | |
| | Join or query pattern | Supported | |
| | `RIGHT [OUTER] JOIN` | Yes | | ||
| | `FULL [OUTER] JOIN` | Yes | | ||
| | `CROSS JOIN` | Yes | | ||
| | `LATERAL JOIN` | Yes | |
There was a problem hiding this comment.
PostgreSQL does not define LATERAL JOIN as a standalone join type. LATERAL qualifies a subquery or function in the FROM clause and can be combined with joins, as in the later LEFT JOIN LATERAL example.
| | `LATERAL JOIN` | Yes | | |
| | `LATERAL` subquery | Yes | |
|
|
||
| ## Common table expressions | ||
|
|
||
| Standard CTEs are supported: |
There was a problem hiding this comment.
Standard CTEs is ambiguous because recursive CTEs are also part of standard SQL/PostgreSQL functionality. This paragraph is specifically contrasting ordinary non-recursive CTEs with the recursive CTEs introduced immediately afterward.
| Standard CTEs are supported: | |
| Non-recursive CTEs are supported: |
|
|
||
| Recursive CTEs are limited to 1,000 iterations. | ||
|
|
||
| Use a unique name for each CTE definition in the same `WITH` list. For compatibility details, see [PostgreSQL Compatibility](/tidb-cloud/starter/postgresql-compatibility.md). |
There was a problem hiding this comment.
The referenced PostgreSQL Compatibility page in this PR does not document the unique-CTE-name rule or the 1,000-iteration recursive CTE limit. The Limits and Constraints page explicitly documents the recursive CTE limit, so it is the more accurate cross-reference.
| Use a unique name for each CTE definition in the same `WITH` list. For compatibility details, see [PostgreSQL Compatibility](/tidb-cloud/starter/postgresql-compatibility.md). | |
| Use a unique name for each CTE definition in the same `WITH` list. For recursive CTE limits, see [PostgreSQL Limits and Constraints](/tidb-cloud/starter/pg-limits-constraints.md). |
| | `BOOLEAN` | `BOOLEAN` | | ||
| | `INT32` | `INTEGER` | | ||
| | `INT64` | `BIGINT` | | ||
| | `FLOAT` | `REAL` | |
There was a problem hiding this comment.
| | `FLOAT` | `REAL` | | |
| | `FLOAT` | `DOUBLE PRECISION` | |
Reason: This mapping is inconsistent with pg-data-types.md in the same PR, which explicitly states that REAL and FLOAT4 are not supported and recommends DOUBLE PRECISION instead. The Parquet type mapping should use a supported PostgreSQL-compatible TiDB Cloud Starter type, or the documentation should explicitly explain why the Parquet extension can return REAL despite that general limitation.
| | `ENCODE(bytea, format)` | Encodes binary data. | | ||
| | `DECODE(text, format)` | Decodes text into binary data. | | ||
|
|
||
| Additional UUID functions are provided through the `uuid-ossp` compatibility extension. |
There was a problem hiding this comment.
| Additional UUID functions are provided through the `uuid-ossp` compatibility extension. | |
| Additional `uuid-ossp`-compatible UUID functions are built in, and `CREATE EXTENSION "uuid-ossp"` can be used to register the extension metadata. |
Reason: Reason: This is inconsistent with pg-extensions-overview.md in the same PR, which states that the uuid-ossp functionality is built in and that CREATE EXTENSION "uuid-ossp" is used to register extension metadata. The original wording incorrectly implies that the functions become available through the extension.
| - Text without an explicit custom collation uses bytewise ordering. | ||
| - Collation is not applied to `ORDER BY` inside aggregate functions. | ||
| - Collation is not applied to window-function `ORDER BY`. | ||
| - Custom collations are not fully reflected by `pg_collation` or `pg_attribute.attcollation`. |
There was a problem hiding this comment.
| - Custom collations are not fully reflected by `pg_collation` or `pg_attribute.attcollation`. | |
| - Custom collations can be used but are not listed in `pg_collation`. |
Reason: The PostgreSQL System Catalog page in the same PR specifically states that custom collations can be used but are not listed in pg_collation. It does not establish the broader claim about pg_attribute.attcollation. The revised wording is also more concrete than "not fully reflected."
qiancai
added
the
do-not-merge/hold
|
@qiqi-power: The following test failed, say
Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
seominjea1942
left a comment
seominjea1942
left a comment
There was a problem hiding this comment.
I dug into the four failing checks so you do not have to read the Actions logs. Three are one-line fixes and I have left them as suggestions below. The fourth is not a problem with your pages.
internal-links-toc, 28 links across 6 targets. The pages are fine. The checker keeps a hardcoded list of valid TiDB Cloud navigation files at scripts/verify-internal-links-in-toc.js line 17, and the new TOC-tidb-cloud-starter-postgresql.md is not on it. Adding it there would clear all 28, but that is shared tooling and a structural decision, so I did not want to suggest it blindly. Worth checking with whoever owns that script.
linkChecker, 7 errors. Six are the new pages not existing on the site yet, and they resolve on merge. The seventh is the _index.md suggestion below, which would stay broken after merge.
Separately, I have a PostgreSQL-compatible Starter instance running and I am going through these pages against it. Three things have already come up that I will raise properly once I have been through everything: the engine is offered in aws-us-east-1 only and no page says which regions support it, the connection user is <prefix>.postgres rather than the <prefix>.root form MySQL uses, and the API cannot set a Postgres password so the console is the only path. Happy to hold those until you have dealt with the checks.
|
|
||
| Arbitrary custom or third-party PostgreSQL extensions cannot be installed. Only extensions explicitly supported by TiDB Cloud are available. | ||
|
|
||
| For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](<link>). |
There was a problem hiding this comment.
The link target is still the literal placeholder <link>, which is what internal-links-files is failing on. pg-extensions-overview.md has both halves of what this sentence promises, the extension table and a ## Limitations section.
| For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](<link>). | |
| For the list of available extensions and extension-specific limitations, see [Supported PostgreSQL extensions](/tidb-cloud/starter/pg-extensions-overview.md). |
| - **Storage**: Includes a monthly free storage quota. | ||
| - **Request Units**: Includes [Request Units (RUs)](/tidb-cloud/tidb-cloud-glossary.md#request-unit-ru) for database operations. | ||
|
|
||
| ### MySQL-compatible Starter |
There was a problem hiding this comment.
This is what internal-links-anchors is failing on, and it affects two pages outside this PR.
Replacing ### Usage quota removed the #usage-quota anchor. The quota content itself moved here unchanged, but three links to the old anchor are now dead: backup-and-restore-serverless.md line 131, and serverless-faqs.md lines 107 and 117. None of those files is in this PR, so the diff does not show the breakage.
Keeping the anchor on this heading fixes all three, since this is where the content went.
| ### MySQL-compatible Starter | |
| ### MySQL-compatible Starter {#usage-quota} |
|
|
||
| <LearningPath label="Migrate" icon="cloud3"> | ||
|
|
||
| [Migrate from PostgreSQL](https://docs.pingcap.com/tidbcloud/starter/Import-with-psql/?plan=starter&compatibility=postgresql) |
There was a problem hiding this comment.
This one will not resolve on merge. The file was renamed to import-with-psql.md with a lowercase i, so this URL will keep returning 404. Every one of the 342 Markdown files under tidb-cloud/ is lowercase, so lowercase is the convention.
| [Migrate from PostgreSQL](https://docs.pingcap.com/tidbcloud/starter/Import-with-psql/?plan=starter&compatibility=postgresql) | |
| [Migrate from PostgreSQL](https://docs.pingcap.com/tidbcloud/starter/import-with-psql/?plan=starter&compatibility=postgresql) |
4 participants
First-time contributors' checklist
What is changed, added, or deleted? (Required)
Which TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions.
What is the related PR or file link(s)?
AI agent involvement
Do your changes match any of the following descriptions?
Summary by CodeRabbit