Migrating to SQLiteMigration vers SQLite

What you do: nothingCe que vous faites : rien

Update the server as usual — Portainer’s Pull and redeploy, your NAS’s update button, or from the stack’s folder:Mettez le serveur à jour comme d’habitude — Pull and redeploy dans Portainer, le bouton de mise à jour de votre NAS, ou depuis le dossier de la pile :

docker compose pull
docker compose up -d

That’s all.C’est tout.

What happensCe qui se passe

1. On its first start, Tentacle finds your MariaDB (or MySQL) and no tentacle.db: it copies everything into data/tentacle.db. MariaDB is only read, never modified — not even if the copy fails.À son premier démarrage, Tentacle trouve votre MariaDB (ou MySQL) et pas de tentacle.db : il recopie tout dans data/tentacle.db. MariaDB n’est que lue, jamais modifiée — pas même si la copie échoue.
2. Meanwhile, the web app, the desktop and mobile apps and the TVs show a waiting screen: “Database migration in progress”, with the progress. It usually takes a few seconds: about 3 on a real database, 8 to 9 on a simulated slow NAS. Apps that are not up to date yet simply see the server restarting.Pendant ce temps, l’application web, les applications de bureau et mobiles et les téléviseurs affichent un écran d’attente : « Migration de la base de données en cours », avec l’avancement. Cela prend d’ordinaire quelques secondes : 3 environ sur une vraie base, 8 à 9 sur un NAS lent simulé. Les applications pas encore à jour voient seulement le serveur redémarrer.
3. Before switching, everything is checked: rows of each table, a checksum per column, and a sample read back the way the server will read it. Only then is the new database put in place.Avant la bascule, tout est vérifié : les lignes de chaque table, une somme de contrôle par colonne, et un échantillon relu comme le serveur le lira. La nouvelle base n’est mise en place qu’ensuite.
4. Tentacle starts on SQLite. Its TMDB title cache follows in the background, copied from MariaDB (no call to TMDB); the Services › Database card shows its progress. Recommendations wait for it.Tentacle démarre sur SQLite. Son cache des fiches TMDB suit en fond, copié depuis MariaDB (aucun appel à TMDB) ; la carte Services › Base de données en montre l’avancement. Les recommandations l’attendent.
5. The administration’s overview then says “MariaDB is no longer needed”, with the steps for your installation (below).La vue d’ensemble de l’administration dit alors « MariaDB n’est plus nécessaire », avec la marche à suivre pour votre installation (plus bas).

What the dashboard saysCe que dit le tableau de bord

Administration › Services › Database shows the engine (SQLite), the file, its size, and “Migrated from MariaDB on …” with the number of tables and rows.Administration › Services › Base de données montre le moteur (SQLite), le fichier, sa taille, et « Migrée depuis MariaDB le … » avec le nombre de tables et de lignes.

In the container’s console, tentacle db migrate prints the migration report, and this reads the database (read-only):Dans la console du conteneur, tentacle db migrate affiche le rapport de migration, et ceci lit la base (en lecture seule) :

tentacle db query "SELECT COUNT(*) AS n FROM paired_devices"

Removing MariaDBRetirer MariaDB

Official stack from before 1.25Pile officielle d’avant la 1.25

tentacle-full or tentacle-db, with their db service. Since 1.25, tentacle-full (with Jellyfin) and tentacle-only (Tentacle alone) contain no MariaDB, and tentacle-db is gone. Two ways:tentacle-full ou tentacle-db, avec leur service db. Depuis la 1.25, tentacle-full (avec Jellyfin) et tentacle-only (Tentacle seul) ne contiennent plus MariaDB, et tentacle-db n’existe plus. Deux voies :

The simplest: move to the new stackLe plus simple : passer à la nouvelle pile

In your stack’s folder, replace compose.yaml with the new stack, without MariaDB — tentacle-full (it replaces tentacle-full) or tentacle-only (it replaces tentacle-db):Dans le dossier de votre pile, remplacez compose.yaml par la nouvelle pile, sans MariaDB — tentacle-full (elle remplace tentacle-full) ou tentacle-only (elle remplace tentacle-db) :

curl -fsSLo compose.yaml https://raw.githubusercontent.com/Knaox/Tentacle-TV/main/stacks/tentacle-full/compose.yaml

curl -fsSLo compose.yaml https://raw.githubusercontent.com/Knaox/Tentacle-TV/main/stacks/tentacle-only/compose.yaml

• Had you changed it (hardware transcoding, ports, web interface turned off…)? Carry those lines over to the new file; your .env file stays valid.Vous l’aviez modifié (transcodage matériel, ports, interface web coupée…) ? Reportez ces lignes dans le nouveau fichier ; votre fichier .env reste valable.
• Apply with the command below — the db and init containers are stopped and removed; MariaDB’s data stays in its volume.Appliquez avec la commande ci-dessous — les conteneurs db et init sont arrêtés et retirés ; les données de MariaDB restent dans leur volume.

docker compose up -d --remove-orphans

Or remove the lines yourselfOu retirer les lignes vous-même

1. In your compose.yaml, delete the db and init services entirely.Dans votre compose.yaml, supprimez en entier les services db et init.
2. In the tentacle service: under depends_on, delete the db entry (and its condition line); delete the DB_HOST and DB_PASSWORD_FILE variables, and the tentacle-secrets volume line.Dans le service tentacle : sous depends_on, supprimez l’entrée db (et sa ligne condition) ; supprimez les variables DB_HOST et DB_PASSWORD_FILE, et la ligne du volume tentacle-secrets.
3. At the bottom of the file, under volumes:, delete tentacle-db and tentacle-secrets.En bas du fichier, sous volumes:, supprimez tentacle-db et tentacle-secrets.
4. Apply with the same command as above.Appliquez avec la même commande que plus haut.

ThenEnsuite

Later, only once you are sure, this deletes MariaDB’s data and passwords for good (docker volume ls gives the exact names; <project> is usually the folder’s name):Plus tard, seulement quand vous êtes sûr, ceci supprime pour de bon les données de MariaDB et ses mots de passe (docker volume ls donne les noms exacts ; <projet> est d’ordinaire le nom du dossier) :

docker volume rm <project>_tentacle-db <project>_tentacle-secrets

This error? A depends_on still names the database: remove it, then run the command again.Cette erreur ? Un depends_on nomme encore la base : retirez-le, puis relancez la commande.

service "tentacle" depends on undefined service "db"

Your stack follows the repository (Portainer’s Repository mode)? It may have received the new file before migrating: see MariaDB removed too early.Votre pile suit le dépôt (le mode Repository de Portainer) ? Elle a pu recevoir le nouveau fichier avant d’avoir migré : voir MariaDB retirée trop tôt.

Docker ComposeDocker Compose

1. In your compose.yaml, delete the database service (often db).Dans votre compose.yaml, supprimez le service de la base (souvent db).
2. In Tentacle’s service: remove its entry from depends_on, and the DB_* and DATABASE_URL variables.Dans le service de Tentacle : retirez son entrée de depends_on, et les variables DB_* et DATABASE_URL.
3. Apply with docker compose up -d and --remove-orphans (the command above) — the database container is stopped and removed; its data stays in its volume.Appliquez par docker compose up -d et --remove-orphans (la commande plus haut) — le conteneur de la base est arrêté et retiré ; ses données restent dans son volume.
4. Later, only once you are sure: delete that volume (docker volume ls, then docker volume rm <name>).Plus tard, seulement quand vous êtes sûr : supprimez ce volume (docker volume ls, puis docker volume rm <nom>).

An error “depends on undefined service”? A depends_on still names the database: remove it.Une erreur « depends on undefined service » ? Un depends_on nomme encore la base : retirez-le.

PortainerPortainer

1. Stacks → your stack → Editor: replace the whole content with the new stack (stacks/tentacle-full or stacks/tentacle-only from the repository), or delete the database service yourself (and init if there is one), its depends_on entry and Tentacle’s DB_* and DATABASE_URL variables.Stacks → votre pile → Editor : remplacez tout le contenu par la nouvelle pile (stacks/tentacle-full ou stacks/tentacle-only du dépôt), ou supprimez vous-même le service de la base (et init s’il existe), son entrée dans depends_on et les variables DB_* et DATABASE_URL de Tentacle.
2. Update the stack, with Prune services ticked: without it, the database container keeps running.Update the stack, en cochant Prune services : sans lui, le conteneur de la base continue de tourner.
3. Stack linked to the repository (Git): set the reference back to refs/heads/main, then Pull and redeploy. A stack that followed stacks/tentacle-db is recreated from stacks/tentacle-only, under the SAME name: its volumes are kept.Pile reliée au dépôt (Git) : remettez la référence sur refs/heads/main, puis Pull and redeploy. Une pile qui suivait stacks/tentacle-db se recrée depuis stacks/tentacle-only, sous le MÊME nom : ses volumes sont repris.
4. Later, only once you are sure: Volumes → the database volume → Remove.Plus tard, seulement quand vous êtes sûr : Volumes → le volume de la base → Remove.

SynologySynology

1. Container Manager → Project → your project → Edit: delete the database service, its depends_on entry and Tentacle’s DB_* variables.Container Manager → Projet → votre projet → Modifier : supprimez le service de la base, son entrée dans depends_on et les variables DB_* de Tentacle.
2. Save, then rebuild the project.Enregistrez, puis reconstruisez le projet.
3. Later, only once you are sure: delete the database folder.Plus tard, seulement quand vous êtes sûr : supprimez le dossier de la base.

UnraidUnraid

1. Docker → the MariaDB container → Stop, then Remove.Docker → le conteneur MariaDB → Stop, puis Remove.
2. In the Tentacle container’s template, remove the DB_* and DATABASE_URL variables, then Apply.Dans le modèle du conteneur Tentacle, retirez les variables DB_* et DATABASE_URL, puis Apply.
3. MariaDB’s files stay in appdata until you delete them.Les fichiers de MariaDB restent dans appdata jusqu’à ce que vous les effaciez.

CasaOSCasaOS

1. Apps → MariaDB → Uninstall.Applications → MariaDB → Désinstaller.
2. In Tentacle’s settings, remove the DB_* and DATABASE_URL variables, then save.Dans les réglages de Tentacle, retirez les variables DB_* et DATABASE_URL, puis enregistrez.

Database chosen in the old wizardBase choisie dans l’ancien assistant

tentacle-only before 1.25, and other installations without DB_* variables: the old database is named by a file of the data folder. The dashboard gives the command that deletes it; run it in the Tentacle container’s console (Portainer: Console; otherwise docker exec <container> followed by the command), then restart Tentacle.tentacle-only d’avant la 1.25, et les installations sans variables DB_* : l’ancienne base est désignée par un fichier du dossier de données. Le tableau de bord donne la commande qui le supprime ; lancez-la dans la console du conteneur Tentacle (Portainer : Console ; sinon docker exec <conteneur> suivi de la commande), puis redémarrez Tentacle.

External databaseBase externe

A MariaDB on another machine, a NAS: remove the DB_* and DATABASE_URL variables from Tentacle’s stack (or the old wizard’s file, above), then restart Tentacle. Then, whenever you wish, delete the Tentacle database from your MariaDB server with the DROP DATABASE command the dashboard gives — Tentacle never runs anything on the old database.Une MariaDB sur une autre machine, un NAS : retirez les variables DB_* et DATABASE_URL de la pile Tentacle (ou le fichier de l’ancien assistant, plus haut), puis redémarrez Tentacle. Ensuite, quand vous le souhaitez, supprimez la base Tentacle de votre serveur MariaDB avec la commande DROP DATABASE que donne le tableau de bord — Tentacle n’exécute jamais rien sur l’ancienne base.

Going backRevenir en arrière

The previous image (for example ghcr.io/knaox/tentacle-tv:v1.24.0) always starts again on your MariaDB, intact. With an official stack, pin it in .env — and keep the stack’s db service:L’image précédente (par exemple ghcr.io/knaox/tentacle-tv:v1.24.0) repart toujours sur votre MariaDB, intacte. Avec une pile officielle, figez-la dans .env — en gardant le service db de la pile :

TENTACLE_VERSION=v1.24.0

This only works while MariaDB is still there: keep it until you are sure. If you come back to the new version after the old one has written in MariaDB, Tentacle notices it and says so under To fix. Nothing is done automatically: the Database card offers Migrate again. The current SQLite database is then kept as a backup (tentacle.db.<date>.bak), and what was written since the first migration is replaced by MariaDB’s content.Cela ne marche que tant que MariaDB est là : gardez-la jusqu’à être sûr. Si vous revenez à la nouvelle version après que l’ancienne a écrit dans MariaDB, Tentacle s’en aperçoit et le dit dans À régler. Rien n’est fait d’office : la carte Base de données propose Migrer à nouveau. La base SQLite actuelle est alors gardée en copie (tentacle.db.<date>.bak), et ce qui a été écrit depuis la première migration est remplacé par le contenu de MariaDB.

If the migration does not completeSi la migration n’aboutit pas

The screen says “The migration did not complete” — your data is intact, the old database was not modified — with the reason in plain words. MariaDB is not modified and nothing is switched. Tentacle retries by itself (after 30 s, 1, 2, 5, 10, then every 15 minutes) and at each restart.L’écran dit « La migration n’a pas abouti » — vos données sont intactes, l’ancienne base n’a pas été modifiée — avec la raison en mots simples. MariaDB n’est pas modifiée et rien n’est basculé. Tentacle réessaie seul (après 30 s, 1, 2, 5, 10, puis toutes les 15 minutes) et à chaque redémarrage.

To retry at once, with a readable report, open the Tentacle container’s console (Portainer: Console) and type:Pour réessayer tout de suite, avec un rapport lisible, ouvrez la console du conteneur de Tentacle (Portainer : Console) et tapez :

tentacle db migrate

From a terminal on the machine, give the container’s name:Depuis un terminal de la machine, avec le nom du conteneur :

docker exec <container> tentacle db migrate

The log’s [db-migration] lines say exactly what went wrong — table names and counts, never your data.Les lignes [db-migration] du journal disent exactement ce qui coince — des noms de tables et des comptes, jamais vos données.

MariaDB removed too earlyMariaDB retirée trop tôt

If the stack lost its db service or its DB_* variables before the migration, Tentacle does not start on an empty database: it stays on the waiting screen and says “This installation used a MariaDB database that is no longer configured”. Put the database service and its variables back, restart, let the migration run, then remove them.Si la pile a perdu son service db ou ses variables DB_* avant la migration, Tentacle ne démarre pas sur une base vide : il reste sur l’écran d’attente et dit « Cette installation utilisait une base MariaDB qui n’est plus configurée ». Remettez le service de la base et ses variables, redémarrez, laissez la migration se faire, puis retirez-les.

Tentacle recognizes such an installation by what it left in its data folder, even one that never ran 1.24.Tentacle reconnaît une telle installation à ce qu’elle a laissé dans son dossier de données, même sans être jamais passée par la 1.24.

• Portainer stack deployed from the repository (Repository): it receives the new tentacle-full as soon as it is published, before having migrated. Set its reference to the tag refs/tags/server-v1.24.0 and redeploy: the old stack comes back, its MariaDB with it, and the current image migrates. Once the dashboard says “MariaDB is no longer needed”, set the reference back to refs/heads/main and redeploy.Pile Portainer déployée depuis le dépôt (Repository) : elle reçoit la nouvelle tentacle-full dès sa publication, avant d’avoir migré. Mettez sa référence sur l’étiquette refs/tags/server-v1.24.0 et redéployez : l’ancienne pile revient, sa MariaDB avec elle, et l’image actuelle migre. Quand le tableau de bord dit « MariaDB n’est plus nécessaire », remettez la référence sur refs/heads/main et redéployez.
• By hand: the old files are kept under that tag — tentacle-full, tentacle-db. Put yours back in the same folder for the migration, then come back to the new one.À la main : les anciens fichiers restent sous cette étiquette — tentacle-full, tentacle-db. Remettez le vôtre dans le même dossier le temps de la migration, puis revenez au nouveau.

That database is lost for good, or you really want to start over? In the container’s console:Cette base est perdue pour de bon, ou vous voulez vraiment repartir de zéro ? Dans la console du conteneur :

tentacle db start-fresh --confirm

Then restart: the setup wizard opens on a new installation. The old database is not touched.Puis redémarrez : l’assistant s’ouvre sur une installation neuve. L’ancienne base n’est pas touchée.

NAS and network sharesNAS et partages réseau

SQLite needs its file on a local disk. On a network share (NFS, SMB/CIFS, a folder mounted from another NAS), it can get corrupted. Tentacle checks the data folder at start-up and warns you — in the log and on the Database card — without blocking.SQLite veut son fichier sur un disque local. Sur un partage réseau (NFS, SMB/CIFS, un dossier monté depuis un autre NAS), il peut s’abîmer. Tentacle vérifie le dossier de données au démarrage et vous prévient — dans le journal et sur la carte Base de données — sans bloquer.

• A NAS running Tentacle itself (Synology, QNAP, Unraid, TrueNAS) keeps the data on its own disks: that is local, all is well.Un NAS qui fait tourner Tentacle lui-même (Synology, QNAP, Unraid, TrueNAS) garde les données sur ses propres disques : c’est local, tout va bien.
• Tentacle on one machine, its data folder on another machine’s share: move tentacle-data to a local disk. Your media can stay on the share — only Jellyfin reads them.Tentacle sur une machine, son dossier de données sur le partage d’une autre : déplacez tentacle-data sur un disque local. Vos médias peuvent rester sur le partage — seul Jellyfin les lit.
• A virtual disk (a VM or container disk stored on a SAN, iSCSI, Ceph RBD) formatted in ext4, xfs, btrfs or zfs counts as local.Un disque virtuel (le disque d’une VM ou d’un conteneur rangé sur un SAN, iSCSI, Ceph RBD) formaté en ext4, xfs, btrfs ou zfs compte comme local.

Backing up, restoring: see The database.Sauvegarder, restaurer : voir La base de données.

Questions you might haveLes questions qu’on se pose