Ban database refactor #42495

PJB3005 · 2026-01-18T03:11:18Z

About the PR

This refactors the way bans are stored in the database, enabling bans to have multiple players/HWIDs/IPs/rounds/roles per ban. There's also significant code cleanup along the way.

This PR does not update most of the game/tooling to expose this new functionality (eg banning on multiple round IDs), that can be done in separate PRs once the main schema refactor is over with. The one exception is that role bans now make one ban with multiple roles.

Why / Balance

Our admins are weeping because role bans weren't normalized in the DB properly and needed to be separate records per job.
Having multiple players/HWIDs/IPs per ban record enables future sticky ban tracking systems sanely.
Multiple rounds per ban is because I was thinking "well if I'm gonna do a massive DB change might as well be proactive."

Technical details

The DB model has been significantly refactored:

The distinction between role and server bans has been removed from the schema, they are now distinguished by a type column on the single ban table.
Information about players/HWIDs/IPs/rounds/roles is now stored normalized in separate tables.
The removal of the distinction between the ban types has been plumbed through much of the codebase, removing a significant amount of code copy paste. Yuck.
SQL migration (for both SQLite and PostgreSQL) should be able to automatically migrate the database to the new format. It does its best to merge denormalized role ban records into single bans with multiple roles.
Oh yeah I fixed the fact that the PostgreSQL index for matching addresses on bans doesn't work. It's a proper GiST index now. I doubt that matters for database performance though.
Plumbed through ProtoId<> more thoroughly in some role ban code.
Removed the optimization where DB ban notification aren't checked on the server that created the ban, as now round IDs are no longer indicative of the game server placing the ban.
Role ban IDs (previously Job:Captain) are now more cleanly typed to avoid confusion.
SS14.Admin PR here: Support new DB schema SS14.Admin#82

Media

Requirements

I have read and am following the Pull Request and Changelog Guidelines.
I have added media to this PR or it does not require an in-game showcase.

Breaking changes

The database schema for bans (both kinds) has been completely refactored to unify server & role bans and allow multiple players/HWIDs/IPs/rounds/roles per ban record.
- C# types and methods have all been modified to reflect this change. In many cases, things have merged (e.g. ServerBanDef & ServerRoleBanDef -> BanDef).
- Separate C# functions for "server bans" and "role bans" have all been merged into just "ban" where applicable (e.g. GetBanAsync().
- This is a large change to the database schema that must be done at the same time for all servers sharing a database. Applying the migration while some game servers have not updated yet will cause a lot of issues.
Plumbed through ProtoId<> more thoroughly in some role ban code.
Role ban IDs (previously Job:Captain) are now more cleanly typed as BanRoleDef in C# to avoid confusion.

Changelog

🆑
ADMIN:

tweak: Role bans for multiple jobs are now stored in a single ban entry, rather than having to create a dozen individual ones.

Supports all the new functionality (multiple players/addresses/hwids/roles/rounds per ban).

The server ID check is no longer done as admins may want to place bans spanning multiple rounds irrelevant of the source server.

PJB3005 · 2026-01-18T03:11:58Z

Marking as draft since I still want to do more testing. Also I need to rebase this onto stable so we can do the server update.

…efactor

SS14.Admin changes would like this

Not relevant, reduces query performance

Would blow up handling null player records. Not a new bug introduced by the refactor, but I ran into it.

VasilisThePikachu

I will do a review later however quick thing I noticed

Please update the deletion and data dump scripts to the new schema.

PJB3005 · 2026-01-20T22:31:41Z

Please update the deletion and data dump scripts to the new schema.

oh yeah fair enough

juliangiebel

Banning multiple departments with the same roles causes the a database exception because the unique index IX_ban_role_role_type_role_id_ban_id gets violated.

An easy way to replicate this is banning someone from command and security

stacktrace.txt

juliangiebel · 2026-01-21T18:41:20Z

The schema looks fine otherwise. The queries could be improved to cut down on roundtrips (because of split queries. The ban table really isn't large enough to require split queries imo) and joins but that is really out of scope for this PR imo

Most notably happened with role bans, as multiple departments may include the same role.

VasilisThePikachu · 2026-01-22T01:18:53Z

Merge before maintenance starts so that vulture does not start with it before we are ready for the db migration.

Ban database refactor (#42495) * Ban DB refactor seems to work at a basic level for PostgreSQL * New ban creation API Supports all the new functionality (multiple players/addresses/hwids/roles/rounds per ban). * Make the migration irreversible * Re-implement ban notifications The server ID check is no longer done as admins may want to place bans spanning multiple rounds irrelevant of the source server. * Fix some split query warnings * Implement migration on SQLite * More comments * Remove required from ban reason SS14.Admin changes would like this * More missing AsSplitQuery() calls * Fix missing ban type filter * Fix old CreateServerBan API with permanent time * Fix department and role ban commands with permanent time * Re-add banhits navigation property Dropped this on accident, SS14.Admin needs it. * More ban API fixes. * Don't fetch ban exemption info for role bans Not relevant, reduces query performance * Regenerate migrations * Fix adminnotes command for players that never connected Would blow up handling null player records. Not a new bug introduced by the refactor, but I ran into it. * Great shame... I accidentally committed submodule update... * Update GDPR scripts * Fix sandbox violation * Fix bans with duplicate info causing DB exceptions Most notably happened with role bans, as multiple departments may include the same role.

Ban database refactor (space-wizards#42495) * Ban DB refactor seems to work at a basic level for PostgreSQL * New ban creation API Supports all the new functionality (multiple players/addresses/hwids/roles/rounds per ban). * Make the migration irreversible * Re-implement ban notifications The server ID check is no longer done as admins may want to place bans spanning multiple rounds irrelevant of the source server. * Fix some split query warnings * Implement migration on SQLite * More comments * Remove required from ban reason SS14.Admin changes would like this * More missing AsSplitQuery() calls * Fix missing ban type filter * Fix old CreateServerBan API with permanent time * Fix department and role ban commands with permanent time * Re-add banhits navigation property Dropped this on accident, SS14.Admin needs it. * More ban API fixes. * Don't fetch ban exemption info for role bans Not relevant, reduces query performance * Regenerate migrations * Fix adminnotes command for players that never connected Would blow up handling null player records. Not a new bug introduced by the refactor, but I ran into it. * Great shame... I accidentally committed submodule update... * Update GDPR scripts * Fix sandbox violation * Fix bans with duplicate info causing DB exceptions Most notably happened with role bans, as multiple departments may include the same role.

PJB3005 added 7 commits January 16, 2026 21:56

Ban DB refactor seems to work at a basic level for PostgreSQL

03c813b

New ban creation API

6718787

Supports all the new functionality (multiple players/addresses/hwids/roles/rounds per ban).

Make the migration irreversible

77f08b7

Re-implement ban notifications

ef46d62

The server ID check is no longer done as admins may want to place bans spanning multiple rounds irrelevant of the source server.

Fix some split query warnings

dbe76b4

Implement migration on SQLite

9002946

More comments

390d7f2

PJB3005 added P2: Raised Priority: Item has a raised priority, indicating it might get increased maintainer attention. T: Refactor Type: Refactor of notable amount of codebase A: Admin Tooling Area: Admin tooling and moderation. A: Database Area: Database code labels Jan 18, 2026

PJB3005 changed the base branch from master to stable January 18, 2026 22:37

PJBot added Changes: Sprites Changes: Might require knowledge of spriting or visual design. Changes: Map Changes: Might require knowledge of mapping. Changes: Audio Changes: Might require knowledge of audio. labels Jan 19, 2026

PJB3005 force-pushed the 26-01-16-ban-db-refactor branch from f637bb8 to 390d7f2 Compare January 19, 2026 20:11

PJBot removed Changes: Map Changes: Might require knowledge of mapping. Changes: Audio Changes: Might require knowledge of audio. labels Jan 19, 2026

PJB3005 added 5 commits January 19, 2026 21:11

Merge remote-tracking branch 'upstream/stable' into 26-01-16-ban-db-r…

3190979

…efactor

Remove required from ban reason

ddea9b4

SS14.Admin changes would like this

More missing AsSplitQuery() calls

4b40f70

Fix missing ban type filter

68bf660

Fix old CreateServerBan API with permanent time

cafac97

PJB3005 added this to NextGen WizDen Adminning Jan 20, 2026

github-project-automation bot moved this to 👀 Needs Review in NextGen WizDen Adminning Jan 20, 2026

PJB3005 added 4 commits January 20, 2026 02:29

More ban API fixes.

5557586

Don't fetch ban exemption info for role bans

07c32b5

Not relevant, reduces query performance

Regenerate migrations

c622183

Fix adminnotes command for players that never connected

3f16161

Would blow up handling null player records. Not a new bug introduced by the refactor, but I ran into it.

PJB3005 marked this pull request as ready for review January 20, 2026 22:21

PJB3005 requested review from DrSmugleaf and crazybrain23 as code owners January 20, 2026 22:21

Great shame... I accidentally committed submodule update...

49bd41d

VasilisThePikachu reviewed Jan 20, 2026

View reviewed changes

VasilisThePikachu self-requested a review January 20, 2026 22:31

PJB3005 added 2 commits January 20, 2026 23:47

Update GDPR scripts

4bdd83c

Fix sandbox violation

336262d

VasilisThePikachu approved these changes Jan 21, 2026

View reviewed changes

juliangiebel requested changes Jan 21, 2026

View reviewed changes

PJBot added S: Awaiting Changes Status: Changes are required before another review can happen and removed S: Needs Review Status: Requires additional reviews before being fully accepted. Not to be replaced by S: Approved. labels Jan 21, 2026

Fix bans with duplicate info causing DB exceptions

c666436

Most notably happened with role bans, as multiple departments may include the same role.

PJB3005 requested a review from juliangiebel January 21, 2026 19:47

PJBot added S: Needs Review Status: Requires additional reviews before being fully accepted. Not to be replaced by S: Approved. and removed S: Awaiting Changes Status: Changes are required before another review can happen labels Jan 21, 2026

juliangiebel approved these changes Jan 21, 2026

View reviewed changes

VasilisThePikachu added the S: DO NOT MERGE Status: Open item that should NOT be merged. DNM. Allows test to run unlike draft. label Jan 22, 2026

PJB3005 merged commit 4e42843 into space-wizards:stable Jan 23, 2026
10 checks passed

github-project-automation bot moved this from 👀 Needs Review to ✅ Done in NextGen WizDen Adminning Jan 23, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Ban database refactor #42495

Ban database refactor #42495

Uh oh!

PJB3005 commented Jan 18, 2026 •

edited

Loading

Uh oh!

PJB3005 commented Jan 18, 2026

Uh oh!

VasilisThePikachu left a comment

Uh oh!

PJB3005 commented Jan 20, 2026

Uh oh!

juliangiebel left a comment •

edited

Loading

Uh oh!

juliangiebel commented Jan 21, 2026

Uh oh!

VasilisThePikachu commented Jan 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Ban database refactor #42495

Ban database refactor #42495

Uh oh!

Conversation

PJB3005 commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

About the PR

Why / Balance

Technical details

Media

Requirements

Breaking changes

Uh oh!

PJB3005 commented Jan 18, 2026

Uh oh!

VasilisThePikachu left a comment

Choose a reason for hiding this comment

Uh oh!

PJB3005 commented Jan 20, 2026

Uh oh!

juliangiebel left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juliangiebel commented Jan 21, 2026

Uh oh!

VasilisThePikachu commented Jan 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

PJB3005 commented Jan 18, 2026 •

edited

Loading

juliangiebel left a comment •

edited

Loading