GoAdmio

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

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:

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 backup or snapshot, 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

  1. Appends a timestamped line with the arguments to /var/log/go/img-out-db.log.
  2. If the first argument is restore, runs /usr/local/goadmio/tmp/restore.sh and stops.
  3. Works out the directory to search (see How the first argument is read).
  4. Stops if no database name was given.
  5. Dumps the database with mariadb-dump into /usr/local/goadmio/tmp/<database>.sql.
  6. Lists matching media files in /usr/local/goadmio/tmp/images.db.
  7. For each file, takes the last part of its path and searches the dump for it. If it is not found:
    1. counts and prints it
    2. moves it to /usr/local/goadmio/tmp/image
    3. appends a cp line to /usr/local/goadmio/tmp/restore.sh that 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


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