mirror of
https://github.com/evennia/evennia.git
synced 2026-03-18 05:46:31 +01:00
416 lines
No EOL
38 KiB
HTML
416 lines
No EOL
38 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>Choosing a database — Evennia latest documentation</title>
|
||
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<link rel="shortcut icon" href="../_static/favicon.ico"/>
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="next" title="Connect Evennia channels to Discord" href="Channels-to-Discord.html" />
|
||
<link rel="prev" title="Evennia Default settings file" href="Settings-Default.html" />
|
||
</head><body>
|
||
|
||
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="Channels-to-Discord.html" title="Connect Evennia channels to Discord"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="Settings-Default.html" title="Evennia Default settings file"
|
||
accesskey="P">previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../index.html">Evennia latest</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Choosing a database</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
|
||
<div class="documentwrapper">
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<p class="logo"><a href="../index.html">
|
||
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
|
||
</a></p>
|
||
<div id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="../search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</div>
|
||
<script>$('#searchbox').show(0);</script>
|
||
<h3><a href="../index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Choosing a database</a><ul>
|
||
<li><a class="reference internal" href="#sqlite3-default">SQLite3 (default)</a><ul>
|
||
<li><a class="reference internal" href="#install-of-sqlite3">Install of SQlite3</a></li>
|
||
<li><a class="reference internal" href="#resetting-sqlite3">Resetting SQLite3</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#postgresql">PostgreSQL</a><ul>
|
||
<li><a class="reference internal" href="#install-and-initial-setup-of-postgresql">Install and initial setup of PostgreSQL</a></li>
|
||
<li><a class="reference internal" href="#evennia-postgresql-configuration">Evennia PostgreSQL configuration</a></li>
|
||
<li><a class="reference internal" href="#resetting-postgresql">Resetting PostgreSQL</a></li>
|
||
<li><a class="reference internal" href="#advanced-postgresql-usage-remote-server">Advanced PostgreSQL Usage (Remote Server)</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#mysql-mariadb">MySQL / MariaDB</a><ul>
|
||
<li><a class="reference internal" href="#installing-and-initial-setup-of-mysql-mariadb">Installing and initial setup of MySQL/MariaDB</a></li>
|
||
<li><a class="reference internal" href="#add-mysql-mariadb-configuration-to-evennia">Add MySQL/MariaDB configuration to Evennia</a></li>
|
||
<li><a class="reference internal" href="#resetting-mysql-mariadb">Resetting MySQL/MariaDB</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#other-databases">Other databases</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="Settings-Default.html"
|
||
title="previous chapter">Evennia Default settings file</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="Channels-to-Discord.html"
|
||
title="next chapter">Connect Evennia channels to Discord</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<!--h3>This Page</h3-->
|
||
<ul class="this-page-menu">
|
||
<li><a href="../_sources/Setup/Choosing-a-Database.md.txt"
|
||
rel="nofollow">Show Page Source</a></li>
|
||
</ul>
|
||
</div><h3>Links</h3>
|
||
<ul>
|
||
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
|
||
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
|
||
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
|
||
<li><a href="http://games.evennia.com">Game Index</a> </li>
|
||
<li>
|
||
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
|
||
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
|
||
<a href="https://evennia.blogspot.com/">Blog</a>
|
||
</li>
|
||
</ul>
|
||
<h3>Doc Versions</h3>
|
||
<ul>
|
||
|
||
<li><a href="Choosing-a-Database.html">latest (main branch)</a></li>
|
||
|
||
<li><a href="../4.x/index.html">v4.0.0 branch (outdated)</a></li>
|
||
|
||
<li><a href="../3.x/index.html">v3.0.0 branch (outdated)</a></li>
|
||
|
||
<li><a href="../2.x/index.html">v2.0.0 branch (outdated)</a></li>
|
||
|
||
<li><a href="../1.x/index.html">v1.0.0 branch (outdated)</a></li>
|
||
|
||
<li><a href="../0.x/index.html">v0.9.5 branch (outdated)</a></li>
|
||
|
||
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section class="tex2jax_ignore mathjax_ignore" id="choosing-a-database">
|
||
<h1>Choosing a database<a class="headerlink" href="#choosing-a-database" 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>
|
||
<ul class="simple">
|
||
<li><p>SQLite3 (default)</p></li>
|
||
<li><p>PostgreSQL</p></li>
|
||
<li><p>MySQL / MariaDB</p></li>
|
||
</ul>
|
||
<p>Since Evennia uses <a class="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 <a class="reference external" href="https://docs.djangoproject.com/en/4.1/ref/databases/#ref-databases">Notes about supported Databases</a> page.</p>
|
||
<section id="sqlite3-default">
|
||
<h2>SQLite3 (default)<a class="headerlink" href="#sqlite3-default" title="Permalink to this headline">¶</a></h2>
|
||
<p><a class="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.</p>
|
||
<p>SQLite stores the database in a single file (<code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>). This means it’s very easy to reset this database - just delete (or move) that <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code> file and run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="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>
|
||
<ul class="simple">
|
||
<li><p>SQLite <a class="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, a proper database is a more appropriate choice.</p></li>
|
||
</ul>
|
||
<section id="install-of-sqlite3">
|
||
<h3>Install of SQlite3<a class="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 <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code> when you run</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
|
||
</pre></div>
|
||
</div>
|
||
<p>without changing any database options. An optional requirement is the <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">dbshell</span></code>. Linux users should look for the <code class="docutils literal notranslate"><span class="pre">sqlite3</span></code> package for their distro while Mac/Windows should get the <a class="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>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="w"> </span>sqlite3<span class="w"> </span>server/evennia.db3
|
||
<span class="w"> </span><span class="c1"># or</span>
|
||
<span class="w"> </span>evennia<span class="w"> </span>dbshell
|
||
</pre></div>
|
||
</div>
|
||
<p>This will bring you into the sqlite command line. Use <code class="docutils literal notranslate"><span class="pre">.help</span></code> for instructions and <code class="docutils literal notranslate"><span class="pre">.quit</span></code> to exit.
|
||
See <a class="reference external" href="https://gist.github.com/vincent178/10889334">here</a> for a cheat-sheet of commands.</p>
|
||
</section>
|
||
<section id="resetting-sqlite3">
|
||
<h3>Resetting SQLite3<a class="headerlink" href="#resetting-sqlite3" title="Permalink to this headline">¶</a></h3>
|
||
<p>If you want to reset your SQLite3 database, see <a class="reference internal" href="Updating-Evennia.html#sqlite3-default"><span class="std std-doc">here</span></a>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="postgresql">
|
||
<h2>PostgreSQL<a class="headerlink" href="#postgresql" title="Permalink to this headline">¶</a></h2>
|
||
<p><a class="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>
|
||
<section id="install-and-initial-setup-of-postgresql">
|
||
<h3>Install and initial setup of PostgreSQL<a class="headerlink" href="#install-and-initial-setup-of-postgresql" title="Permalink to this headline">¶</a></h3>
|
||
<p>First, install the posgresql server. Version <code class="docutils literal notranslate"><span class="pre">9.6</span></code> is tested with Evennia. Packages are readily available for all distributions. You need to also get the <code class="docutils literal notranslate"><span class="pre">psql</span></code> client (this is called <code class="docutils literal notranslate"><span class="pre">postgresql-</span> <span class="pre">client</span></code> on debian-derived systems). Windows/Mac users can <a class="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 <code class="docutils literal notranslate"><span class="pre">postgres</span></code>) when you install.</p>
|
||
<p>For interaction with Evennia you need to also install <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code> to your Evennia install
|
||
(<code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">psycopg2-binary</span></code> in your virtualenv). This acts as the python bridge to the database server.</p>
|
||
<p>Next, start the postgres client:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="w"> </span>psql<span class="w"> </span>-U<span class="w"> </span>postgres<span class="w"> </span>--password
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>With the <code class="docutils literal notranslate"><span class="pre">--password</span></code> argument, Postgres should prompt you for a password. If it won’t, replace that with <code class="docutils literal notranslate"><span class="pre">-p</span> <span class="pre">yourpassword</span></code> instead. Do not use the <code class="docutils literal notranslate"><span class="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>
|
||
<p>On the psql command line:</p>
|
||
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">CREATE</span><span class="w"> </span><span class="k">USER</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">WITH</span><span class="w"> </span><span class="n">PASSWORD</span><span class="w"> </span><span class="s1">'somepassword'</span><span class="p">;</span>
|
||
<span class="k">CREATE</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">evennia</span><span class="p">;</span>
|
||
|
||
<span class="c1">-- Postgres-specific optimizations</span>
|
||
<span class="c1">-- https://docs.djangoproject.com/en/dev/ref/databases/#optimizing-postgresql-s-configuration</span>
|
||
<span class="k">ALTER</span><span class="w"> </span><span class="k">ROLE</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="n">client_encoding</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="s1">'utf8'</span><span class="p">;</span>
|
||
<span class="k">ALTER</span><span class="w"> </span><span class="k">ROLE</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="n">default_transaction_isolation</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="s1">'read committed'</span><span class="p">;</span>
|
||
<span class="k">ALTER</span><span class="w"> </span><span class="k">ROLE</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="n">timezone</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="s1">'UTC'</span><span class="p">;</span>
|
||
|
||
<span class="k">GRANT</span><span class="w"> </span><span class="k">ALL</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="n">evennia</span><span class="p">;</span>
|
||
<span class="c1">-- For Postgres 10+</span>
|
||
<span class="k">ALTER</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">owner</span><span class="w"> </span><span class="k">to</span><span class="w"> </span><span class="n">evennia</span><span class="p">;</span>
|
||
|
||
<span class="c1">-- Other useful commands:</span>
|
||
<span class="c1">-- \l (list all databases and permissions)</span>
|
||
<span class="c1">-- \q (exit)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="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 <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">postgres</span></code> superuser again, then do <code class="docutils literal notranslate"><span class="pre">DROP</span> <span class="pre">DATABASE</span> <span class="pre">evennia;</span></code>, then <code class="docutils literal notranslate"><span class="pre">CREATE</span></code> and <code class="docutils literal notranslate"><span class="pre">GRANT</span></code> steps above again to recreate the database and grant privileges.</p>
|
||
</section>
|
||
<section id="evennia-postgresql-configuration">
|
||
<h3>Evennia PostgreSQL configuration<a class="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>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1">#</span>
|
||
<span class="c1"># PostgreSQL Database Configuration</span>
|
||
<span class="c1">#</span>
|
||
<span class="n">DATABASES</span> <span class="o">=</span> <span class="p">{</span>
|
||
<span class="s1">'default'</span><span class="p">:</span> <span class="p">{</span>
|
||
<span class="s1">'ENGINE'</span><span class="p">:</span> <span class="s1">'django.db.backends.postgresql_psycopg2'</span><span class="p">,</span>
|
||
<span class="s1">'NAME'</span><span class="p">:</span> <span class="s1">'evennia'</span><span class="p">,</span>
|
||
<span class="s1">'USER'</span><span class="p">:</span> <span class="s1">'evennia'</span><span class="p">,</span>
|
||
<span class="s1">'PASSWORD'</span><span class="p">:</span> <span class="s1">'somepassword'</span><span class="p">,</span>
|
||
<span class="s1">'HOST'</span><span class="p">:</span> <span class="s1">'localhost'</span><span class="p">,</span>
|
||
<span class="s1">'PORT'</span><span class="p">:</span> <span class="s1">''</span> <span class="c1"># use default</span>
|
||
<span class="p">}}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If you used some other name for the database and user, enter those instead. Run</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
|
||
</pre></div>
|
||
</div>
|
||
<p>to populate your database. Should you ever want to inspect the database directly you can from now on also use</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia dbshell
|
||
</pre></div>
|
||
</div>
|
||
<p>as a shortcut to get into the postgres command line for the right database and user.</p>
|
||
<p>With the database setup you should now be able to start start Evennia normally with your new database.</p>
|
||
</section>
|
||
<section id="resetting-postgresql">
|
||
<h3>Resetting PostgreSQL<a class="headerlink" href="#resetting-postgresql" title="Permalink to this headline">¶</a></h3>
|
||
<p>If you want to reset your PostgreSQL datbase, see <a class="reference internal" href="Updating-Evennia.html#postgresql"><span class="std std-doc">here</span></a></p>
|
||
</section>
|
||
<section id="advanced-postgresql-usage-remote-server">
|
||
<h3>Advanced PostgreSQL Usage (Remote Server)<a class="headerlink" href="#advanced-postgresql-usage-remote-server" title="Permalink to this headline">¶</a></h3>
|
||
<div class="admonition warning">
|
||
<p class="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 <a class="reference internal" href="#install-and-initial-setup-of-postgresql"><span class="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 <code class="docutils literal notranslate"><span class="pre">pg_lscluster</span></code>:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>pg_lsclusters
|
||
Ver<span class="w"> </span>Cluster<span class="w"> </span>Port<span class="w"> </span>Status<span class="w"> </span>Owner<span class="w"> </span>Data<span class="w"> </span>directory<span class="w"> </span>Log<span class="w"> </span>file
|
||
<span class="m">12</span><span class="w"> </span>main<span class="w"> </span><span class="m">5432</span><span class="w"> </span>online<span class="w"> </span>postgres<span class="w"> </span>/var/lib/postgresql/12/main<span class="w"> </span>/var/log/postgresql/postgresql-12-main.log
|
||
</pre></div>
|
||
</div>
|
||
<p>Next, edit the database’s <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code>. This is found on Ubuntu systems in <code class="docutils literal notranslate"><span class="pre">/etc/postgresql/<ver>/<cluster></span></code>, where <code class="docutils literal notranslate"><span class="pre"><ver></span></code> and <code class="docutils literal notranslate"><span class="pre"><cluster></span></code> are what are reported in the <code class="docutils literal notranslate"><span class="pre">pg_lscluster</span></code> output. So, for the above example, the file is <code class="docutils literal notranslate"><span class="pre">/etc/postgresql/12/main/postgresql.conf</span></code>.</p>
|
||
<p>In this file, look for the line with <code class="docutils literal notranslate"><span class="pre">listen_addresses</span></code>. For example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">listen_address</span> <span class="o">=</span> <span class="s1">'localhost'</span> <span class="c1"># What IP address(es) to listen on;</span>
|
||
<span class="c1"># comma-separated list of addresses;</span>
|
||
<span class="c1"># defaults to 'localhost'; use '*' for all</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Misconfiguring the wrong cluster may cause problems
|
||
with existing clusters.</p>
|
||
</div>
|
||
<p>Also, note the line with <code class="docutils literal notranslate"><span class="pre">port</span> <span class="pre">=</span></code> and keep the port number in mind.</p>
|
||
<p>Set <code class="docutils literal notranslate"><span class="pre">listen_addresses</span></code> to <code class="docutils literal notranslate"><span class="pre">'*'</span></code>. This permits postgresql to accept connections
|
||
on any interface.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Setting <code class="docutils literal notranslate"><span class="pre">listen_addresses</span></code> to <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">pg_hba.conf</span></code> (in the same directory as <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code>). Look for a line with:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># IPv4 local connections:</span>
|
||
<span class="n">host</span> <span class="nb">all</span> <span class="nb">all</span> <span class="mf">127.0.0.1</span><span class="o">/</span><span class="mi">32</span> <span class="n">md5</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Add a line with:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">host</span> <span class="nb">all</span> <span class="nb">all</span> <span class="mf">0.0.0.0</span><span class="o">/</span><span class="mi">0</span> <span class="n">md5</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<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>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>pg_ctlcluster<span class="w"> </span><span class="m">12</span><span class="w"> </span>main<span class="w"> </span>restart
|
||
</pre></div>
|
||
</div>
|
||
<p>Finally, update the database settings in your Evennia secret_settings.py (as described <a class="reference internal" href="#evennia-postgresql-configuration"><span class="std std-doc">above</span></a> modifying <code class="docutils literal notranslate"><span class="pre">SERVER</span></code> and <code class="docutils literal notranslate"><span class="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>
|
||
<section id="mysql-mariadb">
|
||
<h2>MySQL / MariaDB<a class="headerlink" href="#mysql-mariadb" title="Permalink to this headline">¶</a></h2>
|
||
<p><a class="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 <a class="reference external" href="https://mariadb.org/">MariaDB</a> that mimics all functionality and command syntax of the former. So this section covers both.</p>
|
||
<section id="installing-and-initial-setup-of-mysql-mariadb">
|
||
<h3>Installing and initial setup of MySQL/MariaDB<a class="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 <code class="docutils literal notranslate"><span class="pre">mysql-server</span></code> or <code class="docutils literal notranslate"><span class="pre">mariadb-server</span></code> packages for their respective distributions. Windows/Mac users will find what they need from the <a class="reference external" href="https://www.mysql.com/downloads/">MySQL downloads</a> or <a class="reference external" href="https://mariadb.org/download/">MariaDB downloads</a> pages. You also need the respective database clients (<code class="docutils literal notranslate"><span class="pre">mysql</span></code>, <code class="docutils literal notranslate"><span class="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>Finally, you will also need a Python interface to allow Evennia to talk to the database. Django recommends the <code class="docutils literal notranslate"><span class="pre">mysqlclient</span></code> one. Install this into the evennia virtualenv with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">mysqlclient</span></code>.</p>
|
||
<p>Start the database client (this is named the same for both mysql and mariadb):</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mysql<span class="w"> </span>-u<span class="w"> </span>root<span class="w"> </span>-p
|
||
</pre></div>
|
||
</div>
|
||
<p>You should get to enter your database root password (set this up when you installed the database server).</p>
|
||
<p>Inside the database client interface:</p>
|
||
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">CREATE</span><span class="w"> </span><span class="k">USER</span><span class="w"> </span><span class="s1">'evennia'</span><span class="o">@</span><span class="s1">'localhost'</span><span class="w"> </span><span class="n">IDENTIFIED</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="s1">'somepassword'</span><span class="p">;</span>
|
||
<span class="k">CREATE</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">evennia</span><span class="p">;</span>
|
||
<span class="k">ALTER</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="o">`</span><span class="n">evennia</span><span class="o">`</span><span class="w"> </span><span class="nb">CHARACTER</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="n">utf8</span><span class="p">;</span><span class="w"> </span><span class="c1">-- note that it's `evennia` with back-ticks, not</span>
|
||
<span class="n">quotes</span><span class="o">!</span>
|
||
<span class="k">GRANT</span><span class="w"> </span><span class="k">ALL</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="n">evennia</span><span class="p">.</span><span class="o">*</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="s1">'evennia'</span><span class="o">@</span><span class="s1">'localhost'</span><span class="p">;</span>
|
||
<span class="n">FLUSH</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="p">;</span>
|
||
<span class="c1">-- use 'exit' to quit client</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="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 <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="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>If you are not using MySQL for anything else you might consider granting the ‘evennia’ user full privileges with <code class="docutils literal notranslate"><span class="pre">GRANT</span> <span class="pre">ALL</span> <span class="pre">PRIVILEGES</span> <span class="pre">ON</span> <span class="pre">*.*</span> <span class="pre">TO</span> <span class="pre">'evennia'@'localhost';</span></code>. If you do, it means you can use <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="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 id="add-mysql-mariadb-configuration-to-evennia">
|
||
<h3>Add MySQL/MariaDB configuration to Evennia<a class="headerlink" href="#add-mysql-mariadb-configuration-to-evennia" title="Permalink to this headline">¶</a></h3>
|
||
<p>To tell Evennia to use your new database you need to edit <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code> (or <code class="docutils literal notranslate"><span class="pre">secret_settings.py</span></code> if you don’t want your db info passed around on git repositories).</p>
|
||
<blockquote>
|
||
<div><p>The Django documentation suggests using an external <code class="docutils literal notranslate"><span class="pre">db.cnf</span></code> or other external conf- formatted file. Evennia users have however found that this leads to problems (see e.g. <a class="reference external" href="https://git.io/vQdiN">issue #1184</a>). To avoid trouble we recommend you simply put the configuration in your settings as below.</p>
|
||
</div></blockquote>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="c1">#</span>
|
||
<span class="c1"># MySQL Database Configuration</span>
|
||
<span class="c1">#</span>
|
||
<span class="n">DATABASES</span> <span class="o">=</span> <span class="p">{</span>
|
||
<span class="s1">'default'</span><span class="p">:</span> <span class="p">{</span>
|
||
<span class="s1">'ENGINE'</span><span class="p">:</span> <span class="s1">'django.db.backends.mysql'</span><span class="p">,</span>
|
||
<span class="s1">'NAME'</span><span class="p">:</span> <span class="s1">'evennia'</span><span class="p">,</span>
|
||
<span class="s1">'USER'</span><span class="p">:</span> <span class="s1">'evennia'</span><span class="p">,</span>
|
||
<span class="s1">'PASSWORD'</span><span class="p">:</span> <span class="s1">'somepassword'</span><span class="p">,</span>
|
||
<span class="s1">'HOST'</span><span class="p">:</span> <span class="s1">'localhost'</span><span class="p">,</span> <span class="c1"># or an IP Address that your DB is hosted on</span>
|
||
<span class="s1">'PORT'</span><span class="p">:</span> <span class="s1">''</span><span class="p">,</span> <span class="c1"># use default port</span>
|
||
<span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">mysql</span></code> backend is used by <code class="docutils literal notranslate"><span class="pre">MariaDB</span></code> as well.</p>
|
||
<p>Change this to fit your database setup. Next, run:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
|
||
</pre></div>
|
||
</div>
|
||
<p>to populate your database. Should you ever want to inspect the database directly you can from now on also use</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia dbshell
|
||
</pre></div>
|
||
</div>
|
||
<p>as a shortcut to get into the postgres command line for the right database and user.</p>
|
||
<p>With the database setup you should now be able to start start Evennia normally with your new database.</p>
|
||
</section>
|
||
<section id="resetting-mysql-mariadb">
|
||
<h3>Resetting MySQL/MariaDB<a class="headerlink" href="#resetting-mysql-mariadb" title="Permalink to this headline">¶</a></h3>
|
||
<p>If you want to reset your MySQL/MariaDB datbase, see <span class="xref myst">here</span>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="other-databases">
|
||
<h2>Other databases<a class="headerlink" href="#other-databases" title="Permalink to this headline">¶</a></h2>
|
||
<p>No testing has been performed with Oracle, but it is also supported through Django. There are community maintained drivers for <a class="reference external" href="https://code.google.com/p/django-mssql/">MS SQL</a> and possibly a few others. If you try other databases out, consider contributing to this page with instructions.</p>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="Channels-to-Discord.html" title="Connect Evennia channels to Discord"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="Settings-Default.html" title="Evennia Default settings file"
|
||
>previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../index.html">Evennia latest</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="Setup-Overview.html" >Server Setup and Life</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Choosing a database</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2024, The Evennia developer community.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
|
||
</div>
|
||
</body>
|
||
</html> |