Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
Ring keeps its PostgreSQL schema in two places inside ring/web/data/. schema.sql is the flattened single source of truth for new databases. migrations/ holds the numbered incremental files that brought existing databases to the same shape. This page explains which one to use and when.
Use the Founder / Developer tabs in the docs sidebar to filter this page. Shared sections apply to both audiences.
Status: ./install.sh setup-db and npm run db:apply-schema currently fail on public checkouts because they look for paths that moved under web/. Also, schema.sql contains CREATE EXTENSION IF NOT EXISTS postgis;, so a plain psql -f data/schema.sql stops with an error on PostgreSQL images that do not ship PostGIS (for example postgres:16-alpine). Use the commands in Step 2 below.
| Older docs said | Current behavior |
|---|---|
Apply schema.sql, then 002, 003, 004 in order | Fresh installs apply only web/data/schema.sql (flattened, version 4.1.0) |
Run ./scripts/run-migration.sh or apply-*-migrations-dev.sh | Those helpers are not in the public tree. Use psql directly |
Install Homebrew postgresql@18 with a bootstrap script | Any PostgreSQL 16 or newer works. The bootstrap script is Ringdom-internal |
Seed news from scripts/seed-news-v1.6.0.sql | That file does not exist. Seeds for currencies, countries, store settings and news categories are inside schema.sql |
data/schema-delta.sql | Not used. Deltas live as numbered files in data/migrations/ |
You do not need to understand SQL to run a Ring clone, but you should know the rule your developer follows: a new database gets one file, an existing database gets only the new files. That rule is what keeps upgrades boring.
One schema file creates every table (109 at version 4.1.0) plus the reference seeds. No replaying of history.
Your developer applies only the numbered files your database has not seen yet, after a backup.
PostgreSQL is the default production backend (k8s-postgres-fcm).
Next-step: run the app against the database you just created.
Same-workflow: apply the schema to the compose Postgres container.
Prerequisite: why k8s-postgres-fcm needs this schema.
See-also: install.sh and the npm db scripts, including the ones that fail today.
Ring keeps its PostgreSQL schema in two places inside ring/web/data/. schema.sql is the flattened single source of truth for new databases. migrations/ holds the numbered incremental files that brought existing databases to the same shape. This page explains which one to use and when.
Use the Founder / Developer tabs in the docs sidebar to filter this page. Shared sections apply to both audiences.
Status: ./install.sh setup-db and npm run db:apply-schema currently fail on public checkouts because they look for paths that moved under web/. Also, schema.sql contains CREATE EXTENSION IF NOT EXISTS postgis;, so a plain psql -f data/schema.sql stops with an error on PostgreSQL images that do not ship PostGIS (for example postgres:16-alpine). Use the commands in Step 2 below.
| Older docs said | Current behavior |
|---|---|
Apply schema.sql, then 002, 003, 004 in order | Fresh installs apply only web/data/schema.sql (flattened, version 4.1.0) |
Run ./scripts/run-migration.sh or apply-*-migrations-dev.sh | Those helpers are not in the public tree. Use psql directly |
Install Homebrew postgresql@18 with a bootstrap script | Any PostgreSQL 16 or newer works. The bootstrap script is Ringdom-internal |
Seed news from scripts/seed-news-v1.6.0.sql | That file does not exist. Seeds for currencies, countries, store settings and news categories are inside schema.sql |
data/schema-delta.sql | Not used. Deltas live as numbered files in data/migrations/ |
You do not need to understand SQL to run a Ring clone, but you should know the rule your developer follows: a new database gets one file, an existing database gets only the new files. That rule is what keeps upgrades boring.
One schema file creates every table (109 at version 4.1.0) plus the reference seeds. No replaying of history.
Your developer applies only the numbered files your database has not seen yet, after a backup.
PostgreSQL is the default production backend (k8s-postgres-fcm).
Next-step: run the app against the database you just created.
Same-workflow: apply the schema to the compose Postgres container.
Prerequisite: why k8s-postgres-fcm needs this schema.
See-also: install.sh and the npm db scripts, including the ones that fail today.
Ring keeps its PostgreSQL schema in two places inside ring/web/data/. schema.sql is the flattened single source of truth for new databases. migrations/ holds the numbered incremental files that brought existing databases to the same shape. This page explains which one to use and when.
Use the Founder / Developer tabs in the docs sidebar to filter this page. Shared sections apply to both audiences.
Status: ./install.sh setup-db and npm run db:apply-schema currently fail on public checkouts because they look for paths that moved under web/. Also, schema.sql contains CREATE EXTENSION IF NOT EXISTS postgis;, so a plain psql -f data/schema.sql stops with an error on PostgreSQL images that do not ship PostGIS (for example postgres:16-alpine). Use the commands in Step 2 below.
| Older docs said | Current behavior |
|---|---|
Apply schema.sql, then 002, 003, 004 in order | Fresh installs apply only web/data/schema.sql (flattened, version 4.1.0) |
Run ./scripts/run-migration.sh or apply-*-migrations-dev.sh | Those helpers are not in the public tree. Use psql directly |
Install Homebrew postgresql@18 with a bootstrap script | Any PostgreSQL 16 or newer works. The bootstrap script is Ringdom-internal |
Seed news from scripts/seed-news-v1.6.0.sql | That file does not exist. Seeds for currencies, countries, store settings and news categories are inside schema.sql |
data/schema-delta.sql | Not used. Deltas live as numbered files in data/migrations/ |
You do not need to understand SQL to run a Ring clone, but you should know the rule your developer follows: a new database gets one file, an existing database gets only the new files. That rule is what keeps upgrades boring.
One schema file creates every table (109 at version 4.1.0) plus the reference seeds. No replaying of history.
Your developer applies only the numbered files your database has not seen yet, after a backup.
PostgreSQL is the default production backend (k8s-postgres-fcm).
Next-step: run the app against the database you just created.
Same-workflow: apply the schema to the compose Postgres container.
Prerequisite: why k8s-postgres-fcm needs this schema.
See-also: install.sh and the npm db scripts, including the ones that fail today.
schema.sql051_likes_uci_favorites_indexes.sql. Your developer backs up, applies that one file, and redeploys.051 and newer can ship a matching .down.sql file so the change can be reverted. Older files do not.DB_HOSTDB_PORTDB_NAMEDB_USERDB_PASSWORDDB_SSLDATABASE_URLRun the next step as a superuser or as the database owner, because schema.sql creates extensions.
If your server has PostGIS installed (for example a postgis/postgis image), apply the file as is:
On plain PostgreSQL, strip the PostGIS line first. No table uses a PostGIS type, so nothing else changes:
Grant your app role (DB_USER) access to the public schema, then start the app.
Apply only the files your database has not seen. Some migrations record themselves in schema_versions with an INSERT ... WHERE NOT EXISTS (016 to 025, 037, 043 to 046, 050, 051). The others do not, so check for the tables or indexes they create before applying.
To roll back a migration that ships a down file, apply 051_likes_uci_favorites_indexes.down.sql the same way. It also deletes its schema_versions row.
Use the next free number after the highest file in data/migrations/. Make it idempotent (IF NOT EXISTS), record it in schema_versions, and add a .down.sql when the change is reversible.
This runs ring/scripts/flatten-schema-from-migrations.sh. It needs a local PostgreSQL where your role can create databases (PGHOST and PGUSER default to localhost and ring_user). It recreates a scratch database ring_schema_flatten, backs up schema.sql as schema.sql.bak-pre-flatten-<timestamp>, applies the prior schema plus all migrations except 001, dumps DDL plus the reference seeds, and verifies the result on ring_schema_flatten_verify. The verify step needs PostGIS for the reason above.
No. Flattening only rewrites the schema.sql file in the repository. Live databases are never touched by it.
schema.sql. Which files do I need?Compare SELECT version FROM schema_versions with the numbered files, then apply the missing ones in order after a backup. Only some files record a version (see Existing database above), so check for their tables if in doubt. Note that a fresh install from today's schema.sql lists versions up to 045 even though the tables and indexes from 046 to 051 are already present.
CREATE EXTENSION postgis fail?Your PostgreSQL build does not include PostGIS. Strip that line as shown in Step 2, or use a PostGIS-enabled image.
schema.sql051_likes_uci_favorites_indexes.sql. Your developer backs up, applies that one file, and redeploys.051 and newer can ship a matching .down.sql file so the change can be reverted. Older files do not.DB_HOSTDB_PORTDB_NAMEDB_USERDB_PASSWORDDB_SSLDATABASE_URLRun the next step as a superuser or as the database owner, because schema.sql creates extensions.
If your server has PostGIS installed (for example a postgis/postgis image), apply the file as is:
On plain PostgreSQL, strip the PostGIS line first. No table uses a PostGIS type, so nothing else changes:
Grant your app role (DB_USER) access to the public schema, then start the app.
Apply only the files your database has not seen. Some migrations record themselves in schema_versions with an INSERT ... WHERE NOT EXISTS (016 to 025, 037, 043 to 046, 050, 051). The others do not, so check for the tables or indexes they create before applying.
To roll back a migration that ships a down file, apply 051_likes_uci_favorites_indexes.down.sql the same way. It also deletes its schema_versions row.
Use the next free number after the highest file in data/migrations/. Make it idempotent (IF NOT EXISTS), record it in schema_versions, and add a .down.sql when the change is reversible.
This runs ring/scripts/flatten-schema-from-migrations.sh. It needs a local PostgreSQL where your role can create databases (PGHOST and PGUSER default to localhost and ring_user). It recreates a scratch database ring_schema_flatten, backs up schema.sql as schema.sql.bak-pre-flatten-<timestamp>, applies the prior schema plus all migrations except 001, dumps DDL plus the reference seeds, and verifies the result on ring_schema_flatten_verify. The verify step needs PostGIS for the reason above.
No. Flattening only rewrites the schema.sql file in the repository. Live databases are never touched by it.
schema.sql. Which files do I need?Compare SELECT version FROM schema_versions with the numbered files, then apply the missing ones in order after a backup. Only some files record a version (see Existing database above), so check for their tables if in doubt. Note that a fresh install from today's schema.sql lists versions up to 045 even though the tables and indexes from 046 to 051 are already present.
CREATE EXTENSION postgis fail?Your PostgreSQL build does not include PostGIS. Strip that line as shown in Step 2, or use a PostGIS-enabled image.
schema.sql051_likes_uci_favorites_indexes.sql. Your developer backs up, applies that one file, and redeploys.051 and newer can ship a matching .down.sql file so the change can be reverted. Older files do not.DB_HOSTDB_PORTDB_NAMEDB_USERDB_PASSWORDDB_SSLDATABASE_URLRun the next step as a superuser or as the database owner, because schema.sql creates extensions.
If your server has PostGIS installed (for example a postgis/postgis image), apply the file as is:
On plain PostgreSQL, strip the PostGIS line first. No table uses a PostGIS type, so nothing else changes:
Grant your app role (DB_USER) access to the public schema, then start the app.
Apply only the files your database has not seen. Some migrations record themselves in schema_versions with an INSERT ... WHERE NOT EXISTS (016 to 025, 037, 043 to 046, 050, 051). The others do not, so check for the tables or indexes they create before applying.
To roll back a migration that ships a down file, apply 051_likes_uci_favorites_indexes.down.sql the same way. It also deletes its schema_versions row.
Use the next free number after the highest file in data/migrations/. Make it idempotent (IF NOT EXISTS), record it in schema_versions, and add a .down.sql when the change is reversible.
This runs ring/scripts/flatten-schema-from-migrations.sh. It needs a local PostgreSQL where your role can create databases (PGHOST and PGUSER default to localhost and ring_user). It recreates a scratch database ring_schema_flatten, backs up schema.sql as schema.sql.bak-pre-flatten-<timestamp>, applies the prior schema plus all migrations except 001, dumps DDL plus the reference seeds, and verifies the result on ring_schema_flatten_verify. The verify step needs PostGIS for the reason above.
No. Flattening only rewrites the schema.sql file in the repository. Live databases are never touched by it.
schema.sql. Which files do I need?Compare SELECT version FROM schema_versions with the numbered files, then apply the missing ones in order after a backup. Only some files record a version (see Existing database above), so check for their tables if in doubt. Note that a fresh install from today's schema.sql lists versions up to 045 even though the tables and indexes from 046 to 051 are already present.
CREATE EXTENSION postgis fail?Your PostgreSQL build does not include PostGIS. Strip that line as shown in Step 2, or use a PostGIS-enabled image.