Skip to main content

← Back to Portal Setup

Return to the Portal setup overview to explore other deployment options.

​
Migrate to the Cloud Portal

​
For users on Solana

Portal is currently in beta. Please report any bugs or suggestions to the SQD Portal Beta chat or to Squid Devs.
The latest version of Portal serves real-time data for Solana. It replaces both gateways of the open private version of SQD Network and traditional RPC endpoints with a unified, high-performance data source. Learn more about Solana indexing with SQD.
We’re currently experimenting with data request complexity limits. If you see an HTTP 400 error with a message like:
Couldn't parse query: query contains X item requests, but only 50 is allowed
where X is above 50, or any other HTTP 400 response, please let us know.

​
Prerequisites

Before you begin, ensure you have:
  • An existing Solana squid using gateways or RPC endpoints
  • Access to your squid’s source code
  • Node.js and your preferred package manager (npm, yarn, or pnpm) installed

​
Portal endpoint

For this migration, you’ll use the following Portal endpoint: 
https://portal.sqd.dev/datasets/solana-beta
A dedicated Cloud Solana Portal with enhanced performance and real-time support will be available soon.

​
Migration steps

1

Install Portal API packages

Portal support requires special @portal-api tagged versions of SQD packages. These versions include Portal-specific features and optimizations for Solana.Navigate to your squid’s folder:
cd your-squid-folder
Remove your lock file and node_modules folder to ensure a clean installation:
rm -r node_modules package-lock.json
Upgrade all SQD packages to their @portal-api versions:
npx --yes npm-check-updates --filter "@subsquid/*" --target "@portal-api" --upgrade
Freeze the versions of @portal-api packages by removing version range specifiers (^, ~, <, >, >=, <=):
sed -i -e 's/[\^~=<>]*\([0-9\.]*-portal-api\.[0-9a-f]\{6\}\)/\1/g' package.json
Freezing package versions prevents unintended updates that could break Portal compatibility. The @portal-api versions are tightly coupled to specific Portal API versions.
Install the updated dependencies:
npm install
Verify that all @subsquid/* packages in your package.json now have -portal-api in their version strings.
2

Update your code

Migrate your data source configuration and update Solana-specific code patterns for Portal compatibility.

​
Replace data sources with Portal

Update your data source builder to use the Portal endpoint instead of gateways or RPC:
+  .setPortal('https://portal.sqd.dev/datasets/solana-beta')
-  .setGateway('https://v2.archive.subsquid.io/network/solana-mainnet')
-  .setRpc({
-    client: new SolanaRpcClient({
-      url: process.env.SOLANA_NODE
-    })
-  })
Remove any imports of SolanaRpcClient from your code:
-import {DataSourceBuilder, SolanaRpcClient} from '@subsquid/solana-stream'
+import {DataSourceBuilder} from '@subsquid/solana-stream'

​
Update block range to use slot numbers

Portal uses slot numbers instead of block heights. Update your block range configuration:
+  .setBlockRange({from: 325000000})
-  .setBlockRange({from: 303262650})
A convenient block height to slot number converter will be added to the documentation soon.

​
Update slot field references

If you reference the slot field of block headers in your code, update it to use .number:
-  slot: block.header.slot,
+  slot: block.header.number,

​
Request block height if needed (optional)

If you need block height for compatibility with existing code or databases, request it explicitly in your fields configuration:
  .setFields({
    block: { // block header fields
      timestamp: true,
+      height: true
    },
Verify your code compiles without errors by running npm run build or equivalent.
3

Test your migration

We highly recommend testing your migrated squid with a full re-sync. This ensures everything works correctly across the entire chain and allows you to catch any issues early.

​
Zero-downtime update procedure

Follow these steps to test without disrupting your production deployment:
  1. Deploy your updated squid into a new slot
  2. Wait for it to sync completely, observing the improved data fetching performance
  3. Assign your production tag to the new deployment to redirect GraphQL requests
You should observe significantly faster data fetching with Portal compared to gateways or RPC endpoints.
Verify that your GraphQL API returns the same data as before and that your squid syncs successfully to the chain head.
See the slots and tags documentation for detailed instructions.

​
Alternative: Continuous operation without re-sync

This workaround is not recommended. Re-syncing is the safest way to ensure your migration is successful.

​
What’s next?

Explore the Soldexer project to see the new client architecture in action and access the most up-to-date documentation on the Portal API. Stay updated on Portal developments in the SQD Portal Beta chat.
Last modified on November 17, 2025