Saving to PostgreSQL

TypeormDatabase context store provides a wrapper over the TypeORM EntityManager optimized for batch saving. It currently supports only Postgres-compatible databases and seamlessly integrates with entity classes generated from the schema file. Check out this section of the reference page to learn how to specify the database connection parameters.

Usage

import { Store, TypeormDatabase } from '@subsquid/typeorm-store'
import { FooEntity } from './model'

const dbOptions = {/* ... constructor options ... */}

processor.run(new TypeormDatabase(dbOptions), async ctx => {
  // ...  
  await ctx.store.upsert([new FooEntity({ id: '1'}), new FooEntity({ id: '2'})])
})

Here,

FooEntity represents a TypeORM entity class. In squids, these are typically generated from schema files with squid-typeorm-codegen.
TypeormDatabase constructor options govern the behavior of the class at the highest level. They are described in this section of the reference.
ctx.store is of type Store. See the Store interface section of the reference page for more details.

Database migrations

The Squid SDK manages the database schema with TypeORM-based database migrations by means of the squid-typeorm-migration(1) tool. The tool auto-generates the schema migrations from the TypeORM entities created by codegen, so that custom migration scripts are rarely needed.

When the DB_SCHEMA environment variable is set, squid-typeorm-migration apply creates that Postgres schema if it is missing and applies the migrations (and its own migrations ledger) inside it. This lets you index several networks into one database from a single codebase — one schema per network. The generated migration files themselves stay schema-neutral, so the same migrations can be applied to any DB_SCHEMA.

Here are some useful commands:

npx squid-typeorm-migration apply # Apply the DB migrations

npx squid-typeorm-migration generate # Generate a DB migration matching the TypeORM entities

rm -r db/migrations # Clean the migrations folder

Inspect the full list of available options with

npx squid-typeorm-migration --help

To generate or update the migrations after a schema change, follow the steps below.

Updating after schema changes

In most cases the simplest way to update the schema is to drop the database and regenerate the migrations from scratch. 1. Update schema.graphql 2. Regenerate the TypeORM entity classes

# generate entites code from the schema file
npx squid-typeorm-codegen

3. Recreate the database

# drop the database
docker compose down

# start a blank database
docker compose up -d

Note that without dropping the database the next step will generate a migration only for the schema difference. 4. Build the squid code

npm run build

5. Recreate the database migration

rm -r db/migrations

npx squid-typeorm-migration generate

6. Apply the database migration

npx squid-typeorm-migration apply

Updating a deployed squid schema

In some rare cases it is possible to update the schema without dropping the database and restarting the squid from a blank state. The most important case is adding an index to an entity field. More complex changes are usually not feasible. Updating a running squid requires that you add an incremental migration. 1. Ensure that your local database is running and has the same schema as the database of your Cloud squid In most situations re-creating the database container and applying existing migrations should be enough:

docker compose down
docker compose up -d
npx squid-typeorm-migration apply

2. Update schema.graphql For example, add an index 3. Regenerate the model classes and build the code

npx squid-typeorm-codegen
npm run build

4. Add a new database migration

npx squid-typeorm-migration generate

This will create a new file in db/migrations. You may want to examine it before proceeding to the next step. 5. Update the squid in Cloud If the squid is deployed to SQD Cloud, update the deployed version. If you’re self-hosting it, update your remote codebase and run

npx squid-typeorm-migration apply

SQD Cloud deployment

By default, the TypeORM migrations are automatically applied by Cloud with the command npx squid-typeorm-migration apply before the squid services are started. For custom behavior, one can override the migration script using the optional migrate: section of squid.yaml.

To force Cloud to reset the database and start with a blank state after a schema change, use the --hard-reset flag of sqd deploy.

Overview

Pipes SDK

Squid SDK

Alternative clients

Usage

Database migrations

Updating after schema changes

Updating a deployed squid schema

SQD Cloud deployment

​Usage

​Database migrations

​Updating after schema changes

​Updating a deployed squid schema

​SQD Cloud deployment

Usage

Database migrations

Updating after schema changes

Updating a deployed squid schema

SQD Cloud deployment