⏯️ Actions¶

Actions are commands for managing your Meerschaum instance and are a great way to perform bulk operations.

Syntax¶

Actions follow a simple verb-noun syntax (singular or plural):

bootstrap pipes
show pipes
sync pipes
verify pipes
clear pipes
drop pipes
delete pipes

Run mrsm (python -m meerschaum) to execute actions from the Meerschaum shell:

$ mrsm
[ mrsm@sql:main ] ➤ show pipes

Or run actions directly from the command line:

$ mrsm show pipes

Chaining Actions¶

Join actions with + to run them in a single process (similar to && in bash):

sync pipes -i sql:local + \
sync pipes -i sql:main

Flags added after : apply to the entire pipeline:

show version + show arguments : --loop

sync pipes -c plugin:noaa + \
sync pipes -c sql:main : -s 'daily starting 00:00' -d

You can escape : with ::, e.g. mrsm echo :: will output :.

Here are some useful pipeline flags:

• --loop
  Run the pipeline commands continuously.
• --min-seconds (default 1)
  How many seconds to sleep between laps (if --loop or x3).
• -s, --schedule, --cron
  Execute the pipeline on a schedule.
• -d, --daemon
  Create a background job to run the pipeline.
• x3, 3
  Execute the pipeline a specific number of times.

Note that you can add : to single commands as well:

mrsm show version : x3

Daemonize Actions¶

Add -d to any action to run it as a background job.

mrsm sync pipes -s 'every 3 hours' -d

This works well when chaining actions to create a pipeline job:

sync pipes -i sql:local + \
sync pipes -c sql:local : -s 'daily starting 10:00' -d

bash Actions¶

Any bash command may be run as an action. This is a great way to run shell scripts through Meerschaum.

mrsm /path/to/script.sh -s 'every 5 minutes' -d

Subaction Pattern¶

Most actions take a subaction (the noun) that selects what to operate on — usually pipes, but also plugins, users, connectors, jobs, config, venvs, and more:

register pipes        register plugins        register users
show pipes            show plugins            show jobs
delete pipes          delete connectors       delete jobs

Most subactions accept the standard pipe selectors (-c/--connector-keys, -m/--metric-keys, -l/--location-keys, -t/--tags, -i/--instance) so you can scope operations to a subset of pipes. Run mrsm <action> --help (or show help <action>) to see the full list of flags for any action.

Action Reference¶

Pipe Lifecycle¶

Create, edit, duplicate, and remove pipes (and their registrations).

edit¶

Edit the parameters of an existing element. edit pipes opens the selected pipes' parameters in your $EDITOR as YAML; saving persists the changes. edit config opens the configuration registry, and edit users edits user attributes.

mrsm edit pipes -c plugin:noaa -m weather

copy¶

Duplicate pipes or connectors. copy pipes clones the registration (and optionally the data) of the selected pipes into new keys, which is handy for branching a stream onto a new instance.

mrsm copy pipes -c plugin:noaa -m weather -i sql:local

Syncing & Data¶

Move data into pipes and manage what's already stored.

deduplicate¶

Scan pipes' target tables for duplicate rows (rows sharing the same index columns) and remove them, working chunk-by-chunk across the datetime axis so large tables stay manageable. Useful after a misconfigured sync or schema change introduced duplicates.

mrsm deduplicate pipes -c plugin:noaa -m weather --begin 2024-01-01

flush vs. clear¶

These both remove data, but differ in scope:

• clear pipes deletes rows from the existing table within a window (defaults to everything; narrow with --begin / --end / --params). The table and registration stay intact.
• flush pipes is destructive-then-rebuild: it drops the pipe's data (and indices) and re-syncs from the source, effectively recreating the pipe's contents from scratch.

# Remove rows on/after 2024-01-01 but keep the table.
mrsm clear pipes -c plugin:noaa -m weather --begin 2024-01-01

# Wipe and rebuild the pipe entirely.
mrsm flush pipes -c plugin:noaa -m weather

Bare clear (no subaction) just clears the terminal screen.

Maintenance¶

Optimize storage and statistics for pipes' target tables. See Pipe Maintenance for the full guide and per-flavor behavior.

index¶

Create the indices declared in each pipe's parameters['indices'] (plus the implicit datetime/id indices) on the target table. Run it after editing a pipe's indices, or to (re)build indices on a table that was created externally.

mrsm index pipes -c plugin:noaa -m weather

partition¶

Repartition natively range-partitioned tables (PostgreSQL/PostGIS, MySQL/MariaDB, MSSQL with hypertable: True, or TimescaleDB hypertables) to a new chunk width. On TimescaleDB this changes the interval for future chunks; on other flavors the table is rebuilt (read, dropped, re-synced) at the new width.

# Rebuild the 'weather' pipes' tables into 7-day partitions.
mrsm partition pipes -m weather --chunk-minutes 10080

Plugins & Packages¶

Manage Meerschaum plugins and their Python dependencies.

Instances & API¶

Run servers, control jobs, and connect to remote instances.

Utility & Shell¶

Inspect state and drop down to the shell, Python, or SQL.

sql¶

Interact directly with a SQL connector. With no arguments it opens an interactive CLI on sql:main; otherwise {label} {method} {query/table} reads a table/query into a DataFrame (read) or executes a statement (exec).

mrsm sql                                   # interactive CLI on sql:main
mrsm sql local table                       # SELECT * FROM table on sql:local
mrsm sql "SELECT * FROM users WHERE id = 1"  # run a query on sql:main
mrsm sql local exec "INSERT INTO t (id) VALUES (1)"