Migrate a PunBB forum to Discourse

In this tutorial, we will learn how to migrate PunBB forum to :discourse: platform using the official Importer script. Let’s get started :slight_smile:

What can be migrated

  • Topics & replies => topics & posts

  • Categories & Forums

    • Root category => root category
    • Child category => sub category
    • Root Forum => sub category
    • Child forum => sub category
  • Users

    • username
    • name
    • email
    • website
    • privilege status
    • location
    • joining date
    • administration status
    • banned status

Our plan is very simple, all we need:

  • Setup the local DEV ENV.

  • Exporting the production database.

  • Importing the production database to Discourse.

  • Running PunBB importer script.

Let’s get started :slightly_smiling_face:

Setup The Local DEV ENV

First of all, you need to follow one of following guides to install Discourse platform. Consult this guide if you have any problem.

Install MySQL database server;


$ brew install mysql@5.7
$ echo 'export PATH="/usr/local/opt/mysql@5.7/bin:$PATH"' >> ~/.bash_profile
$ source ~/.bash_profile

Check the service status by running:

$ brew services list

You should see something like:

mysql@5.7 started

Otherwise, run the following and re-check the status:

$ brew services start mysql@5.7

Ubuntu 18.04:

Run the following to install MySQL server:

$ sudo apt update
$ sudo apt install mysql-server -y

After finishing installing MySQL, check its status:

$ systemctl status mysql.service

If it’s not running, run the following:

$ sudo systemctl start mysql

For Windows, you can follow the installation guide

Now, our DEV ENV is ready. We will call it: Discourse server.

Exporting The Production Database

Export/Backup the production database (from PunBB production server) by running:

$ mysqldump -u USER_NAME -p DATABASE_NAME > punbb.sql
  • Copy this database dump to the Discourse server.

:bulb: You can use scp or rsync to copy the database.

Importing The Production Database to Discourse

On Discourse server, Create a new empty database. To do that we neet to use MySQL CLI:

$ mysql -u root

If your DB user has a password, you should run the following then type your password:

mysql -u root -p
mysql> CREATE DATABASE punbb;

Make sure that the database has been created successfully by running:


You should see something like:

| Database           |
| information_schema |
| mysql              |
| performance_schema |
| punbb              |

Our next step is to import the production database into this new empty database.

$ mysql -u root punbb < punbb.sql

Running PunBB Importer Script

Let’s first install the importer dependencies. From Discourse server:

$ cd ~/discourse
$ echo "gem 'mysql2', require: false" >> Gemfile
$ bundle install

Next, you should configure the script to run properly. Open script/import_scripts/punbb.rb in any editor of your choice and change. Essensially, All you need to do is providing the MySQL database information:

@client = Mysql2::Client.new(
  host: "localhost",
  username: "MYSQL_USERNAME",
  password: "MYSQL_PASSWORD",
  database: PUNBB_DB

Run the importer with a clean Discourse instance:

$ bundle exec rails db:drop
$ bundle exec rails db:create
$ bundle exec rails db:migrate
$ bundle exec ruby script/import_scripts/punbb.rb

The importer will connect to MySQL DB and migrates your PunBB DB forum to Discourse DB.

After the importer finish, start Discourse server by running:

$ bundle exec rails server

Next, start the background jobs processor to process the migrated data:

$ bundle exec sidekiq

:bulb: You can monitor sidekiq progress at this URL: http://localhost:3000/sidekiq/queues.

Next, prepare your Discourse production server by following this tutorial.

Perform a backup for local Discourse Server platform and upload it to your Discourse production server by following this tutorial.

If you have any questions about the process I am happy to help.

Happy migration :grinning: