<h1>Choosing An SQL Server<aclass="headerlink"href="#choosing-an-sql-server"title="Permalink to this headline">¶</a></h1>
<p>This page gives an overview of the supported SQL databases as well as instructions on install:</p>
<ulclass="simple">
<li><p>SQLite3 (default)</p></li>
<li><p>PostgreSQL</p></li>
<li><p>MySQL / MariaDB</p></li>
</ul>
<p>Since Evennia uses <aclass="reference external"href="https://djangoproject.com">Django</a>, most of our notes are based off of what we
know from the community and their documentation. While the information below may be useful, you can
always find the most up-to-date and “correct” information at Django’s <aclass="reference external"href="https://docs.djangoproject.com/en/dev/ref/databases/#ref-databases">Notes about supported
Databases</a> page.</p>
<sectionid="sqlite3">
<h2>SQLite3<aclass="headerlink"href="#sqlite3"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference external"href="https://sqlite.org/">SQLite3</a> is a light weight single-file database. It is our default database
and Evennia will set this up for you automatically if you give no other options. SQLite stores the
database in a single file (<codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/evennia.db3</span></code>). This means it’s very easy to reset this
database - just delete (or move) that <codeclass="docutils literal notranslate"><spanclass="pre">evennia.db3</span></code> file and run <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">migrate</span></code> again! No server
process is needed and the administrative overhead and resource consumption is tiny. It is also very
fast since it’s run in-memory. For the vast majority of Evennia installs it will probably be all
that’s ever needed.</p>
<p>SQLite will generally be much faster than MySQL/PostgreSQL but its performance comes with two
drawbacks:</p>
<ulclass="simple">
<li><p>SQLite <aclass="reference external"href="https://www.sqlite.org/faq.html#q9">ignores length constraints by design</a>; it is possible
to store very large strings and numbers in fields that technically should not accept them. This is
not something you will notice; your game will read and write them and function normally, but this
<em>can</em> create some data migration problems requiring careful thought if you do need to change
databases later.</p></li>
<li><p>SQLite can scale well to storage of millions of objects, but if you end up with a thundering herd
of users trying to access your MUD and web site at the same time, or you find yourself writing long-
running functions to update large numbers of objects on a live game, either will yield errors and
interference. SQLite does not work reliably with multiple concurrent threads or processes accessing
its records. This has to do with file-locking clashes of the database file. So for a production
server making heavy use of process- or thread pools (or when using a third-party webserver like
Apache), a proper database is a more appropriate choice.</p></li>
</ul>
<sectionid="install-of-sqlite3">
<h3>Install of SQlite3<aclass="headerlink"href="#install-of-sqlite3"title="Permalink to this headline">¶</a></h3>
<p>This is installed and configured as part of Evennia. The database file is created as
<codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/evennia.db3</span></code> when you run</p>
<p>without changing any database options. An optional requirement is the <codeclass="docutils literal notranslate"><spanclass="pre">sqlite3</span></code> client program -
this is required if you want to inspect the database data manually. A shortcut for using it with the
evennia database is <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">dbshell</span></code>. Linux users should look for the <codeclass="docutils literal notranslate"><spanclass="pre">sqlite3</span></code> package for their
distro while Mac/Windows should get the <aclass="reference external"href="https://sqlite.org/download.html">sqlite-tools package from this
page</a>.</p>
<p>To inspect the default Evennia database (once it’s been created), go to your game dir and do</p>
<p>This will bring you into the sqlite command line. Use <codeclass="docutils literal notranslate"><spanclass="pre">.help</span></code> for instructions and <codeclass="docutils literal notranslate"><spanclass="pre">.quit</span></code> to exit.
See <aclass="reference external"href="https://gist.github.com/vincent178/10889334">here</a> for a cheat-sheet of commands.</p>
</section>
</section>
<sectionid="postgresql">
<h2>PostgreSQL<aclass="headerlink"href="#postgresql"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference external"href="https://www.postgresql.org/">PostgreSQL</a> is an open-source database engine, recommended by Django.
While not as fast as SQLite for normal usage, it will scale better than SQLite, especially if your
game has an very large database and/or extensive web presence through a separate server process.</p>
<h3>Install and initial setup of PostgreSQL<aclass="headerlink"href="#install-and-initial-setup-of-postgresql"title="Permalink to this headline">¶</a></h3>
<p>First, install the posgresql server. Version <codeclass="docutils literal notranslate"><spanclass="pre">9.6</span></code> is tested with Evennia. Packages are readily
available for all distributions. You need to also get the <codeclass="docutils literal notranslate"><spanclass="pre">psql</span></code> client (this is called <codeclass="docutils literal notranslate"><spanclass="pre">postgresql-</span><spanclass="pre">client</span></code> on debian-derived systems). Windows/Mac users can <aclass="reference external"href="https://www.postgresql.org/download/">find what they need on the postgresql
download page</a>. You should be setting up a password for your
database-superuser (always called <codeclass="docutils literal notranslate"><spanclass="pre">postgres</span></code>) when you install.</p>
<p>For interaction with Evennia you need to also install <codeclass="docutils literal notranslate"><spanclass="pre">psycopg2</span></code> to your Evennia install (<codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre">psycopg2-binary</span></code> in your virtualenv). This acts as the python bridge to the database server.</p>
<p>With the <codeclass="docutils literal notranslate"><spanclass="pre">--password</span></code> argument, Postgres should prompt you for a password.
If it won’t, replace that with <codeclass="docutils literal notranslate"><spanclass="pre">-p</span><spanclass="pre">yourpassword</span></code> instead. Do not use the <codeclass="docutils literal notranslate"><spanclass="pre">-p</span></code> argument unless you
have to since the resulting command, and your password, will be logged in the shell history.</p>
</div>
<p>This will open a console to the postgres service using the psql client.</p>
<spanclass="c1">-- \l (list all databases and permissions)</span>
<spanclass="c1">-- \q (exit)</span>
</pre></div>
</div>
<p><aclass="reference external"href="https://gist.github.com/Kartones/dd3ff5ec5ea238d4c546">Here</a> is a cheat-sheet for psql commands.</p>
<p>We create a database user ‘evennia’ and a new database named <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> (you can call them whatever
you want though). We then grant the ‘evennia’ user full privileges to the new database so it can
read/write etc to it.
If you in the future wanted to completely wipe the database, an easy way to do is to log in as the
<codeclass="docutils literal notranslate"><spanclass="pre">postgres</span></code> superuser again, then do <codeclass="docutils literal notranslate"><spanclass="pre">DROP</span><spanclass="pre">DATABASE</span><spanclass="pre">evennia;</span></code>, then <codeclass="docutils literal notranslate"><spanclass="pre">CREATE</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">GRANT</span></code> steps above
again to recreate the database and grant privileges.</p>
</section>
<sectionid="evennia-postgresql-configuration">
<h3>Evennia PostgreSQL configuration<aclass="headerlink"href="#evennia-postgresql-configuration"title="Permalink to this headline">¶</a></h3>
<p>Edit `mygame/server/conf/secret_settings.py and add the following section:</p>
<h3>Advanced Postgresql Usage (Remote Server)<aclass="headerlink"href="#advanced-postgresql-usage-remote-server"title="Permalink to this headline">¶</a></h3>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>The example below is for a server within a private network that is not open to
the Internet. Be sure to understand the details before making any changes to
an Internet-accessible server.</p>
</div>
<p>The above discussion is for hosting a local server. In certain configurations
it may make sense host the database on a server remote to the one Evennia is
running on. One example case is where code development may be done on multiple
machines by multiple users. In this configuration, a local data base (such as
SQLite3) is not feasible since all the machines and developers do not have
access to the file.</p>
<p>Choose a remote machine to host the database and PostgreSQl server. Follow the
instructions <aclass="reference internal"href="#install-and-initial-setup-of-postgresql"><spanclass="std std-doc">above</span></a> on that server to set up the database.
Depending on distribution, PostgreSQL will only accept connections on the local
machine (localhost). In order to enable remote access, two files need to be
changed.</p>
<p>First, determine which cluster is running your database. Use <codeclass="docutils literal notranslate"><spanclass="pre">pg_lscluster</span></code>:</p>
Ver Cluster Port Status Owner Data directory Log file
<spanclass="m">12</span> main <spanclass="m">5432</span> online postgres /var/lib/postgresql/12/main /var/log/postgresql/postgresql-12-main.log
</pre></div>
</div>
<p>Next, edit the database’s <codeclass="docutils literal notranslate"><spanclass="pre">postgresql.conf</span></code>. This is found on Ubuntu systems
in <codeclass="docutils literal notranslate"><spanclass="pre">/etc/postgresql/<ver>/<cluster></span></code>, where <codeclass="docutils literal notranslate"><spanclass="pre"><ver></span></code> and <codeclass="docutils literal notranslate"><spanclass="pre"><cluster></span></code> are
what are reported in the <codeclass="docutils literal notranslate"><spanclass="pre">pg_lscluster</span></code> output. So, for the above example,
the file is <codeclass="docutils literal notranslate"><spanclass="pre">/etc/postgresql/12/main/postgresql.conf</span></code>.</p>
<p>In this file, look for the line with <codeclass="docutils literal notranslate"><spanclass="pre">listen_addresses</span></code>. For example:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">listen_address</span><spanclass="o">=</span><spanclass="s1">'localhost'</span><spanclass="c1"># What IP address(es) to listen on;</span>
<spanclass="c1"># comma-separated list of addresses;</span>
<spanclass="c1"># defaults to 'localhost'; use '*' for all</span>
</pre></div>
</div>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>Misconfiguring the wrong cluster may cause problems
with existing clusters.</p>
</div>
<p>Also, note the line with <codeclass="docutils literal notranslate"><spanclass="pre">port</span><spanclass="pre">=</span></code> and keep the port number in mind.</p>
<p>Set <codeclass="docutils literal notranslate"><spanclass="pre">listen_addresses</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">'*'</span></code>. This permits postgresql to accept connections
on any interface.</p>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>Setting <codeclass="docutils literal notranslate"><spanclass="pre">listen_addresses</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">'*'</span></code> opens a port on all interfaces. If your
server has access to the Internet, ensure your firewall is configured
appropriately to limit access to this port as necessary. (You may also list
explicit addresses and subnets to listen. See the postgresql documentation
for more details.)</p>
</div>
<p>Finally, modify the <codeclass="docutils literal notranslate"><spanclass="pre">pg_hba.conf</span></code> (in the same directory as <codeclass="docutils literal notranslate"><spanclass="pre">postgresql.conf</span></code>).
Look for a line with:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># IPv4 local connections:</span>
<p>This permits incoming connections from <em>all</em> IPs. See
the PosgreSQL documentation on how to limit this.</p>
</div>
<p>Now, restart your cluster:</p>
<divclass="highlight-bash notranslate"><divclass="highlight"><pre><span></span>$ pg_ctlcluster <spanclass="m">12</span> main restart
</pre></div>
</div>
<p>Finally, update the database settings in your Evennia secret_settings.py (as
described <aclass="reference internal"href="#evennia-postgresql-configuration"><spanclass="std std-doc">above</span></a> modifying <codeclass="docutils literal notranslate"><spanclass="pre">SERVER</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">PORT</span></code> to match your server.</p>
<p>Now your Evennia installation should be able to connect and talk with a remote
server.</p>
</section>
</section>
<sectionid="mysql-mariadb">
<h2>MySQL / MariaDB<aclass="headerlink"href="#mysql-mariadb"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference external"href="https://www.mysql.com/">MySQL</a> is a commonly used proprietary database system, on par with
PostgreSQL. There is an open-source alternative called <aclass="reference external"href="https://mariadb.org/">MariaDB</a> that mimics
all functionality and command syntax of the former. So this section covers both.</p>
<h3>Installing and initial setup of MySQL/MariaDB<aclass="headerlink"href="#installing-and-initial-setup-of-mysql-mariadb"title="Permalink to this headline">¶</a></h3>
<p>First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the
<codeclass="docutils literal notranslate"><spanclass="pre">mysql-server</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">mariadb-server</span></code> packages for their respective distributions. Windows/Mac users
will find what they need from the <aclass="reference external"href="https://www.mysql.com/downloads/">MySQL downloads</a> or <aclass="reference external"href="https://mariadb.org/download/">MariaDB
downloads</a> pages. You also need the respective database clients
(<codeclass="docutils literal notranslate"><spanclass="pre">mysql</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">mariadb-client</span></code>), so you can setup the database itself. When you install the server you
should usually be asked to set up the database root user and password.</p>
<p>You will finally also need a Python interface to allow Evennia to talk to the database. Django
recommends the <codeclass="docutils literal notranslate"><spanclass="pre">mysqlclient</span></code> one. Install this into the evennia virtualenv with <codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre">mysqlclient</span></code>.</p>
<p>Start the database client (this is named the same for both mysql and mariadb):</p>
<spanclass="k">ALTER</span><spanclass="w"></span><spanclass="k">DATABASE</span><spanclass="w"></span><spanclass="o">`</span><spanclass="n">evennia</span><spanclass="o">`</span><spanclass="w"></span><spanclass="nb">CHARACTER</span><spanclass="w"></span><spanclass="k">SET</span><spanclass="w"></span><spanclass="n">utf8</span><spanclass="p">;</span><spanclass="w"></span><spanclass="c1">-- note that it's `evennia` with back-ticks, not</span>
<spanclass="c1">-- use 'exit' to quit client</span>
</pre></div>
</div>
<p><aclass="reference external"href="https://gist.github.com/hofmannsven/9164408">Here</a> is a mysql command cheat sheet.</p>
<p>Above we created a new local user and database (we called both ‘evennia’ here, you can name them
what you prefer). We set the character set to <codeclass="docutils literal notranslate"><spanclass="pre">utf8</span></code> to avoid an issue with prefix character length
that can pop up on some installs otherwise. Next we grant the ‘evennia’ user all privileges on the
<codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> database and make sure the privileges are applied. Exiting the client brings us back to
the normal terminal/console.</p>
<blockquote>
<div><p>Note: If you are not using MySQL for anything else you might consider granting the ‘evennia’ user
full privileges with <codeclass="docutils literal notranslate"><spanclass="pre">GRANT</span><spanclass="pre">ALL</span><spanclass="pre">PRIVILEGES</span><spanclass="pre">ON</span><spanclass="pre">*.*</span><spanclass="pre">TO</span><spanclass="pre">'evennia'@'localhost';</span></code>. If you do, it means
you can use <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">dbshell</span></code> later to connect to mysql, drop your database and re-create it as a
way of easy reset. Without this extra privilege you will be able to drop the database but not re-
create it without first switching to the database-root user.</p>
</div></blockquote>
</section>
</section>
<sectionid="add-mysql-configuration-to-evennia">
<h2>Add MySQL configuration to Evennia<aclass="headerlink"href="#add-mysql-configuration-to-evennia"title="Permalink to this headline">¶</a></h2>
<p>To tell Evennia to use your new database you need to edit <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/conf/settings.py</span></code> (or
<codeclass="docutils literal notranslate"><spanclass="pre">secret_settings.py</span></code> if you don’t want your db info passed around on git repositories).</p>
<blockquote>
<div><p>Note: The Django documentation suggests using an external <codeclass="docutils literal notranslate"><spanclass="pre">db.cnf</span></code> or other external conf-
formatted file. Evennia users have however found that this leads to problems (see e.g. <aclass="reference external"href="https://git.io/vQdiN">issue
#1184</a>). To avoid trouble we recommend you simply put the configuration in
<spanclass="s1">'HOST'</span><spanclass="p">:</span><spanclass="s1">'localhost'</span><spanclass="p">,</span><spanclass="c1"># or an IP Address that your DB is hosted on</span>
<spanclass="s1">'PORT'</span><spanclass="p">:</span><spanclass="s1">''</span><spanclass="p">,</span><spanclass="c1"># use default port</span>
<spanclass="p">}</span>
<spanclass="p">}</span>
</pre></div>
</div>
<p>Change this to fit your database setup. Next, run:</p>
