Installation

BetterMyAdmin does not apply any special security methods to the MySQL database server. It is still the system administrator’s job to grant permissions on the MySQL databases properly. BetterMyAdmin’s Users page can be used for this.

BetterMyAdmin is one Node.js process that serves the web application and its API. It needs no PHP and no web server in front of it; put a reverse proxy with TLS in front of it before exposing it to a network (see Securing your BetterMyAdmin installation).

Installing using Docker

Released images are published on the GitHub Container Registry:

docker run -d -p 8080:80 -e BMA_HOST=mysql.example.org \
    -v bma-data:/var/lib/bettermyadmin ghcr.io/cb-sigma/better-myadmin:latest

then open http://localhost:8080. Pin a release version (:X.Y.Z) instead of :latest in production.

The image takes the variables of phpMyAdmin’s official Docker image, so a compose file written for the phpmyadmin image works with the image name swapped. It keeps its sessions, the generated blowfish_secret and its local metadata in the /var/lib/bettermyadmin volume, runs as the unprivileged node user and listens on port 80 inside the container (BMA_LISTEN_PORT changes it).

Docker environment variables

Every variable of the official phpMyAdmin image works, so a compose file written for phpmyadmin runs BetterMyAdmin with only the image name changed. Each also has a BetterMyAdmin name, which is the one to use in new setups (the PMA_ names stay supported; when both are set, the BMA_ one wins):

BetterMyAdmin

phpMyAdmin image (also read)

Effect

BMA_HOST

PMA_HOST

the server to log in to (default: the linked db)

BMA_PORT

PMA_PORT

that server’s port

BMA_HOST_LABEL

PMA_VERBOSE

that server’s name in the server list

BMA_HOSTS

PMA_HOSTS

several servers, comma-separated

BMA_PORTS

PMA_PORTS

their ports

BMA_HOST_LABELS

PMA_VERBOSES

their names

BMA_SOCKET

PMA_SOCKET

a server reached through a socket

BMA_SOCKETS

PMA_SOCKETS

several socket servers, comma-separated

BMA_ARBITRARY_SERVER

PMA_ARBITRARY

1: the login form can name any server

BMA_USER

PMA_USER

config authentication: log in as this user, no login form

BMA_PASSWORD

PMA_PASSWORD

that user’s password

BMA_ABSOLUTE_URI

PMA_ABSOLUTE_URI

the public URL behind a reverse proxy

BMA_STORAGE_DB

PMA_PMADB

the configuration storage database (phpmyadmin)

BMA_CONTROL_HOST

PMA_CONTROLHOST

the configuration storage’s server

BMA_CONTROL_PORT

PMA_CONTROLPORT

its port

BMA_CONTROL_USER

PMA_CONTROLUSER

the control user

BMA_CONTROL_PASSWORD

PMA_CONTROLPASS

the control user’s password

BMA_QUERY_HISTORY_DB

PMA_QUERYHISTORYDB

keep the SQL history in the configuration storage

BMA_QUERY_HISTORY_MAX

PMA_QUERYHISTORYMAX

how many history entries to keep

BMA_UPLOAD_DIR

PMA_UPLOADDIR

server-side directory to import files from

BMA_SAVE_DIR

PMA_SAVEDIR

server-side directory to save exports to

BMA_SSL

PMA_SSL

1: TLS to the MySQL server

BMA_SSL_VERIFY

PMA_SSL_VERIFY

verify the server’s certificate

BMA_SSL_CA

PMA_SSL_CA

CA certificate file

BMA_SSL_KEY

PMA_SSL_KEY

client key file

BMA_SSL_CERT

PMA_SSL_CERT

client certificate file

BMA_SSLS

PMA_SSLS

the same per server of BMA_HOSTS, comma-separated

BMA_SSL_VERIFIES

PMA_SSL_VERIFIES

″

BMA_SSL_CAS

PMA_SSL_CAS

″

BMA_SSL_KEYS

PMA_SSL_KEYS

″

BMA_SSL_CERTS

PMA_SSL_CERTS

″

BMA_SSL_CA_BASE64

PMA_SSL_CA_BASE64

the CA certificate itself, base64 (written to BMA_SSL_DIR)

BMA_SSL_KEY_BASE64

PMA_SSL_KEY_BASE64

the client key itself, base64

BMA_SSL_CERT_BASE64

PMA_SSL_CERT_BASE64

the client certificate itself, base64

BMA_SSL_CAS_BASE64

PMA_SSL_CAS_BASE64

″ per server

BMA_SSL_KEYS_BASE64

PMA_SSL_KEYS_BASE64

″ per server

BMA_SSL_CERTS_BASE64

PMA_SSL_CERTS_BASE64

″ per server

BMA_SSL_DIR

PMA_SSL_DIR

where the *_BASE64 files are written

BMA_UPLOAD_LIMIT

UPLOAD_LIMIT

the largest upload, e.g. 64M (MaxUploadSize; default 512M)

BMA_EXEC_TIME_LIMIT

MAX_EXECUTION_TIME

seconds an import or export may run (ExecTimeLimit)

BMA_MEMORY_LIMIT

MEMORY_LIMIT

MemoryLimit (no effect: imports and exports stream)

BMA_LISTEN_PORT

APACHE_PORT

the port BetterMyAdmin listens on in the container (default 80)

BMA_USER_FILE, BMA_PASSWORD_FILE, BMA_HOST_FILE, BMA_HOSTS_FILE, BMA_CONTROL_HOST_FILE, BMA_CONTROL_USER_FILE, BMA_CONTROL_PASSWORD_FILE

PMA_USER_FILE, PMA_PASSWORD_FILE, …

the same values read from files (Docker secrets)

PMA_CONFIG_BASE64, PMA_USER_CONFIG_BASE64 and /etc/phpmyadmin/conf.d hold PHP code and are not read; use a configuration file instead (below).

Customizing configuration file using Docker

Mount a configuration file into /etc/bettermyadmin:

docker run -d -p 8080:80 -v ./bettermyadmin.config.json:/etc/bettermyadmin/bettermyadmin.config.json:ro \
    -v bma-data:/var/lib/bettermyadmin ghcr.io/cb-sigma/better-myadmin:latest

Installing from a checkout

BetterMyAdmin needs Node.js 22.5 or later and pnpm:

git clone https://github.com/cB-Sigma/better-myadmin.git
cd better-myadmin
pnpm install --frozen-lockfile
pnpm build          # the web application (apps/web/dist)
pnpm start          # http://127.0.0.1:8080

pnpm start runs node apps/server/bin/bettermyadmin.mjs, which takes --config <file>, --host, --port and --static <dir>.

Quick Install

  1. Start BetterMyAdmin with Docker (Installing using Docker) or from a checkout (Installing from a checkout).

  2. Configure it. Settings come from four layers, each overriding the one before:

    1. the defaults: every directive of Configuration with its default value;

    2. the Docker variables above;

    3. a configuration file: --config <file>, the BMA_CONFIG variable, or the first of bettermyadmin.config.ts, .js, .mjs, .json, .yaml, .yml in the working directory (/etc/bettermyadmin in the image);

    4. BMA__<Directive>[__<Sub>…] environment variables (BMA__Servers__1__host=db, BMA__MaxRows=50), plus the shortcuts BMA_HOST, BMA_PORT, BMA_USER, BMA_PASSWORD, BMA_ARBITRARY_SERVER and BMA_ABSOLUTE_URI.

  3. Log in with a MySQL account.

Manually creating the file

The configuration file holds every directive of Configuration as data: $cfg['X'] in this documentation is the key X of the file, and $cfg['Servers'][$i] is an entry of its Servers list (server 1 first). If the default value is okay for a particular setting, there is no need to include it. A simple configuration may look like this:

{
  "blowfish_secret": "a 32-byte or longer random string",
  "Servers": [
    { "host": "db.example.org", "auth_type": "cookie" }
  ]
}

Or, if you prefer to not be prompted every time you log in:

{
  "Servers": [
    { "host": "db.example.org", "auth_type": "config", "user": "root", "password": "changeme" }
  ]
}

Warning

Storing passwords in the configuration is insecure as anybody can then manipulate your database.

A TypeScript file gives type checking and completion over every directive:

// bettermyadmin.config.ts
import { defineConfig } from '@bettermyadmin/config'

export default defineConfig({
  Servers: [{ host: 'db.example.org', auth_type: 'cookie' }],
  MaxRows: 50,
})

An unknown directive or an invalid value stops the server with a message naming the closest directive. Without a blowfish_secret, one is generated into $cfg['DataDir'] on the first start. The directives of a phpMyAdmin config.inc.php keep their names, so it translates key for key, and BetterMyAdmin converts one for you:

bettermyadmin import-pma-config /etc/phpmyadmin/config.inc.php -o bettermyadmin.config.json

(node apps/server/bin/bettermyadmin.mjs import-pma-config … from a checkout, docker run --rm -v /etc/phpmyadmin:/pma:ro ghcr.io/cb-sigma/better-myadmin node /app/apps/server/bin/bettermyadmin.mjs import-pma-config /pma/config.inc.php with Docker). The file is read, not run: the importer evaluates the subset of PHP that configuration files use (getenv() reads the environment), and the result is checked like a configuration file before it is written. Without -o the JSON goes to standard output; an existing file is only replaced with --force. The setup script (below) also shows the configuration it builds in both formats.

For a full explanation of possible configuration values, see the Configuration of this document.

Using the Setup script

Until a configuration file exists, the setup script at /setup is open without a login, and the server prints a warning when it starts. It lets you build a configuration page by page and saves it as bettermyadmin.config.json (or shows it for you to copy). Write a configuration file before exposing the server.

phpMyAdmin configuration storage

Changed in version 3.4.0: Prior to phpMyAdmin 3.4.0 this was called Linked Tables Infrastructure, but the name was changed due to the extended scope of the storage.

For a whole set of additional features (Bookmarks, comments, SQL-history, tracking mechanism, PDF-generation, Transformations, Relations etc.) you need to create a set of special tables. Those tables can be located in your own database, or in a central database for a multi-user installation (this database would then be accessed by the controluser, so no other user should have rights to it).

BetterMyAdmin uses phpMyAdmin’s configuration storage as it is: the same database (phpmyadmin by default, see $cfg['Servers'][$i]['pmadb']), the same pma__* tables and the same contents. BetterMyAdmin and phpMyAdmin can therefore share one configuration storage, and you can switch from one to the other without losing bookmarks, relations, user preferences or two-factor settings.

Without a configuration storage, BetterMyAdmin keeps the per-user data (bookmarks, SQL history, recent and favorite tables, table display preferences and user preferences) in a local SQLite file in $cfg['DataDir']; phpMyAdmin offers these only with the storage, or keeps them until you log out. The features that describe the databases themselves (relations, comments, transformations, tracking, …) still need the configuration storage, as they must be shared by all users.

Zero configuration

In many cases, this database structure can be automatically created and configured. This is called “Zero Configuration” mode and can be particularly useful in shared hosting situations. “ZeroConf” mode is on by default, to disable set $cfg['ZeroConf'] to false.

The following three scenarios are covered by the Zero Configuration mode:

  • When entering a database where the configuration storage tables are not present, BetterMyAdmin offers to create them from the Operations tab.

  • When entering a database where the tables do already exist, the software automatically detects this and begins using them. This is the most common situation; after the tables are initially created automatically they are continually used without disturbing the user; this is also most useful on shared hosting where the user is not able to edit the configuration file and usually the user only has access to one database.

  • When having access to multiple databases, if the user first enters the database containing the configuration storage tables then switches to another database, BetterMyAdmin continues to use the tables from the first database; the user is not prompted to create more tables in the new database.

Manual configuration

The tables are created by the SQL script packages/metadata/resources/create_tables.sql of the BetterMyAdmin repository, which is phpMyAdmin’s resources/sql/create_tables.sql. (If your database server runs on Windows, pay special attention to 1.23 I’m running MySQL on a Win32 machine. Each time I create a new table the table and column names are changed to lowercase!.)

If you already had this infrastructure and upgraded to phpMyAdmin 4.3.0 or newer from 2.5.0 or newer (<= 4.2.x), please use packages/metadata/resources/upgrade_column_info_4_3_0+.sql (phpMyAdmin’s resources/sql/upgrade_column_info_4_3_0+.sql); for older upgrades, use the scripts shipped with phpMyAdmin.

You can use BetterMyAdmin to create the tables for you: import create_tables.sql from the Import tab, or use the links of the configuration storage check page (linked from the home page and the Operations tab). Please be aware that you may need special (administrator) privileges to create the database and tables, and that the script may need some tuning, depending on the database name.

After having created the tables, you should specify the table names in your configuration file. The directives used for that can be found in the Configuration (see also the basic example in Examples).

You will also need to have a controluser ($cfg['Servers'][$i]['controluser'] and $cfg['Servers'][$i]['controlpass'] settings, or the Docker variables PMA_CONTROLUSER and PMA_CONTROLPASS) with the proper rights to those tables. For example you can create it using following statement:

And for any MariaDB version:

CREATE USER 'pma'@'localhost' IDENTIFIED VIA mysql_native_password USING 'pmapass';
GRANT SELECT, INSERT, UPDATE, DELETE ON `<pma_db>`.* TO 'pma'@'localhost';

For MySQL 8.0 and newer:

CREATE USER 'pma'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'pmapass';
GRANT SELECT, INSERT, UPDATE, DELETE ON <pma_db>.* TO 'pma'@'localhost';

For MySQL older than 8.0:

CREATE USER 'pma'@'localhost' IDENTIFIED WITH mysql_native_password AS 'pmapass';
GRANT SELECT, INSERT, UPDATE, DELETE ON <pma_db>.* TO 'pma'@'localhost';

The host in these statements is the host BetterMyAdmin connects from, as the MySQL server sees it: with Docker, that is usually the container’s address rather than localhost. BetterMyAdmin’s MySQL driver supports caching_sha2_password, so the mysql_native_password workaround that phpMyAdmin needs with old PHP versions is not necessary (see 1.45 I get an error message about unknown authentication method caching_sha2_password when trying to log in).

Upgrading from an older version

Your configuration file, the Docker variables and the phpMyAdmin configuration storage carry over from one version to the next. A directive that a new version no longer knows stops the server with a message naming it, rather than being silently ignored; one that phpMyAdmin removed only gives a warning at start.

With Docker, pull the new image and recreate the container, keeping the data volume (/var/lib/bettermyadmin) and your configuration file:

docker pull ghcr.io/cb-sigma/better-myadmin:X.Y.Z
docker rm -f bettermyadmin
docker run -d --name bettermyadmin -p 8080:80 -e BMA_HOST=mysql.example.org \
    -v bma-data:/var/lib/bettermyadmin ghcr.io/cb-sigma/better-myadmin:X.Y.Z

or, with Docker Compose, change the image tag and run docker compose pull && docker compose up -d.

From a checkout, update the sources, the dependencies and the web application, then restart the server:

git pull
pnpm install --frozen-lockfile
pnpm build
pnpm start

The release notes of each version are in the changelog.

If you have upgraded your phpMyAdmin to 4.3.0 or newer from 2.5.0 or newer (<= 4.2.x) and if you use the phpMyAdmin configuration storage, you should run the SQL script found in packages/metadata/resources/upgrade_column_info_4_3_0+.sql.

Do not forget to clear the browser cache and to empty the old session by logging out and logging in again.

Using authentication modes

HTTP and cookie authentication modes are recommended in a multi-user environment where you want to give users access to their own database and don’t want them to play around with others. Even in a single-user environment, you might prefer to use HTTP or cookie mode so that your user/password pair are not in clear in the configuration file.

HTTP and cookie authentication modes are more secure: the MySQL login information does not need to be set in the BetterMyAdmin configuration file (except possibly for the $cfg['Servers'][$i]['controluser']). However, keep in mind that the password travels in plain text unless you are using the HTTPS protocol. In every mode, BetterMyAdmin keeps the credentials encrypted (AES-256-GCM) in its server-side session store; the browser only gets a cookie with the session id. (phpMyAdmin stores the encrypted password in the cookie itself.)

Then each of the true users should be granted a set of privileges on a set of particular databases. Normally you shouldn’t give global privileges to an ordinary user unless you understand the impact of those privileges (for example, you are creating a superuser). For example, to grant the user real_user with all privileges on the database user_base:

GRANT ALL PRIVILEGES ON user_base.* TO 'real_user'@localhost IDENTIFIED BY 'real_password';

What the user may now do is controlled entirely by the MySQL user management system. With HTTP or cookie authentication mode, you don’t need to fill the user/password fields inside the $cfg['Servers'].

HTTP authentication mode

Note

There is no way to do proper logout in HTTP authentication, most browsers will remember credentials until there is no different successful authentication. Because of this, this method has a limitation that you can not login with the same user after logout.

Signon authentication mode

phpMyAdmin reads the credentials from the other application’s PHP session and runs PHP signon scripts. BetterMyAdmin cannot run PHP, so its signon mode works with the same keys (PMA_single_signon_user, PMA_single_signon_password, PMA_single_signon_host, …) in a different container:

  • the SignonSession is a cookie of that name whose value is encrypted with a key derived from $cfg['blowfish_secret'] (the other application uses encodeSignonSession from BetterMyAdmin’s sources, or runs on the same host as BetterMyAdmin and shares the cookie);

  • the login page can be served by BetterMyAdmin itself, from a JavaScript module named by $cfg['Servers'][$i]['SignonPage'] (in phpMyAdmin it is a PHP page run by the same web server);

  • $cfg['Servers'][$i]['SignonScript'] names a JavaScript or TypeScript module exporting getLoginCredentials(user) instead of a PHP file.

The simplest setup is a login page served by BetterMyAdmin, apps/server/examples/signon-page.mjs, which stores the credentials typed into a form (the counterpart of phpMyAdmin’s examples/signon.php):

/**
 * `SignonPage` example: the login page of a signon server, served by BetterMyAdmin itself at
 * SignonURL's path (parity exception X54). The in-process counterpart of examples/signon.ts /
 * phpMyAdmin's examples/signon.php: a form whose credentials go into the SignonSession.
 *
 *   Servers: [{ auth_type: 'signon', SignonSession: 'SignonSession', SignonURL: '/signon/',
 *               LogoutURL: '/signon/?logout', SignonPage: './apps/server/examples/signon-page.mjs' }]
 *
 * The module exports a function (default or `signonPage`) taking the request and a context with
 * the current SignonSession, `sessionCookie(data)`, the Set-Cookie value that stores one
 * (`null` clears it), and `returnTo`, the page the user asked for before being sent here. A relative path is resolved against BetterMyAdmin's working directory.
 *
 * pma: examples/signon.php
 */
const esc = (s) => String(s).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)

export default async function signonPage(request, { session, sessionCookie, returnTo }) {
  const url = new URL(request.url)
  if (url.searchParams.has('logout')) {
    return new Response(null, {
      status: 302,
      headers: { 'Set-Cookie': sessionCookie(null), Location: url.pathname },
    })
  }
  if (request.method === 'POST') {
    const form = new URLSearchParams(await request.text())
    const cookie = sessionCookie({
      PMA_single_signon_user: form.get('user') ?? '',
      PMA_single_signon_password: form.get('password') ?? '',
    })
    return new Response(null, { status: 302, headers: { 'Set-Cookie': cookie, Location: returnTo } })
  }
  const error = session?.PMA_single_signon_error_message
  return new Response(
    `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>BetterMyAdmin single signon example</title></head>
<body>${error === undefined ? '' : `<p class="error">${esc(error)}</p>`}
<form action="${esc(url.pathname)}" method="post">
<label>User: <input type="text" name="user" autocomplete="username"></label>
<label>Password: <input type="password" name="password" autocomplete="current-password"></label>
<input type="submit"></form></body></html>`,
    { headers: { 'Content-Type': 'text/html; charset=utf-8' } },
  )
}

/**
 * Optional: the credentials of an agent API request (AgentApi, docs-site/agents.rst), which has no
 * SignonSession cookie. Read them from the request (a sign-on proxy's header, a token…) and return
 * the MySQL user and password, or null. This example has no such source: agent requests are refused.
 *
 * @param {Request} _request
 * @returns {{ user: string, password: string } | null}
 */
export function agentCredentials(_request) {
  return null
}

A separate login application writes the cookie itself, as in apps/server/examples/signon.ts (run with BMA_SECRET=<blowfish_secret> npx tsx apps/server/examples/signon.ts):

/**
 * Single signon example: a tiny login application handing credentials to BetterMyAdmin through
 * the `SignonSession` cookie (`auth_type = 'signon'`), the port of phpMyAdmin's examples/signon.php.
 *
 *   BMA_SECRET=<BetterMyAdmin's blowfish_secret> npx tsx apps/server/examples/signon.ts
 *
 * BetterMyAdmin configuration (the example listens on :8090, BetterMyAdmin on :8080, one host so
 * the cookie is shared):
 *
 *   Servers: [{ auth_type: 'signon', SignonSession: 'SignonSession', SignonURL: 'http://localhost:8090/' }]
 *
 * pma: examples/signon.php
 */
import { createServer } from 'node:http'
import { decodeSignonSession, encodeSignonSession } from '../src/auth/signon.ts'

const secret = process.env.BMA_SECRET ?? ''
const sessionName = 'SignonSession'
const bma = process.env.BMA_URL ?? 'http://localhost:8080/'

const esc = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
const cookieOf = (header: string | undefined, name: string) =>
  header
    ?.split(';')
    .map((p) => p.trim().split('='))
    .find(([k]) => k === name)?.[1]

createServer((req, res) => {
  if (req.method === 'POST') {
    let body = ''
    req.on('data', (d) => {
      body += d
    })
    req.on('end', () => {
      const f = new URLSearchParams(body)
      // store the credentials, and update another field of the server configuration
      const value = encodeSignonSession(secret, {
        PMA_single_signon_user: f.get('user') ?? '',
        PMA_single_signon_password: f.get('password') ?? '',
        ...(f.get('host') ? { PMA_single_signon_host: f.get('host') as string } : {}),
        ...(f.get('port') ? { PMA_single_signon_port: f.get('port') as string } : {}),
        PMA_single_signon_cfgupdate: { verbose: 'Signon test' },
      })
      // the cookie parameters must match SignonCookieParams (path '/', httponly here)
      res.writeHead(302, {
        'Set-Cookie': `${sessionName}=${value}; Path=/; HttpOnly; SameSite=Lax`,
        Location: bma,
      })
      res.end()
    })
    return
  }
  const value = cookieOf(req.headers.cookie, sessionName)
  const error =
    value === undefined ? undefined : decodeSignonSession(secret, value)?.PMA_single_signon_error_message
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
  res.end(`<!DOCTYPE HTML>
<html lang="en" dir="ltr">
<head><meta charset="utf-8"><title>BetterMyAdmin single signon example</title></head>
<body>
${error !== undefined ? `<p class="error">${esc(error)}</p>` : ''}
<form action="/" method="post">
Username: <input type="text" name="user" autocomplete="username" spellcheck="false"><br>
Password: <input type="password" name="password" autocomplete="current-password" spellcheck="false"><br>
Host: (will use the one from the configuration by default) <input type="text" name="host"><br>
Port: (will use the one from the configuration by default) <input type="text" name="port"><br>
<input type="submit">
</form>
</body>
</html>`)
}).listen(Number(process.env.PORT ?? 8090))

phpMyAdmin’s OpenID example (examples/openid.php) has no BetterMyAdmin counterpart; an OpenID or other single signon front end can use either of the ways above.

If you intend to pass the credentials using some other means than the cookie, you have to implement a module to get that data and set it to $cfg['Servers'][$i]['SignonScript']. There is a very minimal example in apps/server/examples/signon-script.ts:

/**
 * `SignonScript` example: BetterMyAdmin imports this module and calls `getLoginCredentials(user)`
 * with the server's configured `user` on every page load; it returns `[user, password]` (or a
 * promise of it). An empty user redirects to SignonURL. The port of phpMyAdmin's
 * examples/signon-script.php (where the PHP function is `get_login_credentials`).
 *
 *   Servers: [{ auth_type: 'signon', SignonScript: './apps/server/examples/signon-script.ts', SignonURL: '…' }]
 *
 * A relative path is resolved against BetterMyAdmin's working directory. A `.ts` module needs a
 * TypeScript-aware Node (≥ 22.18 or tsx), a `.mjs` / `.js` one works everywhere.
 *
 * pma: examples/signon-script.php
 */
export function getLoginCredentials(user: string): [string, string] {
  // this would usually check the request (a header set by a reverse proxy, a ticket, …)
  return [user, process.env.SIGNON_PASSWORD ?? '']
}

Config authentication mode

  • This mode is sometimes the less secure one because it requires you to fill the $cfg['Servers'][$i]['user'] and $cfg['Servers'][$i]['password'] fields (or the Docker variables PMA_USER and PMA_PASSWORD), and as a result, anyone who can read your configuration file or environment can discover your username and password.

  • In the ISPs, multi-user installations section, there is an entry explaining how to protect your configuration file.

  • For additional security in this mode, you may wish to consider the Host authentication $cfg['Servers'][$i]['AllowDeny']['order'] and $cfg['Servers'][$i]['AllowDeny']['rules'] configuration directives.

  • Unlike cookie and http, does not require a user to log in when first loading the BetterMyAdmin site. This is by design but could allow any user to access your installation. Use of some restriction method is suggested: keep BetterMyAdmin listening on 127.0.0.1 (the default of $cfg['Listen']['host']), put an authenticating reverse proxy in front of it, or disallow incoming HTTP requests at one’s router or firewall.

Securing your BetterMyAdmin installation

The BetterMyAdmin project tries hard to make the application secure, however there are always ways to make your installation more secure. See also Security policy.

Using SSL for connection to database server

It is recommended to use SSL when connecting to remote database server. There are several configuration options involved in the SSL setup:

$cfg['Servers'][$i]['ssl']

Defines whether to use SSL at all. If you enable only this, the connection will be encrypted, but there is not authentication of the connection - you can not verify that you are talking to the right server.

$cfg['Servers'][$i]['ssl_key'] and $cfg['Servers'][$i]['ssl_cert']

This is used for authentication of client to the server.

$cfg['Servers'][$i]['ssl_ca'] and $cfg['Servers'][$i]['ssl_ca_path']

The certificate authorities you trust for server certificates. This is used to ensure that you are talking to a trusted server.

$cfg['Servers'][$i]['ssl_verify']

This configuration disables server certificate verification. Use with caution.

With Docker, the PMA_SSL, PMA_SSL_VERIFY, PMA_SSL_CA, PMA_SSL_KEY and PMA_SSL_CERT variables set these (see Docker environment variables).

When the database server is using a local connection or private network and SSL can not be configured you can use $cfg['MysqlSslWarningSafeHosts'] to explicitly list the hostnames that are considered secure.

Known issues

Users with column-specific privileges are unable to “Browse”

If a user has only column-specific privileges on some (but not all) columns in a table, “Browse” will fail with an error message, as in phpMyAdmin.

As a workaround, a bookmarked query with the same name as the table can be created, this will run when using the “Browse” link instead. phpMyAdmin issue 11922.

Trouble logging back in after logging out using ‘http’ authentication

When using the ‘http’ auth_type, the browser keeps sending the same credentials after a logout, so BetterMyAdmin refuses that user once to end the session; logging back in with the same user may need the browser to forget the credentials first. phpMyAdmin issue 11898.