Skip to content

v5.1.0

Choose a tag to compare

@bmeares bmeares released this 20 Nov 04:11
· 2 commits to main since this release
v5.1.0
e5eec37

Meerschaum 5.1.0

5.1.0 is a security release for deployments that allow non-admin users to run commands or use the web terminal. It also adds per-team execution environments and runs supported non-admin commands under the signed-in user's permissions. See Teams on One Instance and the team executor guide.

Ordinary Meerschaum use is supported on Linux 6.8, macOS, and Windows. Isolated Team commands and terminals require a Linux execution host with Landlock signal scoping (ABI 6, available since Linux 6.12) and verified Unix-socket denial. For containers, check the kernel of the Docker host or Docker Desktop VM.

Before upgrading from 5.0.x

  • Upgrade the native CLI, the Python API host, and the Python package in each Team worker interpreter together. Team workers require Meerschaum 5.1.0 or later. For a Python user-site installation of 5.0.x, run python3 -m pip install --user --upgrade meerschaum with the installation's interpreter.
  • Before recreating the stack, review the read-only Grafana role, Valkey password, and credential file changes below. List additional schemas that Grafana must read in stack:grafana:readonly_schemas. Run mrsm stack to generate the default Compose file.
  • Use TCP for connectors accessed by Team workers whose sandbox denies Unix sockets. Reconnect to a live web terminal to restore its tmux windows. Review the permitted commands and required scopes before upgrading users who rely on the web terminal or command API. Permissions
  • In 5.1.0, authenticated non-admin calls from isolated teams to confined native Rust plugin routes require plugins:read, the route's declared built-in scopes, and an attested offline Rust compiler on the execution host. Non-isolated callers (Everyone, custom-scope portal users, and host device tokens) continue to reach host Python and native plugin routes under each route's declared scopes.

Changes

  • Internal engine hypertables use 7-day chunks, 7-day compression, and chunk-dropping retention. The engine's internal time-series tables (mrsm_engine_events, mrsm_engine_metrics, mrsm_engine_nodes, mrsm_engine_runs, and mrsm_engine_ledger) now configure 7-day chunks (verify.chunk_days: 7) and a 7-day TimescaleDB compression window (compress.after: "7 days") instead of 30-day chunks and 30-day compression policies (which previously expired before ever compressing). On TimescaleDB, existing 5.0 installations still on the 30-day default are automatically migrated once per connection without overwriting custom admin intervals or touching history, and end-only clear_pipe calls (used by engine history and sync-metrics retention) now run drop_chunks before DELETE so expired chunks reclaim disk space immediately.
  • Faster web terminal & interactive shell startup, and incremental plugin manifests. Interactive shells and web terminals (mrsm, mrsm --shell, mrsm -i <instance>) now open immediately on cached plugin metadata and refresh stale plugin manifests quietly in the background instead of blocking the prompt. Manifest caches are also keyed per resolved MRSM_PLUGINS_DIR list alongside <root>/cache/plugins_manifest.json / native_plugins_manifest.json so multiple Compose projects sharing one root directory no longer invalidate each other's caches. Static attempt_import scanning skips files that do not reference attempt_import, carries forward cached warnings for unchanged plugins, recognizes PyPI distribution aliases such as PIL → Pillow, and plugin loading iterates vars(module) so lazy module-level __getattr__ re-exports are not eagerly triggered.
  • Native Rust plugin SDK additions (ABI v1 compatible). Both Cargo plugins (meerschaum-plugin) and single-file Rust plugins now provide:
    • Parameterized SQL (host::read_sql_with, host::exec_sql_with) with :name binds, native PostgreSQL array binds (= ANY(:ids), including empty arrays), and typed datetime/date/bytes/json helpers (Bound::to_sql_param, host::sql_timestamptz, host::sql_timestamp, host::sql_date, host::sql_bytes, host::sql_json).
    • Host-managed SQL transactions (host::transaction(connector_keys, lock_key, |tx| ...)) with tx.read_sql_with / tx.exec_sql_with, automatic commit on Ok and rollback on Err or panic unwind, optional transaction-scoped advisory locks (pg_advisory_xact_lock on PostgreSQL-family databases, BEGIN IMMEDIATE on SQLite/GeoPackage), and full support from concurrent native HTTP route handlers.
    • host::root_dir() -> Result<PathBuf> and context["root_dir"] in fetch/subscribe calls reflecting the resolved root directory of the current call (including Compose run_in_process).
    • Pipe::id() -> Result<Option<i64>> and Pipe::is_registered() -> Result<bool> on native Pipe handles.
    • Custom connector methods callable from Python (mrsm.get_connector('<type>:<label>').<method>(**kwargs)), including #[method] functions inside single-file #[make_connector] modules without requiring fetch/sync/subscribe.
  • Host-team resource limits and egress controls (Linux). Optional system.engine settings cap isolated host-team workers and jobs with kernel rlimit bounds (python_team_max_cpu_seconds, python_team_max_memory_mb, python_team_max_file_mb, python_team_max_processes), an aggregate writable-directory disk quota (python_team_max_disk_mb), and outbound network policies (python_team_egress: open | deny | allow_ports with python_team_egress_ports enforced via Landlock ABI 4+ and seccomp). mrsm doctor reports active limits under teams.
  • Empty jobs: {} in Compose. Setting jobs: {} in a Compose project starts no jobs instead of falling back to syncing the project's pipes.
  • Declare rows immutable with sync.immutable: true and select a synchronization strategy such as join, unbounded-simple, or a monthly corrective strategy. Existing pipes keep their backtrack behavior.
  • Isolated teams. A team created with "Hide Everyone's pipes, jobs, connectors and plugins" sees only what belongs to it or was granted to it, in the console, the HTTP API and MCP. Isolated members cannot chain instances. Commands and terminals follow the caller's permissions and the team's execution policy. A user in both an isolated and an open team keeps the open team's view.
  • A database per team. New team in the console and the new bootstrap teams action can create a database or a schema for the team on an existing PostgreSQL-family connector, with a role for the team, a read-only role for dashboards and a connector reserved for the team, which becomes its default instance. The server picks up the new connector without a restart.
  • Team settings. New team and a team's Settings choose its default instance, the connectors and plugins it may use, and whether its members may install plugins.
  • Team plugins. A team allowed to install plugins can install from the repository, create a plugin, or upload files and archives from Plugins → New plugin; its members manage their team's plugins only.
  • Connect an agent. The Tokens page shows ready-to-paste MCP configuration for Claude Code, Claude Desktop, Codex, OpenCode and other clients, with the API key of a new token filled in.
  • Grafana. With api:grafana:enabled, the server signs console users in to Grafana at /grafana, keeps one organization per team with a data source for the team's database, and removes members of isolated teams from the main organization. The stack's grafana service gets the settings it needs when the stack is next started.
  • Grafana safety. Meerschaum owns Grafana's administrator password (generated when api:grafana:admin_password is unset, and Grafana's default admin replaced), trusts the sign-in header only from the stack's API server at a fixed address (never a range), keeps each team's organization by its saved id, retires a deleted team's organization (dashboards kept, members and data sources removed), never lets a team use the anonymous or main organization, and forwards signed-out visitors to Grafana's own anonymous access without any identity.
  • The stack's Grafana reads through a read-only role (upgrading users, read this). The provisioned Meerschaum Main data source now connects as mrsm__main_ro instead of sql:main's user (the database's owner), on every stack, with or without api:grafana. The next mrsm stack up -d sets the role up (a one-shot grafana_readonly service runs before Grafana starts) and switches the data source in place, also when config/stack.yaml holds a copy of the old default; dashboards keep working. The role reads the tables, views and hypertables in the schemas sql:main's user owns and nothing of any team's; anonymous visitors can no longer write, create tables or install extensions such as dblink. A dashboard that writes through Meerschaum Main, or reads a schema owned by another role, stops working: list such schemas under stack:grafana:readonly_schemas. A Meerschaum Main you pointed at another user is left as it is. See Grafana's read-only data source.
  • Deleted teams leave nothing to their name. Deleting a team (console, delete teams, API) keeps its connector, database and data but retires the connector's reservation (teams becomes Deleted team <name> #<id>), so a new team of that name, or one renamed to it, no longer gets the old database. Renaming a team moves its reservations to the new name. Creating or renaming a team onto a name a connector is still reserved for is refused unless an administrator passes adopt.
  • With api:grafana, the API server warns once at startup, while Grafana's anonymous access is on, about the data sources in the main and anonymous organizations other than the read-only Meerschaum Main.
  • Secrets in configuration. MRSM{file:<path>} reads a secret from a file (a Docker secret, a systemd credential) and MRSM{env:<NAME>} from an environment variable, wherever MRSM{} works; a rotated file reaches the next connector built, a reference that cannot be read fails only the connector that needs it, and the values they produce are masked everywhere. MRSM_CONFIG_FILE / MRSM_PATCH_FILE read the two patches from files. Every config writer now writes the file as written plus its change: register connectors and the other writers no longer persist environment connectors, MRSM_CONFIG / MRSM_PATCH values or resolved secrets. A config file holding an inline secret (a value under a password, secret, token, API key, private key or credentials name, or a URI with a password) that its group or others can read gets a warning with the chmod to run. See Secrets in configuration.
  • The stack's credentials leave the compose file (upgrading users, read this). mrsm stack now writes the api service's MRSM_CONFIG / MRSM_PATCH (every connector's password, Grafana's administrator password) to <root>/stack/secrets/api/ and gives the container MRSM_CONFIG_FILE / MRSM_PATCH_FILE; Grafana's administrator password and the grafana_readonly service's passwords move to files the same way. stack/docker-compose.yaml and docker inspect hold paths; <root>/stack/secrets/ is readable by you only. A config/stack.yaml with the old entries (or your own) is moved as it is, with your extra keys. Only an image that reads the files gets them: bmeares/meerschaum:<version> with <version> 5.1.0 or newer (the default). Any other image (an older version, latest, your own build) keeps the environment form with a warning naming the reason; set stack:api_config_files: true for your own 5.1 image, false to keep the environment without the warning. The next mrsm stack up -d recreates the services whose credentials moved. See Credentials in files.
  • Jobs get their configuration in files. A job started with MRSM_CONFIG / MRSM_PATCH in its environment (every job a Compose project with a config: block starts) now gets them as owner-only files in its directory (jobs/<name>/.mrsm_config.json, or systemd/services/<name>/ next to its unit) and MRSM_CONFIG_FILE / MRSM_PATCH_FILE, so /proc/<pid>/environ and the systemd unit no longer hold the credentials. Jobs started earlier keep their environment until they are next started; compose up recreates its jobs and rewrites the files.
  • Team-scoped workers on the main host. Python code allowed to run with an isolated team's credentials (its plugins' fetches, sync(), hooks and register() in a sync, and its jobs, including those the server restarts after a reboot) runs in workers and jobs started with only the team's connectors: an owner-only configuration file under <root>/team_scopes/ (or the job's directory), an empty config directory of their own, and an environment built from an allowlist (what a process needs to run and reach the network, and Meerschaum's variables that hold no secret): none of the server's MRSM_CONFIG, MRSM_PATCH or MRSM_<TYPE>_<LABEL> variables, nor any other variable of its own (cloud credentials, tokens) unless system.engine.python_team_env_passthrough names it; a job's recorded env holds the same allowlist, so a restart after a reboot or a systemd unit does not bring the server's environment back. Their callbacks into Meerschaum (pipe.sync(df)) are limited to the team's instances and pipes. A team worker must prove in its handshake that it loaded the team's configuration (an older meerschaum package cannot, and would load the default connectors): one that does not is stopped before running any of the team's code, and a team job's workers are checked the same way; an API host whose package predates the lookup check is not sent isolated teams' requests (503 naming the fix). Team-scoped work needs the Python package 5.1.0 or newer. A granted or revoked connector, a rename, a deletion or a rotated password takes effect at the team's next call without a restart (old workers stop; a team that loses a connector has its running jobs restarted). New settings system.engine.python_team_workers (the most live workers of all teams together; by default the shared pool's size) and system.engine.python_worker_team_idle_seconds (default 60). In the shared API host, a request of an isolated team's member may not look up other connectors (get_connector() raises PermissionError, get_config() leaves them out). That is a guard rail, not a wall: see What isolates a team for what each layer stops and what none of them do.
  • A filesystem sandbox for isolated teams' host processes (Linux). A team worker, before it imports anything of the team's, and a team job's mrsm, before it runs the job's command, restrict themselves with Landlock: they and everything they start may read the system's programs and libraries, the interpreter, the team's own configuration, plugins and job directories, and write only the team's temporary and cache directories, its own virtual environments and a job's work directory. The server's config/ files, the root's secret files, other teams' configuration, jobs and plugins, the home directory and other processes' /proc entries are out of reach. Newer kernels add the signal and abstract-socket scopes (Linux 6.12: a team's code cannot signal the server) and pathname Unix socket rules (Linux 7.1: no Docker socket). Outbound network connections are not restricted. New setting system.engine.python_team_sandbox: auto (default: enforce where the kernel supports it, else warn once at start), require (refuse to run a team's code without it), require_sockets (see below) or off. Each team worker proves the sandbox in its handshake by failing to read a canary file, and is stopped otherwise; a team job checks the same and logs what is enforced; mrsm doctor and the server's start-up log show the mode, the Landlock ABI and the parts in force, and warn when the server's user can open a container socket the sandbox does not cover. A team job no longer writes its own job directory (its result, heartbeat and start-up release go to jobs/<name>/.mrsm_team_work/), and a team's processes see their own plugins only. See The filesystem sandbox.
  • A job's team is the server's to record. The isolated team a job runs for (its configuration and credentials) follows from the team the server records for the caller who created it. A team_scope property sent with POST /jobs/{name} (or set in the properties a job is created with, from Python or the console) is dropped instead of tying the job to the scope it names. Registered private job history keeps its original owner and team identities. Deleting a team preserves that history for its owner and administrators, and reusing a name does not transfer it. See Job access.
  • Isolated teams' processes write nothing that others load. A team's processes now use virtual environments of their own (<root>/team_scopes/<team id>/venvs, their MRSM_VENVS_DIR), copied from the server's environment of each of the team's plugins the first time; what a team's code installs at run time lands in its copy only. The server's virtual environments of the team's plugins, which the server, the open side and other teams granted the same plugin also import, are no longer writable by the team, and the locks of the team's environments are kept in its own cache directory.
  • Meerschaum's local channels trust only their own peer. The server and its Python workers now talk over a socket pair the worker inherits instead of a socket the server listened on, which another process of the same user could connect to before the worker and receive its calls. The Python API host requires its per-start token on its Unix socket too (it did on Windows' TCP port), so a process that connects to the socket directly gets 403 instead of bypassing the server's checks; the host drops the token from its environment before importing plugins. The web terminal runs without tmux, whose socket runs commands for whoever connects, only where code an isolated team chose could reach it (see the Unix-socket filter below).
  • The sandbox says how much it covers. Where isolated teams' sandbox is enforced, the server's start-up log, mrsm doctor, a team worker's handshake report and a team job's first log line name its level: filesystem only (Linux 5.13 to 7.0, where Landlock cannot deny Unix sockets: see the seccomp filter below) or filesystem and sockets (Linux 7.1 or newer). Where Unix sockets are not denied to team code by either, while isolated teams exist, the server warns once at start, and mrsm doctor warns too, naming the reachable sockets of concern (the D-Bus session bus, Docker and Podman, the user's tmux server) and what to do. New value require_sockets for system.engine.python_team_sandbox: run teams' code only where Unix sockets are denied to it and its signals are scoped. The container-socket warning is part of this one now.
  • Unix socket restrictions for isolated teams (Linux). Where Landlock cannot deny them (before Linux 7.1, "filesystem only"), a team's process installs a seccomp filter right after Landlock and before any of the team's code runs: creating a Unix socket fails ("Address family not supported by protocol"), and so do datagram socket pairs, io_uring_setup and the x32 numbers, while a process using another architecture's system calls (the 32-bit int 0x80 entry) is killed. Connected socket pairs (asyncio, multiprocessing, pipes) and the process's channel to the server keep working. Under the filter, team workers make spawn the default multiprocessing start method (forkserver needs a Unix socket and now fails with a message naming the cause) and run Manager() over loopback TCP. Every status (start-up log, mrsm doctor, a worker's handshake, a team job's first log line) says whether Unix sockets are denied to team code and by which mechanism (Landlock, the seccomp filter, or not at all), a worker proves the filter by failing to create a Unix socket, and require_sockets accepts either mechanism (with signal scoping, Linux 6.12). Web terminals keep tmux, and so survive reloads, dropped connections and server restarts, except while an isolated team that may install its own plugins exists on a server where Unix sockets are not denied to team code (a container runtime that refuses seccomp(), an unsupported architecture, the sandbox off); the server decides from a probe process that applies the sandbox as a team process would, at start-up and after team changes. The warnings about a reachable session bus or container socket now appear only where Unix sockets are not denied. See How much the sandbox covers and Terminals without tmux.
  • Helper programs no longer inherit Meerschaum's secrets. Editors, SQL clients, pip / uv / pipx, cargo, systemctl, ps, docker checks, version probes and the like now start without MRSM_CONFIG, MRSM_PATCH, their _FILE forms and MRSM_<TYPE>_<LABEL> connector variables (a URI or a JSON object). Commands you ask Meerschaum to run (mrsm sh, mrsm os, !command, a word that is not an action, a job's shell command) keep the whole environment, so one that runs mrsm again sees the same configuration; Meerschaum's own processes and the stack's docker compose keep it too. See Processes that are not Meerschaum.
  • The stack's Valkey requires a password (upgrading users, read this). Valkey's images ignore VALKEY_PASSWORD, so the stack's Valkey accepted clients without a password on its published port. mrsm stack now starts it with requirepass set to valkey:main's password, from a file under <root>/stack/secrets/valkey/, and the next mrsm stack up -d recreates it on its existing volume; the API container and valkey:main keep connecting. When valkey:main has no password, one is generated and mrsm stack says how to point valkey:main at it. See Credentials in files.
  • Files that hold credentials are readable by their owner only. stack/docker-compose.yaml when it still holds credentials (an API image that keeps the environment form, a service of your own with a password), and the properties.json of jobs an API server creates, which record the server's environment; such a job's MRSM_CONFIG / MRSM_PATCH go to its owner-only files in its directory instead of properties.json. Existing files are tightened when they are next written.
  • meerschaum.connectors.poll.retry_connect() (used when a SQL connector waits for its database) no longer puts the connector's attributes, its password among them, on the command line of the process it starts, where other users of the host could read them with ps: they travel in an owner-only temporary file the process removes.
  • meerschaum.connectors.poll.retry_connect() retries sql, valkey and api connectors inside the running process, so waiting for an instance (a SQL connector built with wait=True, or your own call) no longer starts a second Python interpreter, writes a temporary file or needs any Python package, and a failed attempt says why (sql:main: cannot connect to localhost:5432 (connection refused). Is the database running?). Enter still retries at once, q quits, Ctrl-C interrupts, and an attempt against a server that never answers ends after the connector's connect_timeout (two of them for an API instance) and a second. Plugin connectors keep the child process and its owner-only file.
  • A job's prompts can be answered again. A job waiting for input (a question from Meerschaum or a plugin, a plugin's input(), a shell read, a program the job started) was never seen as waiting, so attach job and the job log websocket never sent it what was typed, and a plugin's input() in a job read nothing. The process that runs the job now keeps input.stdin.block while anything in the job waits for input (on Linux it sees the wait from outside, so isolated teams' sandboxed jobs are answered too; on macOS Meerschaum's own prompts announce it), show jobs says waiting for input, attach shows a plugin prompt()'s question as 4.x did, a job that asks before printing anything is answered (4.x waited for output first), and attach and the websocket stop waiting when the job ends. See Answer a job's prompts.
  • test_connection(warn=True) on a SQL or API connector says why a connection failed again, as in 4.x: the cause on standard output (sql:main: cannot connect to localhost:5432 (connection refused). Is the database running?, authentication failed for user ..., database "..." does not exist), then Connection to 'sql:main' failed. and Failed connection attempt (1 / 1). It printed nothing for a SQL connector with a configured schema, put "Could not determine the default schema" before the cause otherwise, and an API connector printed only Connection to ... failed.; 4.x printed no cause for an API connector either. Without warn nothing is printed, also no longer the "Failed to log into" warning for an API server that cannot be reached, which 4.x never printed (a server that refuses the credentials still warns once). A password or a URI is never printed. A Valkey connector's test_connection() raises with the cause, as before.
  • Plugin questions inside the interactive shell keep their line breaks, spacing and cursor position again, including plugin:noaa's station question during bootstrap pipes. Typing, backspace, defaults and terminal resizing behave as in a direct command; redirected output stays plain.
  • Security: a user who is not an administrator can run only Meerschaum actions through the API's action and job routes, the console's Execute box and MCP: a command whose word names no action, in any step, is now refused instead of running as a shell command on the server. Administrators are unaffected. 5.0.0 to 5.0.2 are affected.
  • Security: the web terminal of a user who is not an administrator is now restricted: each command runs only if the server would let that user run it through POST /execute, and the terminal starts no other program (no shell, !command, python, editor or SQL client), gives tmux's keys and command prompt nothing to act on, keeps its history to itself and forwards input only to jobs the user could have started; the same rule now applies to answering a job's prompts over the API, and a job a non-administrator creates through POST /jobs/{name} runs in the server's working directory and logs to the server's log file whatever its properties say (before, its cwd and logs.path were the caller's to choose, so a job could write its output to any file the server's user may write). Non-administrators now run a defined set of commands and nothing else (listed in Permissions), in the terminal and through POST /execute and the other action routes, each only on the pipes, Pipelines, jobs and tokens that user may act on through the API with the matching permission; a command that names jobs acts only on jobs that user may see and control over the job routes. A change of role closes the user's open terminals, and a demoted administrator's tmux session is ended rather than reattached. Administrators are unaffected. Through 5.0.2, webterm:use gave a full shell on the server.
  • Separate team executors. An administrator can select a team's execution environment: the main host, a generated Stack container or an independently managed native executor. The main API keeps sign-in, permissions and routing. Apply generated services with mrsm stack up -d. Separate executors require the same-release standalone native mrsm and a compatible Linux host. A launch is refused if the selected executor is unavailable. See Team execution environments for setup and migration.
  • Registered source reads and bounded InnoDB appends. API-only operations can read registered SQLite and GeoPackage sources in pages and explicitly approved PostgreSQL tables on the registration's own instance. MySQL and MariaDB can append complete signed integer and binary rows to an existing InnoDB table through the same main API. See PostgreSQL table reads and InnoDB appends.
  • API-only commands. Non-admin callers can list visible pipes, view their graph and run history, read named job logs, register or edit a Pipeline, and copy one pipe between two SQL instances served by the same main API. See commands under the caller's identity.
  • API-only web terminals. Signed-in operators can run permitted Meerschaum commands on the native Linux host or their team's selected Linux executor. Reconnecting to a live tmux session restores its windows. See API-only terminals.
  • Saved API-only pipe jobs. Save a single-pipe sync or verify job with optional data bounds and run it again through the jobs API. Scheduled, looping and automatically restarted jobs run each invocation under the creating user's or token's current access, with fresh relative bounds. Main preserves the next scheduled fire across restarts. See Saved sync and verify jobs.
  • SQLite BLOB columns through the API-only executor. A Team plugin can append binary data to its registered pipe through a configured service account on the same main API. SQLite preserves the bytes when the write adds a new nullable column.
  • Saved SQLite Pipelines on the API-only executor. Run independent pipes under one saved Pipeline revision and run ID. A Pipeline can also initialize or update children that share the same parents. Each child processes data up to the lowest committed parent watermark. Each target records its own native commit. The REST endpoint and HTTP MCP tool return the job name and run ID. See Run a saved SQLite Pipeline.
  • A provisioned remote Team executor can discover a granted single-file Rust plugin with its offline compiler. Main verifies the Factory’s signed completion receipt before caching the plugin’s declarations. See Plugin metadata and private handlers.
  • Host team execution. Members of an isolated team whose members may install, edit and upload plugins (who can already run any Python in the team's processes) may now run commands too, sh, python, !command and the rest, but only as the team's own sandboxed processes, and only where the server can hold them there: the sandbox not off, Unix sockets denied by Landlock or the proven seccomp filter, and signals scoped by Landlock, no container socket the sandbox misses, and a team process that proved its sandbox and a Python package that applies team scoping. POST /execute, POST /jobs/{name} and the console start such commands as jobs of the team that never start without the sandbox at that level; POST /actions/{action} and MCP's execute_action refuse members of isolated teams; their web terminal is a team terminal, the mrsm shell as a team process on a locked-down tmux server of the team's own; restricted and team terminals follow the rule that tmux is refused only while a team that may install plugins exists and Unix sockets cannot be denied to its code. A refusal names the condition that failed. Their processes can run any program the sandbox lets them reach, with the team's database credentials, and reach any network address the server can; nothing limits their CPU, memory or disk. Everyone else who is not an administrator keeps the commands listed in Permissions. mrsm doctor and the API server's start-up log show, per such team, whether team execution is available and why not. See Commands of a team that runs code.
  • The teams table's row menu is no longer clipped when the table is short.
  • The MCP docs show the bearer token in the form the server accepts (the API Key of a token).
  • The new upsert_changed_only parameter makes an upsert pipe on PostgreSQL, PostGIS, TimescaleDB, TimescaleDB-HA or Citus skip the update of rows whose values did not change, so a pipe that re-reads an overlapping window no longer rewrites identical rows (WAL, dead tuples, autovacuum). The sync message counts only the rows actually written.
  • An upsert pipe on the PostgreSQL family whose table has an array column (text[], integer[], ...) or an extension, enum or composite type column (citext, hstore, an enum, ...) upserts again: the update used to cast those values to the catalog's placeholder names (CAST(... AS ARRAY), CAST(... AS USER-DEFINED)), a syntax error. The values are now assigned without a cast, as the column converts them.
  • An in-place sync (a sql pipe whose definition runs on its own instance) of a table with an enum, citext, hstore or other extension-type column works on PostgreSQL and TimescaleDB without PostGIS. Every sync after the first failed (Failed to execute queries ... current transaction is aborted) because the sync looked for PostGIS geometry columns inside its transaction; the connector now checks once whether PostGIS is installed and skips the lookup when it is not.
  • An in-place sync works with columns that v4's NULL stand-in (-987654321) cannot fill: an enum, a range, interval, point and the other geometric types, an array, inet, time, xml or json on the PostgreSQL family; spatial and INET6 columns on MariaDB; xml, geography and hierarchyid on SQL Server; intervals, lists, structs and maps on DuckDB. It failed with invalid input value for enum ...: "-987654321" (also on an upsert pipe with children, whose sync checks which rows change) or COALESCE types interval and integer cannot be matched; such columns are now compared NULL-safely without the stand-in, as values and as keys.
  • An in-place upsert sync of a pipe keyed on primary into a TimescaleDB hypertable or a natively partitioned PostgreSQL table works: it failed with there is no unique or exclusion constraint matching the ON CONFLICT specification because the table's key also holds the datetime column; the upsert now conflicts on the table's own key, as a sync of a DataFrame does. On PostgreSQL and PostGIS, an in-place sync now creates a new table partitioned as a DataFrame sync would (a datetime column and hypertable not false) and creates the partitions new rows need, which failed with no partition of relation ... found for row. In-place syncs into TimescaleDB keyed on id, or on primary without upsert, are unchanged.
  • A Python list bound as a SQL parameter is an array again (upgrading from 5.0.x, read this). Since 5.0.0, conn.read(query, params={'ids': [1, 2, 3]}) (and exec / value) sent the list to PostgreSQL as jsonb, so id = ANY(:ids) failed with op ANY/ALL (array) requires array on right side. A list now binds as the array 4.x sent (integer[], text[], timestamp[], ...; an empty list matches nothing in = ANY(:ids)), a tuple as the row IN :ids expects, on MySQL and MariaDB a list or tuple expands into IN :ids, and on DuckDB a list is a LIST and a dict a STRUCT, as in 4.x. A dict or a list of dicts still binds as JSON on PostgreSQL. A list of plain values inserted into a json / jsonb column (or, on MySQL, used anywhere but IN / =) worked in 5.0.x and fails again as in 4.x: pass json.dumps(value).
  • A schedule with a time zone abbreviation after starting works again as in 4.x (--schedule 'daily starting 21:00 EDT' failed with Unknown string format). Either abbreviation of the host's own time zone (EST or EDT in America/New_York) is the host's zone, so the time follows that zone's offset on the date; UTC, GMT and Z are UTC; any other abbreviation (PDT on that host) is accepted with a warning in the job's log and the time is read as UTC, so give such a time as an offset (21:00 -07:00). Lowercase names (edt, utc) are an error, as in 4.x. Such a schedule keeps its wall-clock time across daylight-saving changes, as in 4.x (daily starting 21:00 EST runs at 21:00 EST in winter and 21:00 EDT in summer). At the change itself it no longer copies 4.x's slips: a time inside the skipped hour runs once just after it (4.x ran it an hour early, or skipped that day or month), hourly no longer runs twice at one instant in spring nor skips the repeated hour in autumn, and a cron time in the repeated hour runs once.
  • Schedules take a time zone: end one with tz <zone> (local, utc, or an IANA name) to read its times and cron fields on that zone's clock and keep its wall-clock time across daylight-saving changes, e.g. --schedule 'daily starting 21:00 tz local' or --schedule '0 21 * * mon-fri tz America/New_York'. It works with jitter (... tz local jitter 5 minutes), in pipe and compose schedule: values and in meerschaum.utils.schedule.parse_schedule(), and show schedules prints fire times with the zone's offset. See Time zones. jitter 0 forces exact times when a default jitter is configured.
  • upgrade meerschaum asks first, then works. "Upgrade this installation?", "Pull the stack's new Docker images?" (default yes) and "Bring up the stack after upgrading?" (default no) are all asked before anything is downloaded or installed, and the stack questions only when Docker is available and the root has a stack; the installation, the pull and stack up -d then run without asking. The new --no-pull flag skips the pull without asking. Bringing the stack up without pulling says it uses the images already on the host, and a failed pull is reported after the installation's own result and leaves the stack as it was. See Upgrading an installation.
  • upgrade meerschaum upgrades a Python installation where it lives (upgrading from 5.0.x, read this). A pip install --user installation was upgraded with uv pip into the interpreter's system site whenever uv was installed, which failed with a permission error (/usr/local/lib64/python3.15/site-packages/ on Fedora). The upgrade now asks the interpreter where its meerschaum lives and installs there: the user site with pip install --user, a virtual environment as before, and a system location only when it is writable; otherwise, and for an interpreter marked externally managed (PEP 668, Debian and Ubuntu), an editable installation or a package manager's copy, it stops before changing anything and prints the command to run. After installing it checks that the new copy is the one imported, and names the path of an older copy that shadows it; mrsm doctor names the copies an older one shadows too. 5.0.x still runs its own upgrade code, so upgrade a user-site installation from 5.0.x with python3 -m pip install --user --upgrade meerschaum.

Installation

Install with pip install --upgrade meerschaum or cargo install meerschaum --locked (Rust 1.95 or newer). Standalone mrsm binaries for Linux (x86_64, arm64; glibc 2.28 or newer), macOS (arm64, x86_64) and Windows (x86_64) are attached along with SHA256SUMS; the macOS binaries are not signed or notarized (run xattr -d com.apple.quarantine mrsm-... once). For Docker, pull bmeares/meerschaum:5.1.0 (or latest, 5.1.0-full).

The experimental free-threaded Python wheel (cp314t) is omitted from this release.