img-out-db
Move images and other media files that are not mentioned in a MySQL/MariaDB database into a holding folder, with a restore option
- Command:
/go/img-out-db - Category: Files and media
- Required arguments:
<domain|directory>and<database>(orrestore) - Output: Plain text (one numbered line per moved file)
- Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Arguments · Output · Examples · Troubleshooting · Details · See also
Overview
/go/img-out-db finds files in a site that its database never refers to, which is useful for cleaning up uploads that a CMS no longer uses. It:
- dumps the chosen database to a temporary SQL file
- lists the media files in the site directory
- checks each file name against the dump
- moves the files whose names are not found into a holding folder, and writes a restore script so they can be put back
Nothing is deleted. The files stay in /usr/local/goadmio/tmp/image until you remove them yourself.
[!WARNING] A file is moved when its name does not appear in the database dump. Files that are used by theme or template files, CSS, JavaScript, or another database are not in the dump, so they are moved too and the site can lose images. The command has no dry-run mode and does not check that the database dump succeeded. Take a backup first with
backuporsnapshot, and test the site afterwards.
Quick start
# Move unused media out of a site, using its database
/go/img-out-db example.com example_db
# Put everything back
/go/img-out-db restore
Syntax
# Move files that are not in the database
/go/img-out-db <domain|directory> <database>
# Copy moved files back to where they came from
/go/img-out-db restore
Arguments
| Position | Argument | Required | Notes |
|---|---|---|---|
| 1 | domain or directory |
Yes | A hosted domain (searches /home/<domain>/www) or the path of an existing directory. |
| 2 | database |
Yes, except for restore |
The MySQL/MariaDB database to compare against. |
| 1 | restore |
— | Runs the saved restore script instead of scanning. |
How the first argument is read
| Order | Check | Result |
|---|---|---|
| 1 | Is the value an existing directory? | It is searched as a path. |
| 2 | Does /home/<value>/www exist? |
That folder is searched. |
| 3 | Neither exists | Domain <value> does not exist. and the command stops. |
The directory check comes first and is relative to your current folder. If you are in a folder that contains a subfolder named like the domain, that subfolder is used instead of the site.
Files that are checked
| Type | Extensions |
|---|---|
| Images | .webp .jpeg .jpg .png .gif |
| Video | .mp4 |
| Documents | .pdf .doc |
| Archives | .zip .tar .gz |
Extensions are matched in lowercase only, so PHOTO.JPG is ignored. .docx is not included. The search covers every subfolder of the site.
Output
| Situation | Message |
|---|---|
| Moved a file | <number> - <path of the file> |
| Nothing to move | No output |
| Directory or domain not found | Domain <value> does not exist. |
| No database given | Please enter database name. |
restore |
No output. The exit code is always 1, even on success. |
The command prints no summary. The last number shown is the total of moved files.
Examples
# A hosted domain
/go/img-out-db example.com example_db
# A specific folder, such as WordPress uploads
/go/img-out-db /home/example.com/www/wp-content/uploads example_db
# Put all moved files back
/go/img-out-db restore
# Fix ownership after a restore
/go/fix example.com
# See what is waiting in the holding folder
ls /usr/local/goadmio/tmp/image | head
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Almost every file was moved | The database name is wrong, or the dump failed, so the dump is empty and nothing matches. | Run restore. Check the name with dbls, and confirm the dump in /usr/local/goadmio/tmp/<database>.sql is not empty. |
| Images missing on the site after a run | The files are used by theme, CSS, or template files rather than the database. | Run restore, then search a smaller folder such as uploads. |
unary operator expected |
The command was run with no arguments. | Pass a domain or directory and a database name. |
Domain <value> does not exist. |
No folder /home/<value>/www and no such directory. |
Check the spelling, or pass a full directory path. |
Please enter database name. |
The second argument is missing. | Add the database name. |
cannot stat errors |
A file name contains spaces. The script does not quote paths, so those files are not handled correctly. | Rename the files, or move them by hand. Do not rely on restore for them. |
| A restored file is wrong | Two files with the same name in different folders. The holding folder is flat, so the later move replaces the earlier one. | Recover the earlier file from a backup or snapshot. |
| Restored files cannot be read by the site | restore copies as root, so the files are owned by root. |
Run fix for the domain. |
restore fails with a missing file |
No scan has been run yet, so there is no restore script. | Nothing to restore. |
| Files with capital extensions were left | Only lowercase extensions are searched. | Handle them separately. |
Details
What it does
flowchart TD
A["/go/img-out-db target database"] --> B["Append the command to /var/log/go/img-out-db.log"]
B --> C{"First argument is restore?"}
C -- "Yes" --> D["Run restore.sh and exit"]
C -- "No" --> E{"Directory or domain found?"}
E -- "No" --> F["Print error and exit"]
E -- "Yes" --> G{"Database given?"}
G -- "No" --> H["Print error and exit"]
G -- "Yes" --> I["Dump the database to tmp/database.sql"]
I --> J["List media files into tmp/images.db"]
J --> K{"File name found in the dump?"}
K -- "Yes" --> L["Leave the file"]
K -- "No" --> M["Move it to tmp/image and add a cp line to restore.sh"]
L --> K
M --> K
Steps in order
- Appends a timestamped line with the arguments to
/var/log/go/img-out-db.log. - If the first argument is
restore, runs/usr/local/goadmio/tmp/restore.shand stops. - Works out the directory to search (see How the first argument is read).
- Stops if no database name was given.
- Dumps the database with
mariadb-dumpinto/usr/local/goadmio/tmp/<database>.sql. - Lists matching media files in
/usr/local/goadmio/tmp/images.db. - For each file, takes the last part of its path and searches the dump for it. If it is not found:
- counts and prints it
- moves it to
/usr/local/goadmio/tmp/image - appends a
cpline to/usr/local/goadmio/tmp/restore.shthat copies it back
Files it creates
All of them are in /usr/local/goadmio/tmp.
| Path | Contents | Lifetime |
|---|---|---|
<database>.sql |
Full dump of the database, which can hold private data. | Replaced on each run for that database, and never deleted automatically. |
images.db |
Candidate file list. | Replaced on each run. |
image/ |
The moved files, all in one flat folder. | Grows with every run. |
restore.sh |
One cp line per moved file. |
Lines are added on each run and never cleared. |
Notes
- A name match is a substring match on the dump, so
photo.jpgis kept if the dump mentionsmy-photo.jpg. The command errs toward keeping files that look related. - Names that the database stores in a different form, such as URL-encoded (
my%20photo.jpg) or escaped, are not found, so those files are moved. - Only one database is checked. A site that uses several databases can lose files that another one refers to.
restorereplays every line ever added, including those from earlier runs and other sites. Lines for folders that no longer exist fail.restorecopies rather than moves, so the holding folder keeps its files afterwards.- The dump and the holding folder take disk space. Delete
<database>.sqlonce you no longer need it. - The globs in the file search are not quoted. If the folder you run the command from contains files such as
a.png, the search can break, so run it from an empty folder such as/root.
See also
| Command | Description |
|---|---|
img |
Resize images on a GoAdmio server |
webp |
Convert images to WebP format |
pdf |
Compress PDF files in a site directory |
dbls |
List all databases and their sizes |
backup |
Create a backup for all GoAdmio accounts (local and remote) |
snapshot |
Restic-based per-domain snapshot backup and restore |
fix |
Fix GoAdmio file and folder permissions |
clean |
Clean and remove unnecessary files to free up space |