Merge remote-tracking branch 'origin' into flutterflow-guide-v3

benitav · benitav · commit bd264a76943d · 2025-02-05T11:06:23.000-07:00
diff --git a/client-sdk-references/javascript-web/usage-examples.mdx b/client-sdk-references/javascript-web/usage-examples.mdx
@@ -6,7 +6,8 @@ description: "Code snippets and guidelines for common scenarios"
 ## Multiple Tab Support
 
 <Warning>
-  Multiple tab support is not currently available on Android or Safari.
+  * Multiple tab support is not currently available on Android. 
+  * For Safari, use the [`OPFSCoopSyncVFS`](/client-sdk-references/javascript-web#sqlite-virtual-file-systems) virtual file system to ensure stable multi-tab functionality.
 </Warning>
 
 Using PowerSync between multiple tabs is supported on some web browsers. Multiple tab support relies on shared web workers for database and sync streaming operations. When enabled, shared web workers named `shared-DB-worker-[dbFileName]` and `shared-sync-[dbFileName]` will be created.
diff --git a/client-sdk-references/swift.mdx b/client-sdk-references/swift.mdx
@@ -6,7 +6,7 @@ sidebarTitle: "Overview"
 <CardGroup cols={3}>
   <Card title="Source Code" icon="github" href="https://github.com/powersync-ja/powersync-swift/">
   Refer to the powersync-swift repo on GitHub.
-  </Card>  
+  </Card>
   <Card title="API Reference (Coming soon)" icon="book" href="">
   A full API Reference for this SDK is not yet available. This is planned for the V1 release.
   </Card>
@@ -326,7 +326,7 @@ func updateTodo(_ todo: Todo) async throws {
 
 func deleteTodo(id: String) async throws {
     try await db.writeTransaction(callback: { transaction in
-        _ = try await transaction.execute(
+        _ = transaction.execute(
                 sql: "DELETE FROM \(TODOS_TABLE) WHERE id = ?",
                 parameters: [id]
             )
diff --git a/images/migration-guides/mongodb-after.png b/images/migration-guides/mongodb-after.png
diff --git a/images/migration-guides/mongodb-before.png b/images/migration-guides/mongodb-before.png
diff --git a/integration-guides/supabase-+-powersync/handling-attachments.mdx b/integration-guides/supabase-+-powersync/handling-attachments.mdx
@@ -7,7 +7,7 @@ description: "Examples of syncing attachments between a client app and Supabase
 
 Our React Native [To-Do List demo app](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-supabase-todolist) showcases how to sync attachments (such as photos) using the [@powersync/attachments](https://www.npmjs.com/package/@powersync/attachments) library, the PowerSync Service, and Supabase.
 
-In this example, we are syncing photos, however other media types, such as PDFs, are also supported.
+In this example, we are syncing photos, however other media types, such as [PDFs](/tutorials/client/attachments-and-files/pdf-attachment), are also supported.
 
 The library and this example implementation can be used as a reference for implementing similar functionality for a Postgres backend without Supabase.
 
diff --git a/migration-guides/mongodb-atlas.mdx b/migration-guides/mongodb-atlas.mdx
diff --git a/mint.json b/mint.json
@@ -418,7 +418,13 @@
       "group": "Resources",
       "pages": [
         "resources/demo-apps-example-projects",
-        "resources/local-first-software",
+        {
+          "group": "Troubleshooting",
+          "pages": [
+            "resources/troubleshooting",
+            "resources/troubleshooting/error-codes"
+          ]
+        },      
         {
           "group": "Usage & Billing",
           "pages": [
@@ -427,11 +433,11 @@
             "resources/usage-and-billing-faq"
           ]
         },
-        "resources/troubleshooting",
         "resources/performance-and-limits",
         "resources/feature-status",
         "resources/supported-hardware",
         "resources/faq",
+        "resources/local-first-software",
         "resources/release-notes",
         "resources/roadmap",
         "resources/blog",
diff --git a/resources/troubleshooting.mdx b/resources/troubleshooting.mdx
@@ -1,6 +1,7 @@
 ---
 title: "Troubleshooting"
 description: "Summary of common issues, troubleshooting tools and pointers."
+sidebarTitle: "Overview"
 ---
 
 ## Common issues
diff --git a/resources/troubleshooting/error-codes.mdx b/resources/troubleshooting/error-codes.mdx
@@ -0,0 +1,251 @@
+---
+title: "Error Codes Reference"
+description: "Complete list of PowerSync error codes with explanations and troubleshooting guidance."
+sidebarTitle: "Error Codes"
+---
+
+This reference documents PowerSync error codes organized by component, with troubleshooting suggestions for developers. Use the search bar to look up specific error codes (e.g., `PSYNC_R0001`).
+
+# PSYNC_Rxxxx: Sync rules issues
+
+- **PSYNC_R0001**:
+  Catch-all sync rules parsing error, if no more specific error is available
+
+# PSYNC_Sxxxx: Service issues
+
+- **PSYNC_S0001**:
+  Internal assertion.
+  
+  If you see this error, it might indicate a bug in the service code.
+
+- **PSYNC_S0102**:
+  TEARDOWN was not acknowledged.
+  
+  This happens when the TEARDOWN argument was not supplied when running
+  the service teardown command. The TEARDOWN argument is required since
+  this is a destructive command.
+  
+  Run the command with `teardown TEARDOWN` to confirm.
+
+## PSYNC_S1xxx: Replication issues
+
+- **PSYNC_S1002**:
+  Row too large.
+  
+  There is a 15MB size limit on every replicated row - rows larger than
+  this cannot be replicated.
+
+- **PSYNC_S1003**:
+  Sync rules have been locked by another process for replication.
+  
+  This error is normal in some circumstances:
+  1. In some cases, if a process was forcefully terminated, this error may occur for up to a minute.
+  2. During rolling deploys, this error may occur until the old process stops replication.
+  
+  If the error persists for longer, this may indicate that multiple replication processes are running.
+  Make sure there is only one replication process apart from rolling deploys.
+
+- **PSYNC_S1004**:
+  JSON nested object depth exceeds the limit of 20.
+  
+  This may occur if there is very deep nesting in JSON or embedded documents.
+
+## PSYNC_S11xx: Postgres replication issues
+
+- **PSYNC_S1101**:
+  Replication assertion error.
+  
+  If you see this error, it might indicate a bug in the service code.
+
+- **PSYNC_S1103**:
+  Aborted initial replication.
+  
+  This is not an actual error - it is expected when the replication process
+  is stopped, or if replication is stopped for any other reason.
+
+- **PSYNC_S1104**:
+  Explicit cacert is required for `sslmode: verify-ca`.
+  
+  Use either verify-full, or specify a certificate with verify-ca.
+
+- **PSYNC_S1105**:
+  `database` is required in connection config.
+  
+  Specify the database explicitly, or in the `uri` field.
+
+- **PSYNC_S1106**:
+  `hostname` is required in connection config.
+  
+  Specify the hostname explicitly, or in the `uri` field.
+
+- **PSYNC_S1107**:
+  `username` is required in connection config.
+  
+  Specify the username explicitly, or in the `uri` field.
+
+- **PSYNC_S1108**:
+  `password` is required in connection config.
+  
+  Specify the password explicitly, or in the `uri` field.
+
+- **PSYNC_S1109**:
+  Invalid database URI.
+  
+  Check the URI scheme and format.
+
+- **PSYNC_S1110**:
+  Invalid port number.
+  
+  Only ports in the range 1024 - 65535 are supported.
+
+- **PSYNC_S1141**:
+  Publication does not exist.
+  
+  Run: `CREATE PUBLICATION powersync FOR ALL TABLES` on the source database.
+
+- **PSYNC_S1142**:
+  Publication does not publish all changes.
+  
+  Create a publication using `WITH (publish = "insert, update, delete, truncate")` (the default).
+
+- **PSYNC_S1143**:
+  Publication uses publish_via_partition_root.
+
+## PSYNC_S13xx: MongoDB replication issues
+
+- **PSYNC_S1301**:
+  Generic MongoServerError.
+
+- **PSYNC_S1302**:
+  Generic MongoNetworkError.
+
+- **PSYNC_S1303**:
+  MongoDB internal TLS error.
+  
+  If connection to a shared cluster on MongoDB Atlas, this could be an IP Acccess List issue.
+  Check that the service IP is allowed to connect to the cluster.
+
+- **PSYNC_S1304**:
+  MongoDB connection DNS error.
+  
+  Check that the hostname is correct.
+
+- **PSYNC_S1305**:
+  MongoDB connection timeout.
+  
+  Check that the hostname is correct, and that the service IP is allowed to connect to the cluster.
+
+- **PSYNC_S1306**:
+  MongoDB authentication error.
+  
+  Check the username and password.
+
+- **PSYNC_S1307**:
+  MongoDB authorization error.
+  
+  Check that the user has the required priviledges.
+
+- **PSYNC_S1341**:
+  Sharded MongoDB Clusters are not supported yet.
+
+- **PSYNC_S1342**:
+  Standalone MongoDB instances are not supported - use a replicaset.
+
+- **PSYNC_S1343**:
+  PostImages not enabled on a source collection.
+  
+  Use `post_images: auto_configure` to configure post images automatically, or enable manually:
+  
+  ```
+      db.runCommand({
+        collMod: 'collection-name',
+        changeStreamPreAndPostImages: { enabled: true }
+      });
+  ```    
+
+## PSYNC_S14xx: MongoDB storage replication issues
+
+- **PSYNC_S1402**:
+  Max transaction tries exceeded.
+
+## PSYNC_S2xxx: Service API
+
+- **PSYNC_S2001**:
+  Generic internal server error (HTTP 500).
+  
+  See the error details for more info.
+
+- **PSYNC_S2002**:
+  Route not found (HTTP 404).
+
+- **PSYNC_S2003**:
+  503 service unavailable due to restart.
+  
+  Wait a while then retry the request.
+
+## PSYNC_S21xx: Auth errors originating on the client.
+
+This does not include auth configuration errors on the service.
+
+- **PSYNC_S2101**:
+  Generic authentication error.
+
+## PSYNC_S22xx: Auth integration errors
+
+- **PSYNC_S2202**:
+  IPv6 support is not enabled for the JWKS URI.
+  
+  Use an endpoint that supports IPv4.
+
+- **PSYNC_S2203**:
+  IPs in this range are not supported.
+  
+  Make sure to use a publically-accessible JWKS URI.
+
+## PSYNC_S23xx: Sync API errors
+
+- **PSYNC_S2302**:
+  No sync rules available.
+  
+  This error may happen if:
+  1. Sync rules have not been deployed.
+  2. Sync rules have been deployed, but is still busy processing.
+  
+  View the replicator logs to see if the sync rules are being processed.
+
+- **PSYNC_S2304**:
+  Maximum active concurrent connections limit has been reached.
+
+## PSYNC_S23xx: Sync API errors - MongoDB Storage
+
+- **PSYNC_S2401**:
+  Could not get clusterTime.
+
+## PSYNC_S31xx: Auth configuration issues
+
+- **PSYNC_S3102**:
+  Invalid jwks_uri.
+
+- **PSYNC_S3103**:
+  Only http(s) is supported for jwks_uri.
+
+## PSYNC_S32xx: Replication configuration issue.
+
+- **PSYNC_S3201**:
+  Failed to validate module configuration.
+
+## PSYNC_S4000: Management / Dev APIs
+
+- **PSYNC_S4001**:
+  Internal assertion error.
+  
+  This error may indicate a bug in the service code.
+
+- **PSYNC_S4104**:
+  No active sync rules.
+
+- **PSYNC_S4105**:
+  Sync rules API disabled.
+  
+  When a sync rules file is configured, the dynamic sync rules API is disabled.
+
diff --git a/self-hosting/installation/powersync-service-setup.mdx b/self-hosting/installation/powersync-service-setup.mdx
@@ -173,10 +173,6 @@ client_auth:
 
 ```
 
-<Info>
-**Important:** When using Postgres for sync bucket storage, a separate server is currently required for replication connections (if using Postgres for replication) and storage. Using the same server might cause unexpected results.
-</Info>
-
 Specify the connection to Postgres in the `replication` section. Retrieving your database connection string / individual parameters differs by database hosting provider. See [Database Connection](/self-hosting/appendix/database-connection) for further details.
 
 <Info>
@@ -189,6 +185,15 @@ Specify the connection to Postgres in the `replication` section. Retrieving your
 
 Specify the connection to your sync bucket storage provider (Postgres or MongoDB) in the `storage` section.
 
+### Postgres Storage
+
+Separate Postgres servers are required for replication connections and sync bucket storage **if using PostgreSQL versions below 14**.
+
+| PostgreSQL Version | Server configuration                                                                                                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Below 14           | Separate servers are required for the source and sync bucket storage. Replication will be blocked if the same server is detected.                                                                                        |
+| 14 and above       | The source database and sync bucket storage database can be on the same server. Using the same database (with separate schemas) is supported but may lead to higher CPU usage. Using separate servers remains an option. |
+
 ### Environment Variables
 
 The config file uses custom tags for environment variable substitution.
diff --git a/snippets/create-cloud-instance.mdx b/snippets/create-cloud-instance.mdx
@@ -6,5 +6,5 @@
 
 2. Give your instance a name, such as "Testing".
 3. Under the "**General**" tab, you can change the default cloud region from US to EU, JP (Japan), AU (Australia) or BR (Brazil) if desired.
-   * Note: More cloud regions are available, [contact us](/resources/contact-us) if you need a different region.
+   * Note: Additional cloud regions will be considered on request, especially for customers on our Enterprise plan. Please [contact us](/resources/contact-us) if you need a different region.
 4. Under the **"DB Connections"** tab, click on the **+** icon and select your database technology.
