feat: Organizations & team-based access control

[kayvanaarssen]

Background

PR #259 added per-user server access — you can give a single user access to a specific server and optionally restrict them to one or more databases. That covers the simple case really well.

But during the review a good point came up: for teams working on multiple client environments it makes more sense to group servers and volumes under an Organization and manage access at that level, rather than wiring up every user individually. At the same time, the single-user-to-single-database path should still work without having to spin up a full org for it.

This issue is to plan that out and get everyone's input before writing code.

---

Proposed model

Two access paths, both supported

Org path — for teams
Create an org → assign servers/volumes to it → add users as members. Everyone in the org gets access to those resources automatically.

Direct path — for individuals
Assign a user directly to a server (with optional DB restriction) using the existing UserServerAccess mechanism. No org needed.

Data model sketch

organizations
  id, name, slug, created_by

organization_members  (pivot)
  organization_id, user_id, role: owner | admin | member | viewer

database_servers  →  + organization_id (nullable)
volumes           →  + organization_id (nullable)

user_server_accesses  (already exists from PR #259)
  user_id, database_server_id, allowed_databases[], can_restore

organization_id being nullable keeps the direct-access path intact — a server with no org is only reachable by app admins and users with an explicit grant.

Permission resolution

1. App Admin → full access, no restrictions
2. Org member/viewer → sees servers and volumes belonging to their active org, scoped to their allowed_databases if set
3. User with a direct UserServerAccess grant (no org) → sees only those specific servers/databases

Org switcher

Session-based selector in the nav (same approach as the theme switcher) — keeps routing simple and doesn't require touching every URL.

---

Suggested build order

Since this touches a lot of models and policies, splitting it into two PRs makes sense:

PR 1 — Organizations

• Migrations: organizations, organization_members, organization_id on servers + volumes
• Auto-migration: existing servers/volumes stay accessible (nullable FK, no breaking change)
• CRUD: manage orgs and members (admin only)
• Nav org-switcher
• Policies updated to respect org membership

PR 2 — Fine-grained access (builds on PR 1)

• When a user is added to an org, optionally restrict them to specific servers/databases (generates UserServerAccess rows)
• Scoped views: server cards, backup lists, snapshot lists only show what the user can actually access
• This is essentially what PR feat: resource-scoped server access permissions for Viewer/Demo users #259 adds, just wired into the org context

---

Open questions

1. Org member roles — does viewer = read-only (no backup/restore triggers) and member = full actions make sense? Or should that be configurable per org?

2. Org-level DB restriction vs per-member restriction — should an org be able to say "everyone in this org only sees databases X and Y on server Z"? Or is per-member restriction (via UserServerAccess) enough?

3. Personal org or truly optional? — always giving every user a personal org (GitHub-style) simplifies the "always have an active org" assumption but adds noise for solo installs. Truly optional is cleaner for simple setups.

4. Existing installs — for people already running the app, what's the migration story? Auto-create a default org and move everything into it, or leave organization_id null and let admins organise things manually?

---

Happy to start building once there's some alignment on the questions above. Curious what others think about the org roles and whether an org-level DB restriction is worth the extra complexity.

[kayvanaarssen]

@David-Crty - What's your take on the above. To simple or you want to go into this with a bit more depth. I've created this as an issue first instead of a pull request to first map out the scope of what we have in mind to implement. And then see what fits.
Still think this would be along side individual access like i've already created the PR for

[David-Crty]

Busy weekend but I will try to check that asap and let you know. Thanks for everything @kayvanaarssen 🙏

[David-Crty]

Hey @kayvanaarssen 👋

A first version of the multi-organization feature is ready to be tested! You can try it out from PR #275 using the Docker image davidcrty/databasement:feat-multi-organization.

What's been implemented

• Organization model & data isolation — resources (database servers, volumes, agents, snapshots) are scoped to organizations via Eloquent global scopes. Each org has its own isolated set of resources.
• Per-org roles — Users can belong to multiple organizations with different roles in each: Admin, Member, Viewer. A global Super Admin flag grants cross-org access.
• Organization management — Super admins can create, rename, and delete organizations from Configuration > Organizations.
• Organization switcher — Session-based selector in the sidebar (visible when a user belongs to multiple orgs). Selection is persisted via cookie.
• User management — Admins can invite new users or add existing users (from other orgs) to the current organization with a specific role.
• API support — ?org_id= query parameter and X-Organization-Id header for org selection in API requests.
• Safe migration path — Three-step migration (schema, data backfill, finalize) that auto-creates a "Main" organization and moves existing resources into it. No breaking changes for existing installs.
• 77 files changed, covering models, middleware, policies, Livewire components, views, migrations, and tests (899 tests passing).

Documentation

Full documentation is available here:
https://github.com/David-Crty/databasement/blob/refs/heads/feat/multi-organization/docs/docs/user-guide/organizations.md

Happy to get your feedback on this! 🙏

[David-Crty]

@kayvanaarssen

The Organization feature has been released in version 1.2. If you install the new Docker image, you'll be able to access it.

Please provide some feedback.

P.S.: Currently, there are no database server restrictions for users within the same organization.

[kayvanaarssen]

@kayvanaarssen

The Organization feature has been released in version 1.2. If you install the new Docker image, you'll be able to access it.

Please provide some feedback.

P.S.: Currently, there are no database server restrictions for users within the same organization.

Awesome, will test asap, was out of the office whole last week for projects.
Currently, there are no database server restrictions for users within the same organization. Hopefully this will be added soon :-D

Also saw this last night while scrolling through reddit: https://portabase.io/
https://www.reddit.com/r/selfhosted/comments/1szy1nw/portabase_v113_opensource_db_backuprestore_tool/

Not tested yet.

[kayvanaarssen]

@kayvanaarssen

The Organization feature has been released in version 1.2. If you install the new Docker image, you'll be able to access it.

Please provide some feedback.

P.S.: Currently, there are no database server restrictions for users within the same organization.

Just tested - so far so good, options missing.

• Move database servers and thus jobs between orgs
• Add user to org but still limit what a user can or can't do (as you stated not in it yet)
• For us as IT / Admin of the backups we need to be able to see a high level view of all servers / jobs and thus not have to switch orgs (in our use case) So even if we have many orgs, we should still be able to see all servers, and then may need to limit orgs from changing servers (our use case again)

For us we do have some devs (that let us handle the server stuff) so we can grant them full access under the org - like but they cannot change the server connection itself - but they can backup / restore / browse backups etc.

We want to have the orgs so its organised and structured. But we also have some of those same devs that have access to sites on our shared server where we want them to be able to backup / restore / browse backups. So then we dus need to give a user or org access to a specific server >> Database for them to access but not see the rest that is on there.

[David-Crty]

Hey @kayvanaarssen, thanks for taking the time to actually test it and write up the gaps in detail — that kind of feedback is gold 🙏

To be honest, for the scope I had in mind when I started this, the v1.2 release is where I want to land for now. Multi-org with global scoping, an org switcher, invites and the migration path covers what most teams need to get started, and it's already a big surface to maintain.

The three items you raised are all legitimate, but each one is its own non-trivial feature:

1. Moving servers/jobs between orgs — ownership reassignment touches policies, audit trails, snapshot lineage.
2. Finer-grained per-user permissions inside an org (read-only vs can-backup vs can-edit-server, etc.) — that's a whole permissions layer on top of the current role enum.
3. A cross-org "admin overview" for IT/Admins that doesn't require switching orgs — that's a different UX paradigm than the current session-scoped switcher.

I work on Databasement in my spare time and I can't take all three on in one go without it dragging out for months. So I'd like to ask: could you open a separate issue for the one that matters most to you? One thing per issue, with the concrete use case. That lets me (or anyone who wants to contribute) pick them up individually, and we don't lose track of them in this thread.

Closing this one since the original "Organizations & team-based access control" feature is shipped. The follow-ups deserve their own homes.

Thanks again for the help shaping this 💙

[kayvanaarssen]

Hey @kayvanaarssen, thanks for taking the time to actually test it and write up the gaps in detail — that kind of feedback is gold 🙏

To be honest, for the scope I had in mind when I started this, the v1.2 release is where I want to land for now. Multi-org with global scoping, an org switcher, invites and the migration path covers what most teams need to get started, and it's already a big surface to maintain.

The three items you raised are all legitimate, but each one is its own non-trivial feature:

1. Moving servers/jobs between orgs — ownership reassignment touches policies, audit trails, snapshot lineage.
2. Finer-grained per-user permissions inside an org (read-only vs can-backup vs can-edit-server, etc.) — that's a whole permissions layer on top of the current role enum.
3. A cross-org "admin overview" for IT/Admins that doesn't require switching orgs — that's a different UX paradigm than the current session-scoped switcher.

I work on Databasement in my spare time and I can't take all three on in one go without it dragging out for months. So I'd like to ask: could you open a separate issue for the one that matters most to you? One thing per issue, with the concrete use case. That lets me (or anyone who wants to contribute) pick them up individually, and we don't lose track of them in this thread.

Closing this one since the original "Organizations & team-based access control" feature is shipped. The follow-ups deserve their own homes.

Thanks again for the help shaping this 💙

Thanks for the response, and of course we don't expect you to deliver tomorrow :-D Happy to see the product grow!