Not really a requirement but a strong suggestion:
if you are using
the "cookie" authentication method, having the mcrypt
PHP extension on your web server accelerates not only the login
phase but every other action that you do in phpMyAdmin.
Web browser with cookies enabled.
Introduction
phpMyAdmin can manage a whole MySQL server (needs a super-user) as well as
a single database. To accomplish the latter you'll need a properly set up
MySQL user who can read/write only the desired database. It's up to you to
look up the appropriate part in the MySQL manual.
Currently phpMyAdmin can:
easily browse through databases and tables
create, copy, rename, alter and drop databases
create, copy, rename, alter and drop tables
do table maintenance
add, edit and drop fields
execute any SQL-statement, even multiple queries
create, alter and drop indexes
load text files into tables
create (*) and read dumps of tables or databases
export (*) data to SQL, CSV, XML, Word, Excel, PDF and Latex formats
administer multiple servers
manage MySQL users and privileges
check server settings and runtime information with configuration
hints
check referential integrity in MyISAM tables
using Query-by-example (QBE), create complex queries automatically connecting required tables
create PDF graphics of your Database layout
search globally in a database or a subset of it
transform stored data into any format using a set of predefined functions,
like displaying BLOB-data as image or download-link
support InnoDB tables and foreign keys (see FAQ 3.6)
support mysqli, the improved MySQL extension (see FAQ 1.17)
Many people have difficulty
understanding the concept of user management with regards to phpMyAdmin. When
a user logs in to phpMyAdmin, that username and password are passed directly
to MySQL. phpMyAdmin does no account management on its own (other than
allowing one to manipulate the MySQL user account information); all users
must be valid MySQL users.
1) phpMyAdmin can compress (Zip, GZip -RFC 1952- or Bzip2 formats)
dumps and CSV exports if you use
PHP with Zlib support (--with-zlib) and/or Bzip2 support
(--with-bz2). Proper support may also need changes in
php.ini.
Installation
NOTE: phpMyAdmin 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. phpMyAdmin's
"Privileges" page can be used for this.
Warning for Mac users:if you are on a MacOS
version before OS X, StuffIt unstuffs with Mac formats.
So you'll have to resave as in BBEdit to Unix style ALL phpMyAdmin scripts
before uploading them to your server, as PHP seems not to like Mac-style
end of lines character ("\r").
Quick Install
Untar or unzip the distribution (be sure to unzip the subdirectories):
tar -xzvf phpMyAdmin_x.x.x.tar.gz in your webserver's
document root. If you don't have direct access to your document root,
put the files in a directory on your local machine, and, after step 3,
transfer the directory on your web server using, for example, ftp.
Ensure that all the scripts have the appropriate owner (if PHP is
running in safe mode, having some scripts with an owner different
from the owner of other scripts will be a
problem). See FAQ 4.2 and
FAQ 1.26 for suggestions.
Now you must configure your installation. There are two methods that
can be used. Traditionally, users have hand-edited a copy of
config.inc.php, but now a wizard-style setup script is provided for
those who prefer a graphical installation. Creating a config.inc.php is
still a quick way to get started and needed for some advanced features.
To manually create the file, simply use your text editor to
create the file config.inc.php in the main (top-level)
phpMyAdmin directory (the one that contains index.php).
phpMyAdmin first loads libraries/config.default.php
and then overrides those values with anything found in
config.inc.php. If the default value is okay for a particular
setting, there is no need to include it in config.inc.php.
You'll need a few directives to get going, a simple configuration
may look like this:
<?php
$cfg['blowfish_secret'] = 'ba17c1ec07d65003'; // use here a value of your choice
$i=0;
$i++;
$cfg['Servers'][$i]['auth_type'] = 'cookie';
?>
Or, if you prefer to not be prompted every time you log in:
<?php
$i=0;
$i++;
$cfg['Servers'][$i]['user'] = 'root';
$cfg['Servers'][$i]['password'] = 'cbb74bc'; // use here your password
?>
For a full explanation of possible configuration values, see the
Configuration Section of this document.
Instead of manually editing
config.inc.php, you can use the
Setup Script. First you must
manually create a folder config in the phpMyAdmin
directory. This is a security measure. On a Linux/Unix system you
can use the following commands:
cd phpMyAdmin
mkdir config # create directory for saving
chmod o+rw config # give it world writable permissions
And to edit an existing configuration, copy it over first:
cp config.inc.php config/ # copy current configuration for editing
chmod o+w config/config.inc.php # give it world writable permissions
On other platforms, simply create the folder and ensure that your
web server has read and write access to it. FAQ
1.26 can help with this.
Next, open scripts/setup.phpin your browser. Note that changes are not saved to
disk until explicitly choose Save from the
Configuration area of the screen. Normally the script saves
the new config.inc.php to the config/ directory, but if
the webserver does not have the proper permissions you may see the
error "Cannot load or save configuration." Ensure that the
config/ directory exists and has the proper permissions -
or use the Download link to save the config file locally
and upload (via FTP or some similar means) to the proper location.
Once the file has been saved, it must be moved out of the
config/ directory and the permissions must be reset, again
as a security measure:
mv config/config.inc.php . # move file to current directory
chmod o-rw config.inc.php # remove world read and write permissions
Now the file is ready to be used. You can choose to review or edit
the file with your favorite editor, if you prefer to set some
advanced options which the setup script does not provide.
If you are using the
auth_type configuration directive, it is suggested that you protect the phpMyAdmin
installation directory, for example with HTTP–AUTH in a
.htaccess file. See the
multi–user sub–section of this FAQ for additional
information, especially FAQ 4.4.
Open the main phpMyAdmin directory
in your browser. phpMyAdmin should now display a welcome screen
and your databases, or a login dialog if using
HTTP or cookie
authentication mode.
You should deny access to the libraries subfolder in your webserver
configuration. For Apache you can use supplied .htaccess file in that
folder, for other webservers, you should configure this yourself.
Such configuration prevents from possible path exposure and cross
side scripting vulnerabilities that might happen to be found in that
code.
Linked-tables infrastructure
For a whole set of new features (bookmarks, comments, SQL-history,
PDF-generation, field contents transformation, 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).
Please look at your scripts/
directory, where you should find a file called create_tables.sql.
(If you are using a Windows server, pay special attention to FAQ 1.23).
If your MySQL server's version is 4.1.2 or later, please use
create_tables_mysql_4_1_2+.sql instead, for a new installation.
If you already had this infrastructure and upgraded to MySQL 4.1.2
or later, please use upgrade_tables_mysql_4_1_2+.sql.
You can use your phpMyAdmin to create the tables for you. 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 imported the create_tables.sql file,
you should specify the table names in your config.inc.php file. The directives
used for that can be found in the Configuration section.
You will also need to have a controluser with the proper rights to
those tables (see section Using authentication modes below).
Upgrading from an older version
Simply copy ./config.inc.php from your previous installation into the newly
unpacked one. Configuration files from very old versions (2.3.0 or older) may
require some tweaking as some options have been changed or removed.
You should not copy libraries/config.default.php
over config.inc.php because the default configuration file
is version-specific.
If you have upgraded your MySQL server from a version older than 4.1.2 to
version 4.1.2 or newer and if you use the pmadb/linked table infrastructure,
you should run the SQL script found in
scripts/upgrade_tables_mysql_4_1_2+.sql.
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.
Nevertheless be aware that MS Internet Explorer seems to be really
buggy about cookies, at least till version 6. And PHP 4.1.1 is also a
bit buggy in this area!
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 phpMyAdmin
configuration file
(except possibly for the controluser).
However, keep in mind that the password travels in plain text, unless
you are using the HTTPS protocol.
In cookie mode, the password is stored, encrypted with the blowfish
algorithm, in a temporary cookie.
Note: starting with phpMyAdmin 2.6.1, this section is only applicable if
your MySQL server is older than 4.1.2,
or is running with --skip-show-database.
For 'HTTP' and 'cookie' modes, phpMyAdmin needs a controluser that has
only the SELECT privilege on the mysql.user (all
columns except "Password"), mysql.db (all
columns), mysql.host (all columns) and
mysql.tables_priv (all columns except
"Grantor" & "Timestamp") tables. You
must specify the details for the controluser
in the config.inc.php file under the
$cfg['Servers'][$i]['controluser']&
$cfg['Servers'][$i]['controlpass'] settings. The
following example assumes you want to use pma as the
controluser and pmapass as the controlpass, but this is
only an example: use something else in your file! Of course
you have to replace localhost by the webserver's host if it's
not the same as the MySQL server's one.
GRANT USAGE ON mysql.* TO 'pma'@'localhost' IDENTIFIED BY 'pmapass';
GRANT SELECT (
Host, User, Select_priv, Insert_priv, Update_priv, Delete_priv,
Create_priv, Drop_priv, Reload_priv, Shutdown_priv, Process_priv,
File_priv, Grant_priv, References_priv, Index_priv, Alter_priv,
Show_db_priv, Super_priv, Create_tmp_table_priv, Lock_tables_priv,
Execute_priv, Repl_slave_priv, Repl_client_priv
) ON mysql.user TO 'pma'@'localhost';
GRANT SELECT ON mysql.db TO 'pma'@'localhost';
GRANT SELECT ON mysql.host TO 'pma'@'localhost';
GRANT SELECT (Host, Db, User, Table_name, Table_priv, Column_priv)
ON mysql.tables_priv TO 'pma'@'localhost';
If you are using an old MySQL version (below 4.0.2), please replace
the first GRANT SELECT query by this one:
GRANT SELECT (
Host, User, Select_priv, Insert_priv, Update_priv, Delete_priv,
Create_priv, Drop_priv, Reload_priv, Shutdown_priv, Process_priv,
File_priv, Grant_priv, References_priv, Index_priv, Alter_priv
) ON mysql.user TO 'pma'@'localhost';
... and if you want to use the many new relation and bookmark
features:
GRANT SELECT, INSERT, UPDATE, DELETE ON <pma_db>.* TO 'pma'@'localhost';
(this of course requires that your linked-tables infrastructure be set up).
Of course, the above queries only work if your MySQL version supports
the GRANT command. This is the case since 3.22.11.
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'] array.
'http' authentication mode
Was called 'advanced' in versions before 2.2.3.
Introduced in 1.3.0, it uses Basic HTTP authentication method and
allows you to login as any valid MySQL user.
Is supported with most PHP configurations. For IIS (ISAPI) support
using CGI PHP see FAQ 1.32, for using with
Apache CGI see FAQ 1.35.
See also FAQ 4.4 about not using the
.htaccess mechanism along with 'http' authentication mode.
'cookie' authentication mode
You can use this method as a replacement for the HTTP
authentication (for example, if you're running IIS).
Obviously, the user must enable cookies in the browser.
With this mode, the user can truly logout of phpMyAdmin and login back
with the same username.
Warning for Mac users: PHP does not seem to like
Mac end of lines character ("\r"). So ensure you choose
the option that allows to use the *nix end of line character
("\n") in your text editor before saving a script
you have modified.
Configuration note:
Almost all configurable data is placed in config.inc.php. If this file
does not exist, please refer to the Quick install
section to create one. This file only needs to contain the parameters you want to
change from their corresponding default value in
libraries/config.default.php.
The parameters which relate to design (like colors)
are placed in themes/themename/layout.inc.php. You
might also want to create config.footer.inc.php and
config.header.inc.php files to add your site specific code to be
included on start and end of each page.
$cfg[PmaAbsoluteUri] string
Sets here the complete URL (with full path) to your phpMyAdmin
installation's directory.
E.g. http://www.your_web.net/path_to_your_phpMyAdmin_directory/.
Note also that the URL on some web servers are case–sensitive.
Don’t forget the trailing slash at the end.
Starting with version 2.3.0, it is advisable to try leaving this
blank. In most cases phpMyAdmin automatically detects the proper
setting. Users of port forwarding will need to set PmaAbsoluteUri (more info).
A good test is to browse a table, edit a row and save it. There should
be an error message if phpMyAdmin is having trouble auto–detecting the correct value. If you get an error that this must be set or if
the autodetect code fails to detect your path, please post a bug
report on our bug tracker so we can improve the code.
$cfg[PmaNoRelation_DisableWarning] boolean
Starting with version 2.3.0 phpMyAdmin offers a lot of features to work
with master / foreign - tables (see
$cfg['Servers'][$i]['pmadb']).
If you tried to set this up and it does not work for you, have a look on
the "Structure" page of one database where you would like to
use it. You will find a link that will analyze why those features have
been disabled.
If you do not want to use those features set this variable to
TRUE to stop this message from appearing.
$cfg[blowfish_secret] string
Starting with version 2.5.2, the 'cookie' auth_type uses blowfish
algorithm to encrypt the password.
If you are using the 'cookie' auth_type, enter here a random
passphrase of your choice. It will be used internally by the blowfish
algorithm: you won't be prompted for this passphrase. The maximum
number of characters for this parameter seems to be 46.
$cfg[Servers] array
Since version 1.4.2, phpMyAdmin supports the administration of multiple
MySQL servers.
Therefore, a $cfg['Servers']-array has been added which contains
the login information for the different servers. The first
$cfg['Servers'][$i]['host'] contains the hostname of the first
server, the second $cfg['Servers'][$i]['host'] the hostname of
the second server, etc.
In libraries/config.default.php, there is only one section
for server definition, however you can put as many as you need in
config.inc.php, copy that block or needed parts (you don't
have to define all settings, just those you need to change).
$cfg['Servers'][$i]['host'] string
The hostname or IP address of your $i-th MySQL-server. E.g. localhost.
$cfg['Servers'][$i]['port'] string
The port-number of your $i-th MySQL-server. Default is 3306 (leave
blank). If you use "localhost" as the hostname, MySQL
ignores this port number and connects with the socket, so if you want
to connect to a port different from the default port, use
"127.0.0.1" or the real hostname in
$cfg['Servers'][$i]['host'].
$cfg['Servers'][$i]['socket'] string
The path to the socket to use. Leave blank for default.
$cfg['Servers'][$i]['connect_type'] string
What type connection to use with the MySQL server. Your options are
'socket' & 'tcp'. It defaults to 'tcp' as that
is nearly guaranteed to be available on all MySQL servers, while
sockets are not supported on some platforms.
To use the socket mode, your MySQL server must be on the same machine
as the Web server.
$cfg['Servers'][$i]['extension'] string
What php MySQL extension to use for the connection. Valid options are:
mysql :
The classic MySQL extension. This is the recommended and default
method at this time.
mysqli :
The improved MySQL extension. This extension became available
with php 5.0.0 and is the recommended way to connect to a server
running MySQL 4.1.x.
$cfg['Servers'][$i]['compress'] boolean
Whether to use a compressed protocol for the MySQL server connection
or not (experimental).
This feature requires PHP >= 4.3.0.
This special account is used for 2 distinct purposes: to make possible
all relational features
(see $cfg['Servers'][$i]['pmadb']) and, for a
MySQL server older than 4.1.2 or running with
--skip-show-database, to enable a multi-user installation
(http or cookie authentication mode).
When using HTTP or cookie authentication modes (or 'config'
authentication mode since phpMyAdmin 2.2.1), you need to supply the
details of a MySQL account that has SELECT privilege on the
mysql.user (all columns except "Password"),
mysql.db (all columns) & mysql.tables_priv (all columns
except "Grantor" & "Timestamp") tables.
This account is used to check what databases the user will see at
login.
Please see the install section on
"Using authentication modes" for more information.
In phpMyAdmin versions before 2.2.5, those were called
"stduser/stdpass".