Upgrading from Pre-v0.11

Flashcore in v0.11 evolved from a simple key-value store into a full database with models, schemas, and relations. This guide covers what changed and how to upgrade.

What Changed

KV API Is Unchanged

All existing Flashcore.get, Flashcore.set, Flashcore.delete, Flashcore.on, Flashcore.off, and namespace calls work without modification:

// This still works exactly the same
import { Flashcore } from 'robo.js'

await Flashcore.set('key', 'value')
const value = await Flashcore.get<string>('key')
await Flashcore.delete('key')

// This still works exactly the same
import { Flashcore } from 'robo.js'

await Flashcore.set('key', 'value')
const value = await Flashcore.get('key')
await Flashcore.delete('key')

No code changes needed for the KV API.

Automatic Data Migration

v0.11 includes a RuntimeMigrationAdapter that transparently migrates data from the legacy .robo/data/ directory to the new .robo/flashcore/ format.

How It Works

1. On first startup, if .robo/data/ exists and .robo/flashcore/ is empty, Flashcore creates a backup at .robo/flashcore-backups/legacy-{timestamp}/.
2. The adapter enters lazy-read-through mode: when a key is read that does not exist in .robo/flashcore/, it checks .robo/data/ and copies it forward.
3. New writes always go to .robo/flashcore/.
4. Over time, all actively used keys are migrated automatically.

Migration Modes

The adapter operates in two modes:

Deletes During Migration

If you delete a key during migration, a tombstone is written to prevent re-reading the value from legacy storage.

Keyv Adapter Config

The old flashcore.keyv configuration still works. It is automatically wrapped in a KeyvAdapter:

// This still works — no changes needed
import KeyvSqlite from '@keyv/sqlite'

export default {
	flashcore: {
		keyv: {
			store: new KeyvSqlite('sqlite://robo.db')
		}
	}
}

// This still works — no changes needed
import KeyvSqlite from '@keyv/sqlite'

export default {
	flashcore: {
		keyv: {
			store: new KeyvSqlite('sqlite://robo.db')
		}
	}
}

Import Paths

Adding Models

You can start using models alongside KV at any time. Models and KV storage are independent:

import { createModel, f } from 'robo.js/flashcore'

export const GuildSettings = createModel('GuildSettings', {
	id: f.id(),
	guildId: f.string().unique(),
	prefix: f.string().default('!'),
	locale: f.string().default('en'),
	createdAt: f.date().default(() => new Date())
})

import { createModel, f } from 'robo.js/flashcore'

export const GuildSettings = createModel('GuildSettings', {
	id: f.id(),
	guildId: f.string().unique(),
	prefix: f.string().default('!'),
	locale: f.string().default('en'),
	createdAt: f.date().default(() => new Date())
})

Models store data separately from KV keys. There is no collision risk.

Checking Migration Status

If you install @robojs/flashcore-extras, you can use the /db legacy-migrate terminal command to check the current state of the lazy migration:

/db legacy-migrate

This shows the migration mode, backup location, and the last time a key was lazily migrated. It does not perform a bulk migration — see the note below for why.

See CLI Commands for more database management commands.

Step-by-Step Checklist

1. Update Robo.js to v0.11+. No code changes are needed for existing KV usage.
2. Verify data — Start your Robo and confirm existing Flashcore.get() calls return the expected values. The lazy migration handles this automatically.
3. Check .robo/flashcore-backups/ — A backup of your legacy data was created on first startup.
4. Add models (optional) — Define models with createModel and f for any structured data you want to migrate from flat KV.
5. Install @robojs/flashcore-extras (optional) — For migrations, transactions, integrity tools, and /db terminal commands.
6. Run /db legacy-migrate (optional) — Check the current migration status and verify the lazy migration is progressing.
7. Clean up — Once you are confident all actively used keys have been read at least once since upgrading, you can optionally remove the .robo/data/ directory.