GS - SQL
A Godot asset that implements functionality for using SQL in the Gamespice collection.
Lets dot addons keep their data in SQLite, PostgreSQL or MySQL/MariaDB, so records, statistics, achievements and bans can live in a real database that several servers share. Godot has no database client of its own; this is the layer that supplies one.
Install
- Get Godot 4.7.
- Either use dot-bootstrap, which clones every project and links the addons, or copy
addons/dot_sql/and dot-core'saddons/dot_core/into your project and enable dot-sql in Project > Project Settings > Plugins. - For SQLite, run
tools/fetch_sqlite.sh <your project>. It installs a pinned, checksummed release of godot-sqlite (MIT) intoaddons/godot-sqlite. This addon does not ship it.
dot-core is the only dependency.
What is in it
| Piece | What it is |
|---|---|
DotSqlDriverSqlite |
SQLite through godot-sqlite. One server, one file. |
DotSqlDriverGateway |
PostgreSQL, MySQL/MariaDB or SQLite through a small HTTP gateway running beside the database. Several servers, one database. |
tools/sql_gateway.py |
A reference gateway in Python. It handles one request at a time: fine for a few servers, meant to be copied rather than scaled. |
DotSqlDialect |
Everywhere the databases differ: column types, upserts, placeholders, reserved words. |
DotSqlSchema |
Tables described as data and turned into SQL for each database. |
DotSqlMigrator |
Versioned schema changes, one counter per asset. |
DotSql.from_config |
Builds a driver from a config dictionary, so a server picks its database in a file. |
Use
# One SQLite file on this server:
var made := DotSql.from_config({"driver": "sqlite", "path": "user://game.db"}, self)
# A shared MySQL or PostgreSQL database through the gateway:
var made := DotSql.from_config({
"driver": "gateway", "dialect": "mysql",
"url": "http://10.0.0.5:8780", "token": "from your config file",
}, self)
var store := DotTimerStoreSql.new(made.value)
await store.open() # creates or migrates its tables
timers.store = store
Keep the token in the config file. Environment variables and command lines are readable by every process on the machine.
Run the reference gateway:
pip install "psycopg[binary]" pymysql # only the one you need
echo "a long random token" > gateway.token
python3 tools/sql_gateway.py --dialect mysql --dsn mysql://user:pass@127.0.0.1:3306/game --token-file gateway.token
The gateway takes a bearer token on every request. Keep it on a private address or put TLS in front. It is the safer setup anyway: the database password stays on the gateway's machine, and the gateway can connect as a user that only touches the game's tables.
Other addons do not need this one
dot-timer, dot-moderation, dot-leaderboard, dot-achievements and dot-stats each have a SQL store. They hold the driver in an untyped variable and call five methods on it (query, execute, batch, upsert_sql, migrate), so they load without dot-sql.
Testing
| Scene | Checks |
|---|---|
examples/sql_selftest.tscn |
Dialects, placeholders, table specs, upserts, migrations and config, with no database. |
examples/sql_live.tscn |
Real tables, upserts, emoji and quotes, transactions and migrations against a real database. |
Import the project once, then run each scene headless with Godot. tools/test_live.sh runs the live suite on SQLite; set DOT_SQL_PG_DSN and DOT_SQL_MYSQL_DSN to include PostgreSQL and MySQL. It also runs other addons' live suites, such as tools/test_live.sh ../dot-timer res://examples/timer_sql_live.tscn.
Status and licence
Part of the Gamespice platform: a family of Godot addons. Written with Claude Code and maintained by gamemann. Every addon has headless tests, but little of this has been played by real users yet, so expect rough edges and please open an issue when you hit one.
MIT licence, see LICENSE. The only closed part of the Gamespice platform is the web back end; you can use your own instead of Gamespice's.
Engagement Over Time
GS - SQL is a Godot asset. It has 2 downloads, 18 views, and 0 favorites. This item belongs to 1 collection and 7 tags.
Reviews
Log in to leave a review.
Comments (0)
Log in to comment.
