---
sidebar_position: 1
title: From < 0.14.0
description: Upgrading to 0.14.0
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';
import RequiredUpgrade from "@site/src/components/snippets/_upgrade-required.mdx"

{/* <RequiredUpgrade before='< 0.14.0' current='0.14.0' old='0.13.2' /> */}

## Source/Client IDs

MS `0.14.0` introduces a database for persisting Plays/Scrobbles, queues, and other data **associated with a Source/Client**.

To make this association atomic a Source/Client **ID** is now configurable. This ID is what MS will use to identify the Source/Client in your **config** with the Source/Client in the **database**.

This ID needs to be unique to the client or source type it is used on IE:

* two [Koito Clients](/configuration/clients/koito/) cannot both have the ID `myKoitoID`
* it is recommended that the ID be *globally* unique among all sources/clients, but it's not required

### Configuring IDs

<Tabs groupId="configType" queryString>

<TabItem value="env" label="ENV">

For each Source/Client in your environmental variables, add a key with the suffix `_ID` and the ID value. EX

```yaml title="compose.yaml"
services:
  multi-scrobbler:
  # ...
  environment:
    - KOTIO_TOKEN=...
    # ...more koito config
  // highlight-start
    - KOITO_ID=myKoitoID
  // highlight-end

    - JELLYFIN_URL=...
    # ...more jellyin config
  // highlight-start
    - JELLYFIN_ID=myJellyfinID
  // highlight-end    
```

</TabItem>
<TabItem value="file" label="File">

Add an `id` to the top-level for each Source/Client configuration, next to `data`:

```json title="koito.json"
[
  {
    "name": "koito-source",
    "configureAs": "source",
    // highlight-start
    "id": "myKoitoID",
    // highlight-end   
    "data": {
      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
      "username": "admin",
      "url": "http://192.168.0.100:4110" 
    }
  }
]
```

</TabItem>
<TabItem value="aio" label="AIO">

Add an `id` to the top-level for each Source/Client configuration, next to `data`:

```json title="config.json"
{
  "sources": [
    {
      "name": "koito-source",
      "configureAs": "source",
      "type": "koito",
      // highlight-start
      "id": "myKoitoID",
      // highlight-end    
      "data": {
        "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
        "username": "admin",
        "url": "http://192.168.0.100:4110" 
      }
    }
  ]
}
```

</TabItem>
</Tabs>

:::important[Default ID]

**If you do not add an ID then Multi-Scrobbler will automatically use the name of the Source/Client as the ID.** The name is shown in the Dashboard.

If you decide to add an ID later, you must use the Source/Client name as the ID in order to keep Plays/Scobbles associated with the same config.

:::

## Cached Scrobble Migration

:::tip

Before upgrading, if your MS dashboard shows 0 queued/failed for all [Scrobble Clients](/configuration/clients) then you can **ignore this section.**

:::

:::important

The cached scrobbles for a Client/Source were based on its **name**. If you plan on changing the name of a Client/Source with this upgrade you should do it **after** this migration has run or else MS will not be able to find any associated cached scrobbles. 

:::

MS `0.14.0` introduces a database for persisting Plays/Scrobbles, queues, and other data. Prior to `0.14.0`, queued/failed scrobbles were stored in a cache **file** inside your [`CONFIG_DIR`](/installation/?dockerSetting=storage#recommended-settings) named `ms-scrobble.cache`.

When a [Client](/configuration/clients) is created and **enabled** in `0.14.0` it will attempt to **automatically migrate scrobbles** from this cache into the database.

* You can see progress/results for this process by filtering logs for `[Cached Scrobble Migration]`
* If the process fails MS will attempt to migrate failed scrobbles, again, the next time it is started
* Your cached scrobbles **are not deleted** in either the success or failure outcome
  * If the process succeeds then MS knows to ignore the cache on subsequent startups

:::note

This process only occurs for Clients that are **enabled.**

* If you are using ENV for config then your Clients are automatically enabled
* If you are using File/AIO make sure that the `enable` property is either `true` or not present in your Client configs

Even if your Client does not start successfully (EX due to authentication) you should still enable and start **all** Clients in order to get all scrobbled migrated.

:::

## Cache Configuration

In `0.14.0` [Cache](/configuration#caching) has been simplified with much of the required configuration being removed.

:::tip

This only applies to users who have `cache` in their [AIO Config](/configuration/?configType=aio#configuration-types) `config.json` or are using `CACHE_*` [ENV Config](/configuration/?configType=env#configuration-types)

If you do not have any of the above [Cache](/configuration#caching) configuration defined then you can **ignore this section.** 

:::

#### Scrobble Caching Removed

[Scrobble caching has removed and replaced by the new database.](#cached-scrobble-migration)

* Remove any ENV Config starting with `CACHE_SCROBBLE`
* Remove `cache.scrobble` from the AIO Config

#### Metadata Config Simplified

Metadata caching remains the same but the config has been simplified. If you were using [Valkey for caching](/configuration/#secondary-caching) update your config:

<Tabs groupId="configType" queryString>

<TabItem value="env" label="ENV">

* Remove `CACHE_METADATA`
* Rename `CACHE_METADATA_CONN` to [`CACHE_VALKEY`](/configuration/#secondary-caching)

</TabItem>
<TabItem value="aio" label="AIO">

Remove `cache.metadata` and add a new string key `valkey` to the `cache` object, containing your valkey connection string:

```diff
  "cache": {
+    "valkey": "redis://valkey:6379"
-    "metadata": {
-      "provider": "valkey",
-      "connection": "redis://valkey:6379"
-    }
  }
```

</TabItem>
</Tabs>


#### Auth Config Simplified

Auth caching remains the same but the config has been simplified. The connection option for Auth is no longer configurable. You may specify provider as either `file` (default, uses `CONFIG_DIR`) or `valkey`. If you want to use Valkey for auth it will use the same config as Metadata.

<Tabs groupId="configType" queryString>

<TabItem value="env" label="ENV">

* Remove `CACHE_AUTH_CONN`
* Add [`CACHE_VALKEY`](/configuration/#secondary-caching) (if using valkey)

</TabItem>
<TabItem value="aio" label="AIO">

Remove the `connection` property from the `auth` object. If using `file` the entire `auth` object can be removed.

```diff
  "cache": {
+   "valkey": "redis://valkey:6379",
    "auth": {
      "provider": "valkey",
-     "connection": "redis://valkey:6379"
    }
  }
```

</TabItem>
</Tabs>

## Renamed ENV Keys

In an effort to standard ENV prefixes some ENV keys have been renamed:

* `LZENDPOINT_ENABLE` => `LZE_ENABLE`
* `LFMENDPOINT_ENABLE` => `LFM_ENABLE`

## (Optional) ENV Client/Source Names

In the MS Dashboard, prior to 0.14.0, UI Client/Sources configured with [ENV Config](/configuration/?configType=env#configuration-types) always had generated names like `unnamed-koito`.

ENV Config Clients/Sources can now be configured with a name by using the `_NAME` suffix, example:

```yaml title="compose.yaml"
services:
  multi-scrobbler:
  # ...
  environment:
    - KOTIO_TOKEN=...
    # ...
    - KOITO_ID=myKoitoID
  // highlight-start
    - KOITO_NAME=Koito A
  // highlight-end

    - JELLYFIN_URL=...
    # ..
    - JELLYFIN_ID=myJellyfinID
  // highlight-start
    - JELLYFIN_NAME=Foxx Jelly
  // highlight-end    
```

:::important

If you have **cached scrobbles** make sure to upgrade and run [Cached Scrobble Migration](#cached-scrobble-migration) **before** adding names to Client/Sources.

:::
