🔒 Access and Locks¶
Meerschaum is open by default—every user sees and edits every pipe within their permissions until you configure access or locks. Two reserved parameters control who owns a pipe and what can happen to it:
access: Sets owner, team, visibility, and edit mode for API servers, MCP, and the web console.locks: Blocks destructive or mutating operations (sync,clear,drop,delete,parameters) everywhere—CLI, Python, jobs, Pipelines, API, and console.
Where each boundary applies
Teams, visibility, and permissions apply through an API server (api: instances, MCP, web console). Anyone holding raw database credentials can query the database directly—use separate database users or isolated teams for hard DB isolation. Locks apply everywhere, even locally and for admins.
For CLI commands (mrsm lock pipes, mrsm edit pipes access, mrsm register teams), see Teams, Access and Locks.
Locks¶
A lock refuses matching operations until explicitly unlocked—-y, --force, and --allow-protected never bypass it:
import meerschaum as mrsm
pipe = mrsm.Pipe('sql:main', 'weather', instance='sql:main')
pipe.lock('drop', 'delete')
pipe.locks # ['drop', 'delete']
pipe.clear(begin='2024-01-01') # allowed: no `clear` lock
pipe.drop() # (False, "Cannot drop ...: it is locked (drop)...")
pipe.unlock('drop') # still locked: delete
pipe.unlock() # unlock all
pipe.lock() # lock `all`
| Lock | Refuses |
|---|---|
parameters |
Parameter edits (pipe.edit(), set_access(), edit pipes). Syncs still write; lock edits stay allowed. |
sync |
Syncs, replaced windows (replace=True), deduplication, and verification syncs. |
clear |
Row deletes (clear, replaced windows, rebuilds). |
drop |
Drops, rebuilds, verify schema, repartitioning, and dropping indices. |
delete |
Deleting (unregistering) the pipe. |
all |
All of the above. |
Compound operations require every affected lock to be open:
| Operation | Refused by |
|---|---|
sync --replace / pipe.sync(..., replace=True) |
sync, clear |
| Definition rebuild | sync, clear, drop |
delete pipes / pipe.delete() |
drop, delete |
pipe.delete(drop=False) |
delete |
repartition pipes / pipe.repartition() |
drop, parameters |
- Locks are re-read from the instance before every write, so changes from another process apply immediately.
- Saved Pipelines also support locks; internal
mrsmpipes do not.
Locks in Pipeline runs¶
During a Pipeline run (--parents, Pipeline.sync(), or scheduled Pipeline jobs), a sync-locked pipe is skipped with status locked (not a failure), and downstream pipes continue using its existing data. A direct pipe.sync() on a locked pipe is refused immediately.
Access¶
pipe.set_access(team='analytics', visibility='private', edit='owner', owner='carol')
pipe.owner, pipe.team, pipe.visibility, pipe.edit_mode
# ('carol', 'analytics', 'private', 'owner')
pipe.set_access(owner=None) # clear owner, keep other keys
pipe.set_access(team=None) # move back to Everyone
| Key | Values |
|---|---|
owner |
Username, or None. |
team |
Team name, or None for Everyone. |
visibility |
team (default: team members + owner), private (owner, team managers, admins), everyone (all users). |
edit |
team (default: anyone who can see it), owner (owner, team managers, admins). |
- Pipes registered through an
api:instance or the web console default to the creator asownerand their primary team asteam. - Only the owner, team managers, and admins can edit
accessor locks. copy pipespreserves locks and never copiesaccess. Deleting a user clears ownership while leaving pipes with their teams.
Teams¶
Every user belongs to Everyone (cannot be deleted, renamed, or left). Admins create additional teams with members and managers (managers can add/remove members and manage the team's pipe access):
import meerschaum as mrsm
team = mrsm.Team('analytics', instance='sql:main', members=['alice', 'bob'], managers=['carol'])
team.register()
team.add_members('dave')
team.add_managers('bob')
team.remove_members('alice')
team.rename('data-team') # updates pipes, Pipelines, and jobs
team.delete() # moves pipes and legacy jobs to Everyone
Team names are case-insensitive (ANALYTICS matches analytics). Members must be registered users.
Users, roles and permissions¶
Roles are presets of token scopes (meerschaum.core.access.ALL_PERMISSIONS):
| Role | Permissions |
|---|---|
viewer |
Read visible pipes, jobs, logs, plugins, and connectors list; edit own account. |
editor |
Viewer, plus register, edit, and sync pipes (pipes:register, pipes:write, pipes:define_sql), start jobs, and run read-only SQL. |
operator |
Editor, plus execute actions (actions:execute), use the web terminal (webterm:use), and create/stop/pause/delete jobs. |
admin |
All permissions, including users, teams, and connector details (type: admin). |
from meerschaum.core import User
user = User('bob', instance='sql:main')
user.set_role('viewer')
user.set_permissions(['pipes:read', 'logs:read']) # user.role == 'custom'
user.teams # [('Everyone', 'member'), ('analytics', 'manager')]
- A user without an explicit role or permission list inherits
api:permissions:default_role(editorby default). - A token's scopes always intersect with its owner's current permissions.
Checking rules in Python¶
Plugins and console pages can use the same access helpers the API server runs:
from meerschaum.core.access import Principal, can_see, can_edit, filter_visible_pipes, get_principal
alice = get_principal('alice', instance='sql:main')
can_see(alice, pipe), can_edit(alice, pipe)
visible = filter_visible_pipes(alice, mrsm.get_pipes(instance='sql:main', as_list=True))
| Helper | Purpose |
|---|---|
can_see(principal, access) / can_edit(...) |
Check visibility and edit rights for a pipe or access dict. |
can_manage_access(...) / can_lock(...) |
Check if caller is owner, team manager, or admin. |
can_see_email(viewer, user_teams, target_username=) |
Check email visibility (self, team manager, or admin). |
check_lock(locks, op) / lock_refusal(pipe, locks, op) |
Check whether an operation (sync, clear, drop, etc.) is locked. |
user_permissions(...), role_permissions(...), token_permissions(...) |
Compute effective permissions. |
Custom instance connectors inherit teams, access, and locks automatically—teams are stored in Pipe('mrsm', 'teams') and locks are checked before every write.