This is the documentation for CDH 5.1.x. Documentation for other versions is available at Cloudera Documentation.

Hue Database

The Hue server requires an SQL database to store small amounts of data, including user account information as well as history of job submissions and Hive queries. The Hue server supports a lightweight embedded database and several types of external databases. If you elect to configure Hue to use an external database, upgrades may require more manual steps.

Embedded Database

By default, Hue is configured to use the embedded database SQLite for this purpose, and should require no configuration or management by the administrator.

Inspecting the Embedded Hue Database

The default SQLite database used by Hue is located in /var/lib/hue/desktop.db. You can inspect this database from the command line using the sqlite3 program. For example: 

# sqlite3 /var/lib/hue/desktop.db
SQLite version 3.6.22
Enter ".help" for instructions
Enter SQL statements terminated with a ";"
sqlite> select username from auth_user;
admin
test
sample
sqlite>
  Important: It is strongly recommended that you avoid making any modifications to the database directly using sqlite3, though sqlite3 is useful for management or troubleshooting.

Backing up the Embedded Hue Database

If you use the default embedded SQLite database, copy the desktop.db file to another node for backup. It is recommended that you back it up on a regular schedule, and also that you back it up before any upgrade to a new version of Hue.

External Database

Although SQLite is the default database, some advanced users may prefer to have Hue access an external database. Hue supports MySQL, PostgreSQL, and Oracle. See Supported Databases for the supported versions.

  Note: In the instructions that follow, dumping the database and editing the JSON objects is only necessary if you have data in SQLite that you need to migrate. If you don't need to migrate data from SQLite, you can skip those steps.

Configuring the Hue Server to Store Data in MySQL

  1. Shut down the Hue server if it is running.
  2. Dump the existing database data to a text file. Note that using the .json extension is required. 
    $ sudo -u hue <HUE_HOME>/build/env/bin/hue dumpdata > <some-temporary-file>.json
  3. Open <some-temporary-file>.json and remove all JSON objects with useradmin.userprofile in the model field.
  4. Start the Hue server.
  5. Install the MySQL client developer package.
    OS Command

    RHEL 

    $ sudo yum install mysql-devel

    SLES 

    $ sudo zypper install mysql-devel

    Ubuntu or Debian 

    $ sudo apt-get install libmysqlclient-dev
  6. Install the MySQL connector.
    OS Command

    RHEL

    		 
    $ sudo yum install mysql-connector-java

    SLES 

    $ sudo zypper install mysql-connector-java

    Ubuntu or Debian 

    $ sudo apt-get install libmysql-java
  7. Install and start MySQL.
    OS Command

    RHEL 

    $ sudo yum install mysql-server

    SLES 

    $ sudo zypper install mysql
$ sudo zypper install libmysqlclient_r15

    Ubuntu or Debian 

    $ sudo apt-get install mysql-server
  8. Change the /etc/my.cnf file as follows: 
    [mysqld]
datadir=/var/lib/mysql
socket=/var/lib/mysql/mysql.sock
bind-address=<ip-address>
default-storage-engine=MyISAM
  9. Start the mysql daemon.
    OS Command

    RHEL 

    $ sudo service mysqld start

    SLES and Ubuntu or Debian 

    $ sudo service mysql start
  10. Configure MySQL to use a strong password. In the following procedure, your current root password is blank. Press the Enter key when you're prompted for the root password. 
    $ sudo /usr/bin/mysql_secure_installation
[...]
Enter current password for root (enter for none):
OK, successfully used password, moving on...
[...]
Set root password? [Y/n] y
New password:
Re-enter new password:
Remove anonymous users? [Y/n] Y
[...]
Disallow root login remotely? [Y/n] N
[...]
Remove test database and access to it [Y/n] Y
[...]
Reload privilege tables now? [Y/n] Y
All done!
  11. Configure MySQL to start at boot.
    OS Command

    RHEL 

    $ sudo /sbin/chkconfig mysqld on
$ sudo /sbin/chkconfig --list mysqld
mysqld          0:off   1:off   2:on    3:on    4:on    5:on    6:off

    SLES 

    $ sudo chkconfig --add mysql

    Ubuntu or Debian 

    $ sudo chkconfig mysql on
  12. Create the Hue database and grant privileges to a hue user to manage the database. 
    mysql> create database hue;
Query OK, 1 row affected (0.01 sec)
mysql> grant all on hue.* to 'hue'@'localhost' identified by '<secretpassword>';
Query OK, 0 rows affected (0.00 sec)
  13. Open the Hue configuration file in a text editor.
  14. Directly below the [[database]] section under the [desktop] line, add the following options (and modify accordingly for your MySQL setup): 
    host=localhost
port=3306
engine=mysql
user=hue
password=<secretpassword>
name=hue
  15. As the hue user, load the existing data and create the necessary database tables using syncdb and migrate. 
    $ sudo -u hue <HUE_HOME>/build/env/bin/hue syncdb --noinput
$ sudo -u hue <HUE_HOME>/build/env/bin/hue migrate
$ mysql -uhue -p<secretpassword>
mysql > SHOW CREATE TABLE auth_permission;
  16. (InnoDB only) Drop the foreign key. 
    mysql > ALTER TABLE auth_permission DROP FOREIGN KEY content_type_id_refs_id_XXXXXX;
  17. Delete the rows in the django_content_type table. 
    mysql > DELETE FROM hue.django_content_type;
  18. Load the data. 
    $ <HUE_HOME>/build/env/bin/hue loaddata <some-temporary-file>.json
  19. (InnoDB only) Add the foreign key. 
    $ mysql -uhue -p<secretpassword>
mysql > ALTER TABLE auth_permission ADD FOREIGN KEY (`content_type_id`) REFERENCES `django_content_type` (`id`);

Configuring the Hue Server to Store Data in PostgreSQL

  Warning: Hue requires PostgreSQL 8.4 or newer.
  1. Shut down the Hue server if it is running.
  2. Dump the existing database data to a text file. Note that using the .json extension is required. 
    $ sudo -u hue <HUE_HOME>/build/env/bin/hue dumpdata > <some-temporary-file>.json
  3. Open <some-temporary-file>.json and remove all JSON objects with useradmin.userprofile in the model field.
  4. Install required packages.
    OS Command

    RHEL 

    $ sudo yum install postgresql-devel gcc python-devel

    SLES 

    $ sudo zypper install postgresql-devel gcc python-devel

    Ubuntu or Debian 

    $ sudo apt-get install postgresql-devel gcc python-devel
  5. Install the module that provides the connector to PostgreSQL. 
    sudo -u hue <HUE_HOME>/build/env/bin/pip install setuptools
sudo -u hue <HUE_HOME>/build/env/bin/pip install psycopg2
  6. Install the PostgreSQL server.
    OS Command

    RHEL

    		 
    $ sudo yum install postgresql-server

    SLES 

    $ sudo zypper install postgresql-server

    Ubuntu or Debian 

    $ sudo apt-get install postgresql
  7. Initialize the data directories: 
    $ service postgresql initdb
  8. Configure client authentication.
    1. Edit /var/lib/pgsql/data/pg_hba.conf.
    2. Set the authentication methods for local to trust and for host to password and add the following line at the end. 
      host	hue	hue	0.0.0.0/0	md5
  9. Start the PostgreSQL server. 
    $ su - postgres
# /usr/bin/postgres -D /var/lib/pgsql/data > logfile 2>&1 &
  10. Configure PostgreSQL to listen on all network interfaces.
    Edit /var/lib/pgsql/data/postgresql.conf and set list_addresses: 
    listen_addresses = ‘0.0.0.0’     # Listen on all addresses
  11. Create the hue database and grant privileges to a hue user to manage the database. 
    # psql -U postgres
postgres=# create database hue;
postgres=# \c hue;
You are now connected to database 'hue'.
postgres=# create user hue with password '<secretpassword>';
postgres=# grant all privileges on database hue to hue;
postgres=# \q
  12. Restart the PostgreSQL server. 
    $ sudo service postgresql restart
  13. Verify connectivity. 
    psql –h localhost –U hue –d hue
Password for user hue: <secretpassword>
  14. Configure the PostgreSQL server to start at boot.
    OS Command

    RHEL 

    $ sudo /sbin/chkconfig postgresql on
$ sudo /sbin/chkconfig --list postgresql
postgresql          0:off   1:off   2:on    3:on    4:on    5:on    6:off

    SLES 

    $ sudo chkconfig --add postgresql

    Ubuntu or Debian 

    $ sudo chkconfig postgresql on
  15. Open the Hue configuration file in a text editor.
  16. Directly below the [[database]] section under the [desktop] line, add the following options (and modify accordingly for your PostgreSQL setup). 
    host=localhost
port=5432
engine=postgresql_psycopg2
user=hue
password=<secretpassword>
name=hue
  17. As the hue user, configure Hue to load the existing data and create the necessary database tables. You will need to run both the migrate and syncdb commands. 
    $ sudo -u hue <HUE_HOME>/build/env/bin/hue syncdb --noinput
$ sudo -u hue <HUE_HOME>/build/env/bin/hue migrate
  18. Determine the foreign key ID. 
    bash# su – postgres
$ psql –h localhost –U hue –d hue
postgres=# \d auth_permission;
  19. Drop the foreign key that you retrieved in the previous step. 
    postgres=# ALTER TABLE auth_permission DROP CONSTRAINT content_type_id_refs_id_<XXXXXX>;
  20. Delete the rows in the django_content_type table.
    postgres=# TRUNCATE django_content_type CASCADE;
  21. Load the data. 
    $ sudo -u hue <HUE_HOME>/build/env/bin/hue loaddata <some-temporary-file>.json
  22. Add back the foreign key you dropped. 
    bash# su – postgres
$ psql –h localhost –U hue –d hue
postgres=# ALTER TABLE auth_permission ADD CONSTRAINT content_type_id_refs_id_<XXXXXX> FOREIGN KEY (content_type_id) REFERENCES django_content_type(id) DEFERRABLE INITIALLY DEFERRED;

Configuring the Hue Server to Store Data in Oracle

  1. Ensure Python 2.6 or newer is installed on the server Hue is running on.
  2. Download the Oracle client libraries at Instant Client for Linux x86-64 Version 11.1.0.7.0, Basic and SDK (with headers) zip files to the same directory.
  3. Unzip the zip files.
  4. Set environment variables to reference the libraries.
    $ export ORACLE_HOME=<download directory>
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME
  5. Create a symbolic link for the shared object: 
    $ cd $ORACLE_HOME
$ ln -sf libclntsh.so.11.1 libclntsh.so
  6. Install the Python Oracle library.
    $ <HUE_HOME>/build/env/bin/pip install cx_Oracle
  7. Upgrade django south.
    $ <HUE_HOME>/build/env/bin/pip install south --upgrade
  8. Get a data dump by executing: 
    $ <HUE_HOME>/build/env/bin/hue dumpdata > <some-temporary-file>.json --indent 2
  9. Open the Hue configuration file in a text editor.
  10. Directly below the [[database]] section under the [desktop] line, add the following options (and modify accordingly for your Oracle setup): 
    host=localhost
port=1521
engine=oracle
user=hue
password=<secretpassword>
name=<SID of the Oracle database, for example, 'XE'>

    To add support for a multithreaded environment, set the threaded option to true under the [desktop]>[[database]] section.

    options={'threaded':true}
  11. As the hue user, configure Hue to load the existing data and create the necessary database tables. You will need to run both the syncdb and migrate commands.
    $ sudo -u hue <HUE_HOME>/build/env/bin/hue syncdb --noinput
$ sudo -u hue <HUE_HOME>/build/env/bin/hue migrate
  12. Generate statements to delete all data from Oracle tables:
    > SELECT 'DELETE FROM ' || '.' || table_name || ';' FROM user_tables;
  13. Run the statements generated in the preceding step.
  14. Load the data. 
    $ sudo -u hue <HUE_HOME>/build/env/bin/hue loaddata <some-temporary-file>.json
Page generated September 3, 2015.