SuperTokens

https://github.com/supertokens/supertokens-core
Admin
SuperTokens is an open-source authentication provider offering secure login, session management,...
Tokens:484,921
Snippets:2,624
Trust Score:9.3
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install SuperTokens CLI: copy config and run java install command

Source: https://github.com/supertokens/supertokens-core/blob/master/CONTRIBUTING.md

Manual installation of the SuperTokens CLI requires copying the example config into the project root and then running the Java main class from the cli folder. These are sequential steps in the same installation workflow.

```bash
cp temp/config.yaml .
```

```java
java -classpath "./cli/*" io.supertokens.cli.Main true install
```

--------------------------------

### Install OpenJDK 21.0.7 on Linux (Ubuntu)

Source: https://github.com/supertokens/supertokens-core/wiki/Installing-OpenJDK-for-Mac-and-Linux

Install OpenJDK 21.0.7 on Ubuntu by creating /usr/java, moving and extracting the downloaded archive, renaming the JDK directory, and setting environment variables in /etc/profile. Verify with java -version.

```bash
sudo mkdir /usr/java
```

```bash
mv OpenJDK21U-jdk_x64_linux_hotspot_21.0.7_6.tar.gz /usr/java
```

```bash
cd /usr/java
```

```bash
sudo tar -xzvf OpenJDK21U-jdk_x64_linux_hotspot_21.0.7_6.tar.gz
```

```bash
mv /usr/java/jdk-21.0.7+6 /usr/java/jdk-21.0.7
```

```bash
JAVA_HOME=/usr/java/jdk-21.0.7
PATH=$PATH:$HOME/bin:$JAVA_HOME/bin  
export JAVA_HOME  
export JRE_HOME  
export PATH
```

```bash
java -version
```

--------------------------------

### Install SuperTokens using CLI

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

Installs SuperTokens on the machine. May require sudo. After installation, check with 'supertokens' and uninstall with 'supertokens uninstall'.

```bash
java -classpath "./cli/*" io.supertokens.cli.Main true install
```

--------------------------------

### Run startTestingEnv script

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

Starts the testing environment. Must be kept running during subsequent steps.

```bash
./startTestingEnv --wait
```

--------------------------------

### Run tests and start core locally

Source: https://github.com/supertokens/supertokens-core/blob/master/CONTRIBUTING.md

Commands used to run and test the Supertokens core locally. First, run all tests with './startTestEnv'. Then, to run the core manually, execute 'startTestEnv --wait' in one terminal important terminal, copy the config file, and start the core with the Java command, which listens on http://localhost:3567.

```shell
./startTestEnv

```

```shell
startTestEnv --wait

```

```shell
cp ./temp/config.yaml .

```

```shell
java -classpath "./core/*:./plugin-interface/*:./ee/*" io.supertokens.Main ./ DEV

```

--------------------------------

### Verify schema after booting new binaries

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Run these psql commands to confirm the new tables and columns exist after starting the new core in LEGACY mode. Expect the time_joined and primary_or_recipe_user_time_joined columns on app_id_to_user_id.

```sql
\dt recipe_user_account_infos
\dt recipe_user_tenants
\dt primary_user_tenants
\d+ app_id_to_user_id      -- expect time_joined, primary_or_recipe_user_time_joined columns
```

--------------------------------

### Run docker container

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

Starts the docker container, defaulting to in-memory database, mapping port 3567.

```bash
docker run -p 3567:3567 supertokens
```

--------------------------------

### Install OpenJDK 21.0.7 on Mac

Source: https://github.com/supertokens/supertokens-core/wiki/Installing-OpenJDK-for-Mac-and-Linux

Install OpenJDK 21.0.7 on macOS by extracting the downloaded archive and moving the JDK folder to /Library/Java/JavaVirtualMachines/. Verify with java -version; if the version is not 21.0.7, switch the default Java version.

```bash
tar -xzvf OpenJDK21U-jdk_aarch64_mac_hotspot_21.0.7_6.tar.gz
```

```bash
sudo mv jdk-21.0.7+6 /Library/Java/JavaVirtualMachines/
```

```bash
java -version
```

--------------------------------

### GET /migration/backfill/progress?verify=true - Verify backfill completeness

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Runs the 'verifyBackfillCompleteness' scan and returns 'inconsistentUsersCount'. Expect 0 for a successful backfill.

```http
GET /migration/backfill/progress?verify=true
```

--------------------------------

### Run SuperTokens core directly with java

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

Runs the core without installing, using java directly.

```bash
java -Djava.security.egd=file:/dev/urandom -classpath "./core/*:./plugin-interface/*" io.supertokens.Main ./
```

--------------------------------

### GET /migration/backfill/progress - Check backfill progress

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Returns an object with a 'cuds' array containing per-CUD progress. Wait until 'pendingUsers' is 0 for every CUD being migrated.

```http
GET /migration/backfill/progress
```

--------------------------------

### Dockerfile lines to remove

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

These lines in the Dockerfile download and install SuperTokens from the internet. They should be removed.

```dockerfile
ARG PLUGIN_NAME=mysql
ARG PLAN_TYPE=FREE
ARG CORE_VERSION=2.4.0
ARG PLUGIN_VERSION=1.3.0
RUN apt-get update && apt-get install -y curl zip
RUN curl -o supertokens.zip -s -X GET \
   "https://api.supertokens.io/0/app/download?pluginName=$PLUGIN_NAME&os=linux&mode=DEV&binary=$PLAN_TYPE&targetCore=$CORE_VERSION&targetPlugin=$PLUGIN_VERSION" \
   -H "api-version: 0"
RUN unzip supertokens.zip
RUN cd supertokens && ./install
```

--------------------------------

### Backfill progress log output

Source: https://github.com/supertokens/supertokens-core/blob/master/docs/CUTOVER-PROCEDURE.md

Sample log output from the BackfillReservationTables cron job, showing progress messages from start to completion. Use to monitor backfill progress in logs.

```text
Backfill starting: 50000 users pending for app public
Backfill progress: 10000/50000 users processed
Backfill progress: 20000/50000 users processed
...
Backfill complete and verified: 50000 users processed
```

--------------------------------

### JSON test case structure for tenant create/update

Source: https://github.com/supertokens/supertokens-core/blob/master/test-data/README.md

Defines the JSON schema for each test case file. Fields include tenantId, cv, uv, cbody, ubody, tenantState, g4, g5, gv2, and invalidConfig. The comments indicate the purpose of each field, such as CDI versions for creation and update, expected outputs for different GET API versions, and whether the config is invalid.

```json
{
  "tenantId": "public", // public or non public
  "cv": "4", // CDI version used for tenant creation
  "uv": "4", // CDI version used fo updating the tenant
  "cbody": {
    // ... body of the create operation
  },
  "ubody": {
    // ... body of the update operation
  },
  "tenantState": { // state stored in the db
    "tenantId": "public",
    "emailPasswordEnabled": true,
    "passwordlessEnabled": true,
    "thirdPartyEnabled": true,
    "firstFactors": null,
    "requiredSecondaryFactors": null
  },
  "g4": { // expected output from GET tenant API for CDI version 4
    "emailPasswordEnabled": true,
    "thirdPartyEnabled": true,
    "passwordlessEnabled": true
  },
  "g5": { // expected output from GET tenant API for CDI version 5
    "emailPasswordEnabled": true,
    "thirdPartyEnabled": true,
    "passwordlessEnabled": true,
    "firstFactors": null,
    "requiredSecondaryFactors": null
  },
  "gv2": { // expected output from GET tenant API for CDI version 5.1
    "firstFactors": null, 
    "requiredSecondaryFactors": null },
  "invalidConfig": false // Indicates if create or update should result in an invalid config error
}
```

--------------------------------

### Create activity_log table with range partitioning

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Creates an append-only activity_log table partitioned by RANGE on created_at, with a DEFAULT partition as a backstop. Includes a BRIN index on created_at. The core pre-creates current/next month partitions at boot and the CleanupActivityLogPartitions cron maintains monthly partitions.

```sql
-- activity_log audit table (core 12.0.3 / postgresql-plugin 9.5.2):
-- append-only, range-partitioned by created_at into one partition per UTC month.

CREATE TABLE IF NOT EXISTS activity_log (
    id                        BIGINT GENERATED ALWAYS AS IDENTITY,
    app_id                    VARCHAR(64)  NOT NULL DEFAULT 'public',
    tenant_id                 VARCHAR(64)  NOT NULL DEFAULT 'public',
    recipe_user_id            VARCHAR(128),
    primary_or_recipe_user_id VARCHAR(128),
    event_type                VARCHAR(64)  NOT NULL,
    status                    VARCHAR(128),
    auth_principal            VARCHAR(256),
    identifier                VARCHAR(256),
    created_at                BIGINT       NOT NULL,
    payload                   TEXT
) PARTITION BY RANGE (created_at);

-- DEFAULT partition is a backstop; the core pre-creates the current/next month at boot
-- and the CleanupActivityLogPartitions cron maintains the monthly partitions thereafter.
CREATE TABLE IF NOT EXISTS activity_log_default PARTITION OF activity_log DEFAULT;

CREATE INDEX IF NOT EXISTS activity_log_created_at_brin ON activity_log USING brin (created_at);
```

--------------------------------

### Pre-flight: Recreate foreign keys and create pagination indexes

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Drops and re-adds foreign key constraints on all_auth_recipe_users, emailpassword_users, thirdparty_users, passwordless_users, webauthn_users, webauthn_account_recovery_tokens, and userid_mapping to reference app_id_to_user_id with ON DELETE CASCADE ON UPDATE CASCADE. Then creates four pagination indexes on app_id_to_user_id. Includes a COMMIT statement.

```sql
ALTER TABLE all_auth_recipe_users
    DROP CONSTRAINT all_auth_recipe_users_primary_or_recipe_user_id_fkey;
ALTER TABLE all_auth_recipe_users
    ADD CONSTRAINT all_auth_recipe_users_primary_or_recipe_user_id_fkey
    FOREIGN KEY (app_id, primary_or_recipe_user_id)
    REFERENCES app_id_to_user_id (app_id, user_id) ON DELETE CASCADE ON UPDATE CASCADE;

ALTER TABLE all_auth_recipe_users
    DROP CONSTRAINT all_auth_recipe_users_user_id_fkey;
ALTER TABLE all_auth_recipe_users
    ADD CONSTRAINT all_auth_recipe_users_user_id_fkey
    FOREIGN KEY (app_id, user_id)
    REFERENCES app_id_to_user_id (app_id, user_id) ON DELETE CASCADE ON UPDATE CASCADE;

ALTER TABLE emailpassword_users
    DROP CONSTRAINT emailpassword_users_user_id_fkey;
ALTER TABLE emailpassword_users
    ADD CONSTRAINT emailpassword_users_user_id_fkey
    FOREIGN KEY (app_id, user_id)
    REFERENCES app_id_to_user_id (app_id, user_id) ON DELETE CASCADE ON UPDATE CASCADE;

ALTER TABLE thirdparty_users
    DROP CONSTRAINT thirdparty_users_user_id_fkey;
ALTER TABLE thirdparty_users
    ADD CONSTRAINT thirdparty_users_user_id_fkey
    FOREIGN KEY (app_id, user_id)
    REFERENCES app_id_to_user_id (app_id, user_id) ON DELETE CASCADE ON UPDATE CASCADE;

ALTER TABLE passwordless_users
    DROP CONSTRAINT passwordless_users_user_id_fkey;
ALTER TABLE passwordless_users
    ADD CONSTRAINT passwordless_users_user_id_fkey
    FOREIGN KEY (app_id, user_id)
    REFERENCES app_id_to_user_id (app_id, user_id) ON DELETE CASCADE ON UPDATE CASCADE;

ALTER TABLE webauthn_users
    DROP CONSTRAINT webauthn_users_user_id_fkey;
ALTER TABLE webauthn_users
    ADD CONSTRAINT webauthn_users_user_id_fkey
    FOREIGN KEY (app_id, user_id)
    REFERENCES app_id_to_user_id (app_id, user_id) ON DELETE CASCADE ON UPDATE CASCADE;

ALTER TABLE webauthn_account_recovery_tokens
    DROP CONSTRAINT webauthn_account_recovery_token_user_id_fkey;
ALTER TABLE webauthn_account_recovery_tokens
    ADD CONSTRAINT webauthn_account_recovery_token_user_id_fkey
    FOREIGN KEY (app_id, user_id)
    REFERENCES app_id_to_user_id (app_id, user_id) ON DELETE CASCADE ON UPDATE CASCADE;

ALTER TABLE userid_mapping
    DROP CONSTRAINT userid_mapping_supertokens_user_id_fkey;
ALTER TABLE userid_mapping
    ADD CONSTRAINT userid_mapping_supertokens_user_id_fkey
    FOREIGN KEY (app_id, supertokens_user_id)
    REFERENCES app_id_to_user_id (app_id, user_id) ON DELETE CASCADE ON UPDATE CASCADE;

COMMIT;

CREATE INDEX CONCURRENTLY IF NOT EXISTS app_id_to_user_id_pagination_index1 ON app_id_to_user_id
    (app_id, primary_or_recipe_user_time_joined DESC, primary_or_recipe_user_id DESC);
CREATE INDEX CONCURRENTLY IF NOT EXISTS app_id_to_user_id_pagination_index2 ON app_id_to_user_id
    (app_id, primary_or_recipe_user_time_joined ASC, primary_or_recipe_user_id DESC);
CREATE INDEX CONCURRENTLY IF NOT EXISTS app_id_to_user_id_pagination_index3 ON app_id_to_user_id
    (recipe_id, app_id, primary_or_recipe_user_time_joined DESC, primary_or_recipe_user_id DESC);
CREATE INDEX CONCURRENTLY IF NOT EXISTS app_id_to_user_id_pagination_index4 ON app_id_to_user_id
    (recipe_id, app_id, primary_or_recipe_user_time_joined ASC, primary_or_recipe_user_id DESC);
```

--------------------------------

### List files in supertokens-root

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

Verifies that the core, plugin, and plugin-interface folders are present.

```bash
ls
```

--------------------------------

### Verify dual-write with SQL queries

Source: https://github.com/supertokens/supertokens-core/blob/master/docs/CUTOVER-PROCEDURE.md

SQL verification queries to confirm dual-write is working. After creating a test user, both tables should show new entries.

```sql
-- Create a test user, then verify dual-write:
SELECT COUNT(*) FROM recipe_user_account_infos WHERE app_id = 'public';
-- Should show new entries for recently created users

SELECT COUNT(*) FROM all_auth_recipe_users WHERE app_id = 'public';
-- Should also have entries (still being written)
```

--------------------------------

### Build docker image

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

Builds the docker image with the tag 'supertokens'.

```bash
docker build -t supertokens .
```

--------------------------------

### Verify migration with verification queries

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Run these SQL queries to check that all users have time_joined, reservation rows, and primary reservations. All three should return 0.

```sql
-- Users still missing time_joined
SELECT COUNT(*) FROM app_id_to_user_id WHERE time_joined = 0;

-- Users missing reservation rows
SELECT COUNT(*) FROM app_id_to_user_id a
LEFT JOIN recipe_user_account_infos rai
  ON a.app_id = rai.app_id AND a.user_id = rai.recipe_user_id
WHERE rai.recipe_user_id IS NULL;

-- Linked users missing primary reservations
SELECT COUNT(*) FROM app_id_to_user_id a
WHERE a.is_linked_or_is_a_primary_user = TRUE
  AND NOT EXISTS (
    SELECT 1 FROM primary_user_tenants pt
    WHERE pt.app_id = a.app_id
      AND pt.primary_user_id = a.primary_or_recipe_user_id
  );
```

--------------------------------

### SQL DDL for new reservation tables and schema changes

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Full DDL for the migration: creates recipe_user_account_infos, recipe_user_tenants, and primary_user_tenants tables with indexes, adds new columns to app_id_to_user_id, and updates a foreign key to ON UPDATE CASCADE. The pagination indexes are built CONCURRENTLY after COMMIT to avoid locking on live databases.

```sql
-- New reservation tables

CREATE TABLE IF NOT EXISTS recipe_user_account_infos (
    app_id              VARCHAR(64)  NOT NULL,
    recipe_user_id      CHAR(36)     NOT NULL,
    recipe_id           VARCHAR(128) NOT NULL,
    account_info_type   VARCHAR(8)   NOT NULL,
    account_info_value  TEXT         NOT NULL,
    third_party_id      VARCHAR(28),
    third_party_user_id VARCHAR(256),
    primary_user_id     CHAR(36)     NULL,
    CONSTRAINT recipe_user_account_infos_pkey
        PRIMARY KEY (app_id, recipe_id, recipe_user_id, account_info_type, third_party_id, third_party_user_id),
    CONSTRAINT recipe_user_account_infos_tenant_id_fkey
        FOREIGN KEY (app_id)
        REFERENCES apps (app_id) ON DELETE CASCADE
);

CREATE INDEX IF NOT EXISTS idx_recipe_user_account_infos_app_recipe_user
    ON recipe_user_account_infos (app_id, recipe_user_id);

CREATE TABLE IF NOT EXISTS recipe_user_tenants (
    app_id              VARCHAR(64)  NOT NULL,
    recipe_user_id      CHAR(36)     NOT NULL,
    tenant_id           VARCHAR(64)  NOT NULL,
    recipe_id           VARCHAR(128) NOT NULL,
    account_info_type   VARCHAR(8)   NOT NULL,
    account_info_value  TEXT         NOT NULL,
    third_party_id      VARCHAR(28),
    third_party_user_id VARCHAR(256),
    CONSTRAINT recipe_user_tenants_pkey
        PRIMARY KEY (app_id, tenant_id, recipe_id, account_info_type, third_party_id, third_party_user_id, account_info_value),
    CONSTRAINT recipe_user_tenants_tenant_id_fkey
        FOREIGN KEY (app_id, tenant_id)
        REFERENCES tenants (app_id, tenant_id) ON DELETE CASCADE
);

CREATE INDEX IF NOT EXISTS idx_recipe_user_tenants_tenant
    ON recipe_user_tenants (app_id, tenant_id);
CREATE INDEX IF NOT EXISTS idx_recipe_user_tenants_recipe_user_id
    ON recipe_user_tenants (app_id, recipe_user_id);
CREATE INDEX IF NOT EXISTS idx_recipe_user_tenants_account_info
    ON recipe_user_tenants (app_id, tenant_id, account_info_type, account_info_value);

CREATE TABLE IF NOT EXISTS primary_user_tenants (
    app_id             VARCHAR(64) NOT NULL,
    tenant_id          VARCHAR(64) NOT NULL,
    account_info_type  VARCHAR(8)  NOT NULL,
    account_info_value TEXT        NOT NULL,
    primary_user_id    CHAR(36)    NOT NULL,
    CONSTRAINT primary_user_tenants_pkey
        PRIMARY KEY (app_id, tenant_id, account_info_type, account_info_value),
    CONSTRAINT primary_user_tenants_app_id_fkey
        FOREIGN KEY (app_id, tenant_id)
        REFERENCES tenants (app_id, tenant_id) ON DELETE CASCADE
);

CREATE INDEX IF NOT EXISTS idx_primary_user_tenants_primary
    ON primary_user_tenants (primary_user_id);

-- New columns on app_id_to_user_id

ALTER TABLE app_id_to_user_id
    ADD COLUMN IF NOT EXISTS time_joined BIGINT NOT NULL DEFAULT 0,
    ADD COLUMN IF NOT EXISTS primary_or_recipe_user_time_joined BIGINT NOT NULL DEFAULT 0;

-- Add ON UPDATE CASCADE to every FK referencing app_id_to_user_id(app_id, user_id)

ALTER TABLE app_id_to_user_id
    DROP CONSTRAINT app_id_to_user_id_primary_or_recipe_user_id_fkey;
ALTER TABLE app_id_to_user_id
    ADD CONSTRAINT app_id_to_user_id_primary_or_recipe_user_id_fkey
    FOREIGN KEY (app_id, primary_or_recipe_user_id)
    REFERENCES app_id_to_user_id (app_id, user_id) ON DELETE CASCADE ON UPDATE CASCADE;
```

--------------------------------

### modules.txt with fork username

Source: https://github.com/supertokens/supertokens-core/blob/master/CONTRIBUTING.md

Shows the format of the modules.txt file after adding your GitHub username (e.g., helloworld) to the core line. This file is used to specify the branch and fork for each module.

```text
// put module name like module name,branch name,github username(if contributing with a forked repository) and then call ./loadModules script        
core,master,helloworld  
plugin-interface,master        
sqlite-plugin,master

```

--------------------------------

### Creating a session logic

Source: https://github.com/supertokens/supertokens-core/wiki/Session-pseudo-code

Pseudo-code for creating a session: generates session handle, tokens (refresh, access, front, idRefresh), stores double-hashed refresh token in DB, and sets cookies and headers.

```plaintext
Input from user:
userId: string
jwtPayload: JSON object, array or any primitive type. Is serialised everywhere.
sessionData: JSON object, array or any primitive type. Is serialised everywhere.
res: response object

Logic:
CODE: sessionHandle = a random string that will stay constant during this session
CODE: jwtKey = fetched from memory / db
CODE: refreshTokenKey = fetched from memory / db
CODE: refreshNonce = a random string
CODE: antiCsrfToken = a random string
CODE: timeNow = time in milli now.

// the refreshNonce is unique per refresh tokens. It's what makes one refresh token belonging to a session different to another one.
CODE: refreshToken = encrypt({sessionHandle, userId, refreshNonce, antiCsrfToken}, refreshTokenKey) + "." + refreshNonce

// the access token contains a pointer to the refresh token via rt below.
// It may not make sense now as to why this link is needed but will become clear later.
// The antiCsrfToken is stored in the access token so that we can do CSRF check without a db lookup.
CODE: accessToken = createJWTWithPayload({sessionHandle, userId, rt: hash(refreshToken), expiryTime, userPayload: jwtPayload, antiCsrfToken}, jwtKey)

// this token is accessible to the frontend and is used to read session info there.
CODE: frontToken = base64({uid: userId, ate: expiryTime, up: jwtPayload})

// This token acts as a proxy to the refresh token for the frontend. Whenever the refresh token changes, this token changes.
// The frontend needs to know when the refresh token changes to prevent race conditions while calling the refresh API.
// Since it cannot read the refresh token directly (since it's httpOnly cookie), it uses this token to keep track of changes.
CODE: idRefreshToken = a random string

// We store double hashed version of refresh token in the db since the plain text goes as cookie, 
// the hashed is stored in the access token, so we store the hash of that. This way, if the db is compromised,
// then there is literally nothing that can be with this double hashed refresh token.
CODE: insert into db: sessionHandle => {userId, rtHash2: hash(hash(refreshToken)), sessionData, refreshTokenExpiryTime, timeNow, jwtPayload}


CODE: set refreshToken (HttpOnly, secure), idRefreshToken (HttpOnly, secure) and accessToken (HttpOnly, secure) in cookies using res
CODE: set antiCsrfToken in the res header with the key anti-csrf
CODE: set idRefreshToken in res header with the key id-refresh-token
CODE: set frontToken in res header with key front-token
```

--------------------------------

### Copy config.yaml for docker build

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

Copies the config.yaml from the supertokens-root temp folder into the supertokens-root folder.

```bash
cp supertokens-root/temp/config.yaml supertokens-root/
```

--------------------------------

### Allowed MigrationMode transitions

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Shows the allowed transitions between MigrationMode values. MIGRATED is terminal; DUAL_WRITE_READ_NEW to MIGRATED requires getBackfillPendingUsersCount == 0.

```text
LEGACY              ↔  DUAL_WRITE_READ_OLD
DUAL_WRITE_READ_OLD ↔  DUAL_WRITE_READ_NEW
DUAL_WRITE_READ_NEW →  MIGRATED    (only when getBackfillPendingUsersCount == 0)
MIGRATED            (terminal; no outgoing transitions)
```

--------------------------------

### Flip to DUAL_WRITE_READ_NEW via CRUD API

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

PUT request to set migration_mode to DUAL_WRITE_READ_NEW. This is the first risk-bearing step; reads switch to new tables. The validator does not block on backfill completion here, so manual verification is required.

```http
PUT /recipe/multitenancy/connectionuridomain/v2
{
  "connectionUriDomain": "<cud>",
  "coreConfig": { "migration_mode": "DUAL_WRITE_READ_NEW" }
}
```

--------------------------------

### Copy config.yaml

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

Copies the temporary config file to the current directory.

```bash
cp temp/config.yaml .
```

--------------------------------

### Run offline backfill script

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Execute the migration-backfill.sql script from the supertokens-postgresql-plugin repository. Pass -v app_id="''" for all apps or -v app_id="'my-app'" to scope to a single app. The script runs four INSERTs and one UPDATE in a single transaction.

```bash
psql "<connection-uri>" -v app_id="''" -f migration-scripts/migration-backfill.sql
```

--------------------------------

### Generate parity dumps with psql and diff

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Use these commands to generate canonical dumps of old and new tables and compare them. A clean diff indicates the two views agree.

```bash
psql -v app_id="'<app>'" -f migration-scripts/dump_old_canonical.sql > old.csv
psql -v app_id="'<app>'" -f migration-scripts/dump_new_canonical.sql > new.csv
diff old.csv new.csv
```

--------------------------------

### Dockerfile replacement lines

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

These lines replace the removed lines to copy the local supertokens-root and run the CLI.

```dockerfile
RUN mkdir ./supertokens
COPY ./supertokens-root/ ./supertokens
RUN cd supertokens && ./jre/bin/java -classpath "./cli/*" io.supertokens.cli.Main true
```

--------------------------------

### PUT /recipe/multitenancy/connectionuridomain/v2 - Set migration_mode to DUAL_WRITE_READ_OLD

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Use this API call to switch a connection URI domain (CUD) from LEGACY to DUAL_WRITE_READ_OLD. The validator permits this transition without a backfill probe. After this, multitenancy refresh fans out the config to all nodes sharing the CUD, and subsequent operations dual-write to both old and new tables.

```http
PUT /recipe/multitenancy/connectionuridomain/v2
{
  "connectionUriDomain": "<cud>",
  "coreConfig": { "migration_mode": "DUAL_WRITE_READ_OLD" }
}
```

--------------------------------

### Copy supertokens-root into docker repo

Source: https://github.com/supertokens/supertokens-core/wiki/Building-from-source

Copies the supertokens-root folder into the cloned docker repository.

```bash
cp -rf ./supertokens-root ./supertokens-docker-mysql
```

--------------------------------

### SQL: New columns for app_id_to_user_id

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Adds two new columns to the app_id_to_user_id table: time_joined and primary_or_recipe_user_time_joined, both BIGINT NOT NULL DEFAULT 0.

```sql
time_joined                       BIGINT NOT NULL DEFAULT 0,
primary_or_recipe_user_time_joined BIGINT NOT NULL DEFAULT 0,
```

--------------------------------

### Set SUPERTOKENS_MIGRATION_MODE environment variable

Source: https://github.com/supertokens/supertokens-core/blob/master/docs/CUTOVER-PROCEDURE.md

Alternative to the config file: set the environment variable to enable dual-write mode. This is useful for containerized or environment-based deployments.

```bash
SUPERTOKENS_MIGRATION_MODE=DUAL_WRITE_READ_OLD
```

--------------------------------

### Option A: Directly edit tenant_configs to set MIGRATED

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Update the tenant_configs row directly to set migration_mode to MIGRATED. Adjust the JSON-cast syntax to match your column type (text vs jsonb). Repeat for each tenant that needs a non-default mode.

```sql
-- For each app's public tenant. Example for the base tenant on the root CUD:
UPDATE tenant_configs
SET core_config = jsonb_set(
    core_config::jsonb,
    '{migration_mode}',
    '"MIGRATED"'::jsonb
)::text
WHERE connection_uri_domain = '' AND app_id = 'public' AND tenant_id = 'public';
```

--------------------------------

### Canonical dump comparison

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Generate old and new canonical dumps and compare them with diff. A non-empty diff indicates a discrepancy that must be investigated before proceeding.

```bash
psql "<connection-uri>" -f migration-scripts/dump_old_canonical.sql > old.csv
psql "<connection-uri>" -f migration-scripts/dump_new_canonical.sql > new.csv
diff old.csv new.csv
```

--------------------------------

### Check pending backfill count

Source: https://github.com/supertokens/supertokens-core/blob/master/docs/CUTOVER-PROCEDURE.md

SQL query to check how many users still need backfilling. A result of 0 indicates backfill is complete.

```sql
-- Users still needing backfill (time_joined = 0 means pre-migration)
SELECT COUNT(*) FROM app_id_to_user_id
WHERE app_id = 'public' AND time_joined = 0;
-- Target: 0
```

--------------------------------

### Set migration_mode to DUAL_WRITE_READ_OLD

Source: https://github.com/supertokens/supertokens-core/blob/master/docs/CUTOVER-PROCEDURE.md

Set this configuration on all SuperTokens instances to enable dual-write mode. Reads remain unchanged, and writes are duplicated to both old and new tables.

```yaml
migration_mode: DUAL_WRITE_READ_OLD
```

--------------------------------

### MigrationMode enum values

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

Lists the four MigrationMode values and their read/write behavior: LEGACY, DUAL_WRITE_READ_OLD, DUAL_WRITE_READ_NEW, MIGRATED. Default when absent is LEGACY.

```text
LEGACY              writeold + readold
DUAL_WRITE_READ_OLD writeold + writenew + readold
DUAL_WRITE_READ_NEW writeold + writenew + readnew
MIGRATED            writenew + readnew
```

--------------------------------

### Validate data consistency after backfill

Source: https://github.com/supertokens/supertokens-core/blob/master/docs/CUTOVER-PROCEDURE.md

Four SQL validation queries to verify backfill correctness: check for missing time_joined, missing account info entries, tenant coverage match, and missing primary reservations. Expected results are 0, 0, new_count >= old_count, and empty respectively.

```sql
-- 1. No users missing time_joined
SELECT COUNT(*) FROM app_id_to_user_id
WHERE time_joined = 0 AND app_id = 'public';
-- Expected: 0

-- 2. All users have account info entries
SELECT COUNT(*) FROM app_id_to_user_id a
WHERE a.app_id = 'public' AND NOT EXISTS (
    SELECT 1 FROM recipe_user_account_infos rai
    WHERE rai.app_id = a.app_id AND rai.recipe_user_id = a.user_id
);
-- Expected: 0

-- 3. Tenant coverage matches
SELECT
    (SELECT COUNT(*) FROM all_auth_recipe_users WHERE app_id = 'public') AS old_count,
    (SELECT COUNT(*) FROM recipe_user_tenants WHERE app_id = 'public') AS new_count;
-- new_count should be >= old_count (may be higher for users with multiple account infos)

-- 4. All linked users have primary reservations
SELECT DISTINCT a.primary_or_recipe_user_id
FROM app_id_to_user_id a
WHERE a.is_linked_or_is_a_primary_user = TRUE AND a.app_id = 'public'
AND NOT EXISTS (
    SELECT 1 FROM primary_user_tenants pt
    WHERE pt.app_id = a.app_id AND pt.primary_user_id = a.primary_or_recipe_user_id
);
-- Expected: empty
```

--------------------------------

### Notation definitions

Source: https://github.com/supertokens/supertokens-core/wiki/Session-pseudo-code

Defines the notation used in the pseudo-code: encrypt, createJWTWithPayload, hash, and base64 functions.

```plaintext
encrypt(x, y) = encrypt 'x' using the key 'y'
createJWTWithPayload(x, y) = create a JWT containing 'x' as the payload, signed with 'y'
hash(x) = hash of 'x'
base64(x) = base64 representation of 'x'
```

--------------------------------

### Flip to MIGRATED via CRUD API

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

PUT request to set migration_mode to MIGRATED. The validator runs requireBackfillComplete and refuses if any user has time_joined = 0. This step is one-way through the standard CRUD path; the validator blocks the reverse.

```http
PUT /recipe/multitenancy/connectionuridomain/v2
{
  "connectionUriDomain": "<cud>",
  "coreConfig": { "migration_mode": "MIGRATED" }
}
```

--------------------------------

### SQL table refresh_tokens

Source: https://github.com/supertokens/supertokens-core/wiki/Session-pseudo-code

SQL schema for the refresh_tokens table, storing session handle, user ID, hashed refresh token, session data, expiry times, and JWT user payload.

```sql
CREATE TABLE refresh_tokens (
    session_handle VARCHAR(255) NOT NULL,
    user_id VARCHAR(128) NOT NULL,
    refresh_token_hash_2 VARCHAR(128) NOT NULL,
    session_data TEXT,
    expires_at BIGINT UNSIGNED NOT NULL,
    created_at_time BIGINT UNSIGNED NOT NULL,
    jwt_user_payload TEXT,
    PRIMARY KEY(session_handle)
);
```

--------------------------------

### Drop deprecated tables in future release

Source: https://github.com/supertokens/supertokens-core/blob/master/SCHEMA-REWORK.md

SQL statements to drop deprecated tables after all CUDs have been on MIGRATED for at least one release cycle. Must be shipped in a separate release, not bundled with the cutover release.

```sql
DROP TABLE IF EXISTS emailpassword_user_to_tenant;
DROP TABLE IF EXISTS passwordless_user_to_tenant;
DROP TABLE IF EXISTS thirdparty_user_to_tenant;
DROP TABLE IF EXISTS webauthn_user_to_tenant;
DROP TABLE IF EXISTS all_auth_recipe_users;
```
Tokens:
Raw