store: Split subgraph_deployment table

We split the table `subgraphs.subgraph_deployment` into two tables,
`subgraphs.head` and `subgraphs.deployment` where the `head` table only
contains the metadata that changes on every block.

This should help with situations where the `subgraph_deployment` table gets
very bloated since the `head` table that gets bloated through frequent
changes has much smaller rows than the current `subgraph_deployment`
table. Rows in `subgraph_deployment` can grow as big as 500k, whereas rows
in the `head` table will only take about 350 bytes at most.

Updates will also be marginally better on the `heads` table since it only
has one index rather than the two that `subgraph_deployment` has.

Author: lutter

docs/implementation/metadata.md

@@ -7,7 +7,7 @@
 List of all known subgraph names. Maintained in the primary, but there is a background job that periodically copies the table from the primary to all other shards. Those copies are used for queries when the primary is down.
 
 | Column            | Type         | Use                                       |
-|-------------------|--------------|-------------------------------------------|
+| ----------------- | ------------ | ----------------------------------------- |
 | `id`              | `text!`      | primary key, UUID                         |
 | `name`            | `text!`      | user-chosen name                          |
 | `current_version` | `text`       | `subgraph_version.id` for current version |
@@ -18,29 +18,27 @@ List of all known subgraph names. Maintained in the primary, but there is a back
 
 The `id` is used by the hosted explorer to reference the subgraph.
 
-
 ### `subgraphs.subgraph_version`
 
 Mapping of subgraph names from `subgraph` to IPFS hashes. Maintained in the primary, but there is a background job that periodically copies the table from the primary to all other shards. Those copies are used for queries when the primary is down.
 
 | Column        | Type         | Use                     |
-|---------------|--------------|-------------------------|
+| ------------- | ------------ | ----------------------- |
 | `id`          | `text!`      | primary key, UUID       |
 | `subgraph`    | `text!`      | `subgraph.id`           |
 | `deployment`  | `text!`      | IPFS hash of deployment |
 | `created_at`  | `numeric`    | UNIX timestamp          |
 | `vid`         | `int8!`      | unused                  |
 | `block_range` | `int4range!` | unused                  |
 
-
 ## Managing a deployment
 
 Directory of all deployments. Maintained in the primary, but there is a background job that periodically copies the table from the primary to all other shards. Those copies are used for queries when the primary is down.
 
 ### `public.deployment_schemas`
 
 | Column       | Type           | Use                                          |
-|--------------|----------------|----------------------------------------------|
+| ------------ | -------------- | -------------------------------------------- |
 | `id`         | `int4!`        | primary key                                  |
 | `subgraph`   | `text!`        | IPFS hash of deployment                      |
 | `name`       | `text!`        | name of `sgdNNN` schema                      |
@@ -52,36 +50,46 @@ Directory of all deployments. Maintained in the primary, but there is a backgrou
 
 There can be multiple copies of the same deployment, but at most one per shard. The `active` flag indicates which of these copies will be used for queries; `graph-node` makes sure that there is always exactly one for each IPFS hash.
 
-### `subgraphs.subgraph_deployment`
+### `subgraphs.head`
+
+Details about a deployment that change on every block. Maintained in the
+shard alongside the deployment's data in `sgdNNN`.
+
+| Column            | Type       | Use                                          |
+| ----------------- | ---------- | -------------------------------------------- |
+| `id`              | `integer!` | primary key, same as `deployment_schemas.id` |
+| `block_hash`      | `bytea`    | current subgraph head                        |
+| `block_number`    | `numeric`  |                                              |
+| `entity_count`    | `numeric!` | total number of entities                     |
+| `firehose_cursor` | `text`     |                                              |
+
+### `subgraphs.deployment`
 
 Details about a deployment to track sync progress etc. Maintained in the
 shard alongside the deployment's data in `sgdNNN`. The table should only
-contain frequently changing data, but for historical reasons contains also
-static data.
-
-| Column                               | Type       | Use                                          |
-|--------------------------------------|------------|----------------------------------------------|
-| `id`                                 | `integer!` | primary key, same as `deployment_schemas.id` |
-| `deployment`                         | `text!`    | IPFS hash                                    |
-| `failed`                             | `boolean!` |                                              |
-| `synced`                             | `boolean!` |                                              |
-| `earliest_block_number`              | `integer!` | earliest block for which we have data        |
-| `latest_ethereum_block_hash`         | `bytea`    | current subgraph head                        |
-| `latest_ethereum_block_number`       | `numeric`  |                                              |
-| `entity_count`                       | `numeric!` | total number of entities                     |
-| `graft_base`                         | `text`     | IPFS hash of graft base                      |
-| `graft_block_hash`                   | `bytea`    | graft block                                  |
-| `graft_block_number`                 | `numeric`  |                                              |
-| `reorg_count`                        | `integer!` |                                              |
-| `current_reorg_depth`                | `integer!` |                                              |
-| `max_reorg_depth`                    | `integer!` |                                              |
-| `fatal_error`                        | `text`     |                                              |
-| `non_fatal_errors`                   | `text[]`   |                                              |
-| `health`                             | `health!`  |                                              |
-| `last_healthy_ethereum_block_hash`   | `bytea`    |                                              |
-| `last_healthy_ethereum_block_number` | `numeric`  |                                              |
-| `firehose_cursor`                    | `text`     |                                              |
-| `debug_fork`                         | `text`     |                                              |
+contain data that changes fairly infrequently, but for historical reasons
+contains also static data.
+
+| Column                               | Type          | Use                                                  |
+| ------------------------------------ | ------------- | ---------------------------------------------------- |
+| `id`                                 | `integer!`    | primary key, same as `deployment_schemas.id`         |
+| `subgraph`                           | `text!`       | IPFS hash                                            |
+| `earliest_block_number`              | `integer!`    | earliest block for which we have data                |
+| `health`                             | `health!`     |                                                      |
+| `failed`                             | `boolean!`    |                                                      |
+| `fatal_error`                        | `text`        |                                                      |
+| `non_fatal_errors`                   | `text[]`      |                                                      |
+| `graft_base`                         | `text`        | IPFS hash of graft base                              |
+| `graft_block_hash`                   | `bytea`       | graft block                                          |
+| `graft_block_number`                 | `numeric`     |                                                      |
+| `reorg_count`                        | `integer!`    |                                                      |
+| `current_reorg_depth`                | `integer!`    |                                                      |
+| `max_reorg_depth`                    | `integer!`    |                                                      |
+| `last_healthy_ethereum_block_hash`   | `bytea`       |                                                      |
+| `last_healthy_ethereum_block_number` | `numeric`     |                                                      |
+| `debug_fork`                         | `text`        |                                                      |
+| `synced_at`                          | `timestamptz` | time when deployment first reach chain head          |
+| `synced_at_block_number`             | `integer`     | block number where deployment first reach chain head |
 
 The columns `reorg_count`, `current_reorg_depth`, and `max_reorg_depth` are
 set during indexing. They are used to determine whether a reorg happened
@@ -94,7 +102,7 @@ Details about a deployment that rarely change. Maintained in the
 shard alongside the deployment's data in `sgdNNN`.
 
 | Column                  | Type       | Use                                                  |
-|-------------------------|------------|------------------------------------------------------|
+| ----------------------- | ---------- | ---------------------------------------------------- |
 | `id`                    | `integer!` | primary key, same as `deployment_schemas.id`         |
 | `spec_version`          | `text!`    |                                                      |
 | `description`           | `text`     |                                                      |
@@ -115,7 +123,7 @@ but there is a background job that periodically copies the table from the
 primary to all other shards.
 
 | Column  | Type  | Use                                         |
-|---------|-------|---------------------------------------------|
+| ------- | ----- | ------------------------------------------- |
 | id      | int4! | primary key, ref to `deployment_schemas.id` |
 | node_id | text! | name of index node                          |
 
@@ -147,7 +155,7 @@ should have the 'account-like' optimization turned on.
 Details about features that a deployment uses, Maintained in the primary.
 
 | Column         | Type      | Use         |
-|----------------|-----------|-------------|
+| -------------- | --------- | ----------- |
 | `id`           | `text!`   | primary key |
 | `spec_version` | `text!`   |             |
 | `api_version`  | `text`    |             |

node/src/manager/commands/unused_deployments.rs

@@ -64,7 +64,7 @@ pub fn record(store: Arc<SubgraphStore>) -> Result<(), Error> {
     let recorded = store.record_unused_deployments()?;
 
     for unused in store.list_unused_deployments(unused::Filter::New)? {
-        if recorded.iter().any(|r| r.deployment == unused.deployment) {
+        if recorded.iter().any(|r| r.subgraph == unused.deployment) {
             add_row(&mut list, unused);
         }
     }

store/postgres/migrations/2025-05-13-173523_split_subgraph_deployment/down.sql

@@ -0,0 +1,110 @@
+create table subgraphs.subgraph_deployment (
+    id int4 primary key,
+
+    deployment text unique not null,
+
+    latest_ethereum_block_hash bytea,
+    latest_ethereum_block_number numeric,
+    entity_count numeric NOT NULL,
+    firehose_cursor text,
+
+    earliest_block_number integer DEFAULT 0 NOT NULL,
+
+    graft_base text,
+    graft_block_hash bytea,
+    graft_block_number numeric,
+
+    health text NOT NULL,
+    failed boolean NOT NULL,
+    fatal_error text,
+    non_fatal_errors text[] DEFAULT '{}'::text[],
+
+    reorg_count integer DEFAULT 0 NOT NULL,
+    current_reorg_depth integer DEFAULT 0 NOT NULL,
+    max_reorg_depth integer DEFAULT 0 NOT NULL,
+
+    last_healthy_ethereum_block_hash bytea,
+    last_healthy_ethereum_block_number numeric,
+
+    debug_fork text,
+
+    synced_at timestamp with time zone,
+    synced_at_block_number integer,
+
+    constraint subgraph_deployment_health_new_check
+      check ((health = any (array['failed', 'healthy', 'unhealthy'])))
+);
+
+insert into subgraphs.subgraph_deployment
+ (id, deployment,
+  latest_ethereum_block_hash, latest_ethereum_block_number,
+  entity_count, firehose_cursor,
+  earliest_block_number,
+  graft_base, graft_block_hash, graft_block_number,
+  health, failed, fatal_error, non_fatal_errors,
+  reorg_count, current_reorg_depth, max_reorg_depth,
+  last_healthy_ethereum_block_hash, last_healthy_ethereum_block_number,
+  debug_fork,
+  synced_at, synced_at_block_number)
+select h.id, d.subgraph,
+  h.block_hash, h.block_number,
+  h.entity_count, h.firehose_cursor,
+  earliest_block_number,
+  graft_base, graft_block_hash, graft_block_number,
+  health, failed, fatal_error, non_fatal_errors,
+  reorg_count, current_reorg_depth, max_reorg_depth,
+  last_healthy_block_hash, last_healthy_block_number,
+  debug_fork,
+  synced_at, synced_at_block_number
+  from subgraphs.head h, subgraphs.deployment d
+ where h.id = d.id;
+
+alter table subgraphs.copy_state
+ drop constraint copy_state_dst_fkey,
+  add constraint copy_state_dst_fkey
+      foreign key (dst) references
+      subgraphs.subgraph_deployment(id) on delete cascade;
+
+alter table subgraphs.subgraph_error
+ drop constraint subgraph_error_subgraph_id_fkey,
+  add constraint subgraph_error_subgraph_id_fkey
+      foreign key (subgraph_id) references
+      subgraphs.subgraph_deployment(deployment) on delete cascade;
+
+alter table subgraphs.subgraph_manifest
+ drop constraint subgraph_manifest_id_fkey,
+  add constraint subgraph_manifest_new_id_fkey
+      foreign key (id) references
+      subgraphs.subgraph_deployment(id) on delete cascade;
+
+alter table subgraphs.table_stats
+ drop constraint table_stats_deployment_fkey,
+  add constraint table_stats_deployment_fkey
+      foreign key (deployment) references
+      subgraphs.subgraph_deployment(id) on delete cascade;
+
+drop view info.subgraph_info;
+
+create view info.subgraph_info as
+select ds.id AS schema_id,
+       ds.name AS schema_name,
+       ds.subgraph,
+       ds.version,
+       s.name,
+           CASE
+               WHEN s.pending_version = v.id THEN 'pending'::text
+               WHEN s.current_version = v.id THEN 'current'::text
+               ELSE 'unused'::text
+           END AS status,
+       d.failed,
+       d.synced_at
+  from deployment_schemas ds,
+       subgraph_deployment d,
+       subgraph_version v,
+       subgraph s
+  where d.id = ds.id
+    and v.deployment = d.deployment
+    and v.subgraph = s.id;
+
+drop table subgraphs.deployment;
+drop table subgraphs.head;

store/postgres/migrations/2025-05-13-173523_split_subgraph_deployment/up.sql

@@ -0,0 +1,116 @@
+create table subgraphs.head (
+    id                    int4 primary key,
+    entity_count          int8 not null,
+    block_number          int4,
+    block_hash            bytea,
+    firehose_cursor       text
+);
+
+create table subgraphs.deployment (
+    id                        int4 primary key,
+
+    subgraph                text unique not null,
+
+    earliest_block_number     int4 default 0 not null,
+
+    health                    text not null,
+    failed                    boolean not null,
+    fatal_error               text,
+    non_fatal_errors          text[] default '{}'::text[],
+
+    graft_base                text,
+    graft_block_hash          bytea,
+    graft_block_number        int4,
+
+    reorg_count               int4 default 0 not null,
+    current_reorg_depth       int4 default 0 not null,
+    max_reorg_depth           int4 default 0 not null,
+
+    last_healthy_block_hash   bytea,
+    last_healthy_block_number int4,
+
+    debug_fork                text,
+
+    synced_at                 timestamptz,
+    synced_at_block_number    int4,
+
+    constraint deployment_health_new_check
+      check ((health = any (array['failed', 'healthy', 'unhealthy']))),
+    constraint deployment_id
+      foreign key (id) references subgraphs.head(id) on delete cascade
+);
+
+insert into subgraphs.head
+  (id, block_hash, block_number, entity_count, firehose_cursor)
+select id, latest_ethereum_block_hash,
+       latest_ethereum_block_number, entity_count, firehose_cursor
+  from subgraphs.subgraph_deployment;
+
+insert into subgraphs.deployment
+  (id, subgraph, failed, graft_base, graft_block_hash, graft_block_number,
+   fatal_error, non_fatal_errors, reorg_count, current_reorg_depth,
+   max_reorg_depth,
+   last_healthy_block_hash, last_healthy_block_number,
+   debug_fork, earliest_block_number,
+   health,
+   synced_at, synced_at_block_number)
+select
+   id, deployment, failed, graft_base, graft_block_hash, graft_block_number,
+   fatal_error, non_fatal_errors, reorg_count, current_reorg_depth,
+   max_reorg_depth,
+   last_healthy_ethereum_block_hash, last_healthy_ethereum_block_number,
+   debug_fork, earliest_block_number,
+   health,
+   synced_at, synced_at_block_number
+from subgraphs.subgraph_deployment;
+
+-- Support joining with subgraph_error
+create index deployment_fatal_error
+    on subgraphs.deployment(fatal_error);
+
+alter table subgraphs.copy_state
+ drop constraint copy_state_dst_fkey,
+  add constraint copy_state_dst_fkey
+      foreign key (dst) references subgraphs.deployment(id) on delete cascade;
+
+alter table subgraphs.subgraph_error
+ drop constraint subgraph_error_subgraph_id_fkey,
+  add constraint subgraph_error_subgraph_id_fkey
+      foreign key (subgraph_id) references
+      subgraphs.deployment(subgraph) on delete cascade;
+
+alter table subgraphs.subgraph_manifest
+ drop constraint subgraph_manifest_new_id_fkey,
+  add constraint subgraph_manifest_id_fkey
+      foreign key (id) references subgraphs.deployment(id) on delete cascade;
+
+alter table subgraphs.table_stats
+ drop constraint table_stats_deployment_fkey,
+  add constraint table_stats_deployment_fkey
+      foreign key (deployment) references subgraphs.deployment(id)
+      on delete cascade;
+
+drop view info.subgraph_info;
+
+drop table subgraphs.subgraph_deployment;
+
+create view info.subgraph_info as
+select ds.id as schema_id,
+       ds.name as schema_name,
+       ds.subgraph,
+       ds.version,
+       s.name,
+        CASE
+            WHEN s.pending_version = v.id THEN 'pending'
+            WHEN s.current_version = v.id THEN 'current'
+            ELSE 'unused'
+        END AS status,
+       d.failed,
+       d.synced_at
+  from deployment_schemas ds,
+       subgraphs.deployment d,
+       subgraphs.subgraph_version v,
+       subgraphs.subgraph s
+ where d.id = ds.id
+   and v.deployment = d.subgraph
+   and v.subgraph = s.id;

store/postgres/src/chain_store.rs

@@ -2394,10 +2394,10 @@ impl ChainStoreTrait for ChainStore {
                           where name = $2)), -1)::int as block
               from (
                 select min(d.latest_ethereum_block_number) as block
-                  from subgraphs.subgraph_deployment d,
+                  from subgraphs.deployment d,
                        subgraphs.subgraph_deployment_assignment a,
                        deployment_schemas ds
-                 where ds.subgraph = d.deployment
+                 where ds.id = d.id
                    and a.id = d.id
                    and not d.failed
                    and ds.network = $2) a;";