Browsing your database (Adminer)

Sometimes you need to look straight at a site's database — to check a value, run a quick query, export a single table, or fix one stubborn row by hand. BOA ships a small web tool called Adminer for exactly that. It's a database browser that runs in your web browser, so you don't need to install anything or run any database commands yourself.

Your host has already installed Adminer and put it behind HTTPS for you. Your job is just to open the address, log in with a site's own database credentials, and you're in — looking at that site's tables. Log in with a given site's credentials and that's the schema you land in; because BOA grants each site's database user rights over only that site's own database, that login normally reaches nothing else.

One thing worth understanding up front: this is a single Adminer, shared by the whole server, and it will happily connect with any valid database login — what you can see after logging in is whatever that particular MySQL user was granted, not a fence the tool puts around one site. The wall that actually keeps this tool private is at the network level: your host only allows approved locations to reach the address at all (see When it won't open). That allow-list, not the login form, is the real front door.

This is a sharp tool, so this page also covers the handful of habits worth keeping so a five-minute look-around never turns into a bad afternoon.

Where to find Adminer

Adminer lives at /sqladmin/ on your own Aegir control-panel address — the same https:// address you log into to manage your sites. So if you reach your control panel at https://aegir.example.com, Adminer is at:

https://aegir.example.com/sqladmin/

You don't have to hunt for this or ask anyone: it's your control-panel URL with /sqladmin/ on the end. (The welcome email you got when your account was set up lists this same address under "Managing your databases".) It's HTTPS-only, so the address always starts with https://.

There's nothing to install and no separate password to set up for Adminer itself — you log in with a site's database credentials, which the next section shows you how to find.

Finding a site's database credentials

Every site BOA runs has its own private database, with its own name, username, and password. BOA generated all three for you when it built the site, and you log into Adminer with them.

The place to read them is the site's drushrc.php file, which lives inside your account alongside the site:

platforms/<platform>/sites/<your-site-domain>/drushrc.php

Open it over SFTP, or with nano in your shell. Near the Aegir section you'll find the three values you need, spelled out in full:

$options['db_name'] — the database name
$options['db_user'] — the username
$options['db_passwd'] — the password

(You'll also see db_host and db_port there — handy if you ever need them, though for Adminer the defaults are usually fine.)

Why drushrc.php and not settings.php? On BOA both files actually carry the real credentials — BOA writes the literal database password into settings.php too (that's what lets each site's own Drush work). But drushrc.php lays them out cleanly as the three named $options[...] lines above, whereas in settings.php the same values are buried in the Drupal $databases array. drushrc.php is simply the easier file to copy from — either one has the true values.

Two of the three also show up in your control panel: open the site in the Aegir web control panel and its info panel lists the Database server and Database name. The panel doesn't show the password, though — for that you read the site's drushrc.php as above.

You never have to invent or reset these credentials. They already exist and they're already correct; you're just copying them from the file into the login form.

Logging in

Open https://<your-control-panel-address>/sqladmin/ in your browser.
Adminer shows a login form. Fill it in with the site's values from drushrc.php:
- System / driver: MySQL (the default — leave it).
- Server: localhost unless the db_host line in drushrc.php shows a different host.
- Username: the site's db_user value.
- Password: the site's db_passwd value.
- Database: the site's db_name value.
Log in. You're now looking at that one site's database — its tables listed down the side, ready to browse.

Because a site's own database user is granted rights over just that site's database, logging in with those credentials lands you in that one site's tables. To look at a different site, log out and log back in with that site's credentials. (What you can reach is set by the MySQL user's grants, not by Adminer itself — so stick to each site's own drushrc.php credentials and you stay neatly inside that one site.)

What you can do here

Adminer is genuinely handy for the everyday "let me just check the database" jobs:

Browse the structure — click through the database, its tables, and columns to see how a site is laid out.
Run a quick query — the SQL command box lets you run a SELECT to look something up, or a careful UPDATE to fix a single value.
Export a table — dump one table (or a few) to a file when you want a copy of just part of the data. This is great for small tables; for a full-site backup use the proper backup tools instead (see Related pages below).
Inspect indexes and the like — check which columns are indexed, look at views and triggers, and generally understand a schema.

It's perfect for a spot-check or a one-row fix. It is not the tool for moving a whole site's worth of data around — a big export will crawl or time out in the browser. When you need the whole database, reach for a backup instead.

A few safety habits

Editing a live database by hand is the kind of thing that's completely fine right up until it isn't. A few habits keep you safe:

Take a backup first. Before you change anything, grab a fresh backup of the site. Then a mistake is a quick restore away rather than a real problem. See Backups.
Read before you write. Browsing and exporting can't hurt anything. Changing rows can. If you're only looking, you're perfectly safe — the caution is entirely about edits.
Prefer Drupal's own tools when they exist. For most jobs, doing it through the site's admin screens or a Drush command is safer than editing tables directly, because Drupal knows to clear its caches and keep related data in step. Reach for Adminer when there genuinely isn't a cleaner way.
Leave tables you don't recognise alone. Drupal keeps a lot of internal bookkeeping in its tables. If you don't know what a table is for, don't edit it.

None of this needs saying if you're just browsing — it's here for the day you decide to change something.

When it won't open

If you go to the Adminer address and the page simply won't load — a timeout, a connection refused, or a plain "forbidden" — that's almost always because your current internet location isn't on the list of addresses allowed to reach it. This allow-list is the main thing keeping Adminer private: it's the security boundary BOA actually enforces, so the tool isn't sitting open to the whole internet with only a login form in the way. (Known crawlers and bots are refused outright as well.)

Getting an address added to that allow-list is done on the server, which isn't something you can reach from your account. When you need it, that's a one-line support request: ask your host to add your current IP address to the Adminer allow-list, and tell them roughly where you're connecting from. Once they do, the address will load normally.

Everything else on this page — reading your credentials, logging in, browsing, editing — is entirely yours to do. It's only that first "let me in from this location" step that occasionally needs your host.

Backups — take one before any hand-edit, and use it (not an Adminer export) when you want a full copy of a site's database.
Your files and storage — where your platforms and sites live in your account, so you can find a site's drushrc.php.
Shell and SFTP access — how to connect so you can open drushrc.php and read the credentials.
Drush basics — the safer route for many database changes, since Drupal keeps its own data consistent.
Restricting access to your site — a different kind of access control (for your sites), also managed entirely from your own account.