> For the complete documentation index, see [llms.txt](https://stellarskills.gitbook.io/stellarskills-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stellarskills.gitbook.io/stellarskills-docs/storage-and-migration.md).

# storage and migration

The default database is `config/stellarskills/data/stellarskills.db`. It stores balances, purchases, choices, class/hero state, XP/level history, quest acceptance/progress, Journey progress, transaction claims, and audit history.

## SQLite

```yaml
type: sqlite
file: data/stellarskills.db
pool-size: 6
```

The path is resolved inside the StellarSkills configuration root and cannot escape it. SQLite deliberately uses one pooled connection regardless of the reference pool-size value, with foreign keys and a busy timeout enabled.

{% hint style="warning" %}
For a portable backup, stop the server before copying the database and its directory. Do not assume copying only the `.db` while writes are running produces a consistent backup. Keep world/player data too: command-provider permission ownership also lives in persistent player data.
{% endhint %}

## SQL server connections

The non-SQLite branch accepts allowed MySQL/MariaDB/PostgreSQL JDBC URL prefixes, `jdbc-url`, `username`, `password`, and `pool-size` (2–20). MySQL and PostgreSQL drivers are bundled. A MariaDB URL requires a suitable driver; accepting its prefix is not proof that one is bundled.

Example for a dedicated PostgreSQL database:

```yaml
type: postgresql
jdbc-url: jdbc:postgresql://db.example.invalid:5432/stellarskills
username: stellarskills_app
password: REPLACE_WITH_A_PRIVATE_PASSWORD
pool-size: 6
```

{% hint style="warning" %}
Do not publish real credentials in GitBook. Use a limited application account, controlled network access and the TLS options appropriate to your environment. This is a syntax example, not a security-complete hosted-database configuration.
{% endhint %}

`storage.yml` is read during repository initialization. Restart after changing it. Changing `type`/URL points at another database; it does **not** copy SQLite data into SQL automatically. SQL backends are not a guarantee of cross-server distributed caches or every backend-specific statement behaving identically. Test your selected backend before production.

## Editor revisions

`/skills admin backup list` lists supported filenames in `backups/`. Restore only one of those exact revisions using `/skills admin backup restore <revision>`. The restorer confines paths, creates a safety copy, validates and activates supported content files.

{% hint style="warning" %}
Progression rollback may involve both leveling and objectives, and class/theme files can require your own copies. Do not treat a single revision restore as a full simultaneous rollback of every configuration/database/world change. Avoid restoring schema/effect/integration reference files as if they were live trees.
{% endhint %}

## Quest migration in 5.15.0

* Existing objective IDs and progress are retained.
* Explicit `reward.xp` or `reward.experience` wins.
* Old `reward.amount` without XP becomes **amount × 100 XP**.
* Missing legacy amount defaults through the parser; write explicit XP to avoid unintended rewards.
* Old objective currency is no longer the direct quest payout.
* Completed one-time quests do not pay again merely because the reward type changed.
* Existing balances are not removed.
* Publishing a progression draft writes explicit XP rewards.

{% hint style="warning" %}
Review every migrated quest, especially large repeatable objectives. A conversion rule is not a balancing equivalence between old skill points and new XP.
{% endhint %}

## Level and build history

The highest-ever level prevents repeated level-point grants after lowering XP or curve edits. If your intention is a true seasonal fresh economy, configure/reset the relevant systems explicitly rather than assuming curve changes erase history.

Current build exports include selectable-effect choices. Older `SSB1` builds without choice metadata remain usable for ordinary nodes; a build referring to a newly choice-enabled node without valid picks is rejected before applying that plan. Keep option IDs stable.

Class starting grants remain one-time after ordinary class resets. Normal Hero fates remain one-roll after reconnect/respec. Hero revoke is an explicit exception for administrative testing.

## Upgrade checklist

{% stepper %}
{% step %}

### Stop and back up

Stop and back up config, database, player/world data.
{% endstep %}

{% step %}

### Record versions

Record server and engine versions and verify protocol 20.
{% endstep %}

{% step %}

### Replace intended jars

Replace the intended jars only; keep unrelated modules intact.
{% endstep %}

{% step %}

### Review migrated content

Review new/migrated quests, level caps and secondary point sources.
{% endstep %}

{% step %}

### Validate startup

Run validation and examine startup/database migration errors.
{% endstep %}

{% step %}

### Test core functionality

Test class access, a quest completion, a paid rank upgrade, an effect choice/refund, and privacy.
{% endstep %}

{% step %}

### Retain the backup

Keep the backup until an ordinary player confirms the live experience.
{% endstep %}
{% endstepper %}

No generic automatic player-ID/content-ID migration command is documented because one is not exposed in the current command tree.