Commands
Every command-line tool Propus ships, with its options and defaults.
On this page: propus · serve options · propus migrate · install.sh · propus-generate · Environment variables · Test scripts
propus
| Command | Does | Server |
|---|---|---|
propus init --data <dir> [--encrypt --key-file <file>] [--public-url <url>] | Creates a server's data directory. Prints the server admin key once and the setup link for the console's owner. --key-file is created if missing | – |
propus serve --data <dir> [options] | Runs the server. See serve options | – |
propus setup-link --data <dir> [--public-url <url>] | Prints a new one-time link that creates the console's single account | running or stopped |
propus recovery-link --data <dir> --email <email> [--public-url <url>] | Prints a one-time link that sets a new password | running or stopped |
propus backup --data <dir> --database <name> --out <file> [--key-file <file>] | Backs up one database | stopped |
propus restore --data <dir> --database <name> --backup <file> [--key-file <file>] | Restores one database; the backup's SHA-256 manifest is checked first | stopped |
propus rotate-key --data <dir> --key-file <file> --new-key-file <file> | Re-wraps the data key under a new key file | stopped |
propus promote --data <dir> | Makes a running replica a primary that takes writes | running |
propus replication --data <dir> | Prints the server's role, its replicas or its primary, and how far behind each is | running |
propus migrate … | Brings data in from another system. See propus migrate | running |
propus version | Prints the version | – |
On an installed server, leave out --data: the settings come from /etc/propus/propus.env, so sudo propus setup-link is enough. While the server is running, backups can also be taken from the console or POST /v1/db/<name>/backups.
serve options
| Option | Default | For |
|---|---|---|
--listen <addr:port> | 127.0.0.1:7900 | HTTPS API, console, S3 |
--public-url <url> | – | The address the console is opened at (links, URLs shown) |
--tls-cert <pem> --tls-key <pem> | plain HTTP | TLS for everything. Without it, keep the server on loopback or behind a TLS proxy |
--pg-listen <addr:port> / --pg-public <host:port> | off | PostgreSQL protocol, and the address clients use |
--cache-listen <addr:port> / --cache-public <host:port> | off | Redis protocol (FlashCache) |
--kafka-listen <addr:port> / --kafka-public <host:port> | off | Kafka protocol (PulseStream) |
--protocol-tls-cert <pem> --protocol-tls-key <pem> | – | TLS for the three protocols only, when a proxy handles HTTPS. Certificates reload when their files change |
--cache-mb <n> | 256 | FlashCache memory before eviction |
--object-max-mb <n> | 5120 | Largest object |
--object-versions <n> | 5 | Versions kept per object in versioned buckets |
--backup-dir <dir> | off | Turns on scheduled, integrity-checked backups |
--backup-every <hours> | 24 | How often |
--backup-keep <n> | 7 | How many to keep |
--slow-ms <n> | 100 | Queries slower than this are kept with their plans |
--no-console | console on | Serve the API only |
--replication-secret-file <file> | – | A shared secret (16+ characters) replicas present. On a primary it turns on serving replicas; a replica needs the same file |
--replica-of <primary URL> | – | Runs as a read replica of that primary. Needs the primary's --key-file when it is encrypted |
--primary-ca <pem> | system roots | The CA that signed the primary's certificate |
--synchronous-replicas <n> | 0 | A commit returns once n replicas have it |
--synchronous-timeout <seconds> | 10 | How long a commit waits for them before going ahead (counted in propus replication) |
--failover-after <seconds> | off | A replica promotes itself when the primary has been unreachable this long |
--replication-log-mb <n> | 256 | Commits kept for replicas to catch up from; further behind, a replica copies a fresh snapshot |
propus migrate
propus migrate --from <source URL> --to <database URL> [--copy-only] [--prefix <p>] [--tables <a,b>] [--yes]
propus migrate status --to <database URL> [--id <id>]
propus migrate cutover --to <database URL> --id <id> [--no-fence]
propus migrate rollback --to <database URL> --id <id>
propus migrate cancel --to <database URL> --id <id>
| Option | Does |
|---|---|
--copy-only | Copy once and finish; don't follow changes |
--prefix <p> | Prefix for the tables created in Propus (when a name is already taken) |
--tables <a,b> | Only these source tables |
--yes | Start without asking after the inspection report |
--no-fence | Cut over without making the source read-only (SQLite, Kafka and S3 have no fence: stop the app) |
The target is the database URL from the console (propus://<db>:<secret>@host/<db>); PROPUS_URL can hold it instead of --to.
| Source | URL |
|---|---|
 PostgreSQL 10+ | postgres://user:pass@host:5432/db?sslmode=require |
 MySQL 5.7+, MariaDB | mysql://user:pass@host:3306/db?ssl-mode=REQUIRED |
 SQLite | sqlite:///path/to/file.db |
 Redis, Valkey | redis://:pass@host:6379 or rediss:// |
 Kafka 2.4+ | kafka://user:pass@host:9092?sasl=scram-sha-512&tls=true (sasl=plain, scram-sha-256; topics=a,b, groups=g1) |
 S3 and compatible | s3://KEY:SECRET@host/bucket |
install.sh
install.sh [--url <release base URL> | --from <dir>] [--version <v>]
[--port 7900] [--public-url https://db.example.com]
[--tls-cert <pem> --tls-key <pem>] [--no-encrypt] [--no-firewall]
[--backup-every 24] [--backup-keep 7]
[--pg-port <n>] [--redis-port <n>] [--kafka-port <n>]
[--trust-key <pem>]
install.sh --upgrade [--url … | --from …] [--version <v>]
install.sh --rollback
install.sh --uninstall [--purge]
| Option | Does |
|---|---|
--url / --from | Where the release is: a web address, or a folder of downloaded release files |
--version | A release version (default latest) |
--port | The HTTPS port (default 7900) |
--pg-port, --redis-port, --kafka-port | Turn on those protocols, over TLS |
--no-encrypt | Store data unencrypted (encrypted by default) |
--no-firewall | Leave ufw / firewalld alone |
--trust-key <pem> | Trust your own signing key for your own builds |
--upgrade | Verify, install, restart; rolls back by itself if the health check fails |
--rollback | Back to the previous version |
--uninstall [--purge] | Remove Propus; --purge also removes data, keys, backups and the propus account |
propus-generate
Comes with the JavaScript SDK (npx propus-generate).
propus-generate --url <database URL> --lang typescript|python|java|csharp [--namespace X] [--out file]
propus-generate --migration <name> --schema <module exporting tables> [--drop] [--out file]
The first prints row types and table definitions from the live schema (like prisma generate / db pull). The second writes the difference between your tables and the database as a SQL migration with -- up and -- down parts (like prisma migrate dev). See sdks.md.
Environment variables
Every serve option has one. The installed server keeps them in /etc/propus/propus.env.
| Variable | Option |
|---|---|
PROPUS_DATA, PROPUS_KEY_FILE | --data, --key-file |
PROPUS_LISTEN, PROPUS_PUBLIC_URL | --listen, --public-url |
PROPUS_TLS_CERT, PROPUS_TLS_KEY | --tls-cert, --tls-key |
PROPUS_PG_LISTEN, PROPUS_PG_PUBLIC | --pg-listen, --pg-public |
PROPUS_CACHE_LISTEN, PROPUS_CACHE_PUBLIC, PROPUS_CACHE_MB | --cache-listen, --cache-public, --cache-mb |
PROPUS_KAFKA_LISTEN, PROPUS_KAFKA_PUBLIC | --kafka-listen, --kafka-public |
PROPUS_PROTOCOL_TLS_CERT, PROPUS_PROTOCOL_TLS_KEY | --protocol-tls-cert, --protocol-tls-key |
PROPUS_OBJECT_MAX_MB, PROPUS_OBJECT_VERSIONS | --object-max-mb, --object-versions |
PROPUS_BACKUP_DIR, PROPUS_BACKUP_EVERY_HOURS, PROPUS_BACKUP_KEEP | --backup-dir, --backup-every, --backup-keep |
PROPUS_SLOW_MS, PROPUS_NO_CONSOLE | --slow-ms, --no-console |
PROPUS_REPLICATION_SECRET_FILE, PROPUS_REPLICA_OF, PROPUS_PRIMARY_CA | --replication-secret-file, --replica-of, --primary-ca |
PROPUS_SYNCHRONOUS_REPLICAS, PROPUS_SYNCHRONOUS_TIMEOUT | --synchronous-replicas, --synchronous-timeout |
PROPUS_FAILOVER_AFTER, PROPUS_REPLICATION_LOG_MB | --failover-after, --replication-log-mb |
PROPUS_TX_IDLE_SECONDS | Interactive transactions idle longer are rolled back (default 60) |
PROPUS_CHANGES_KEEP | Change-feed entries kept per database (default 1,000,000) |
PROPUS_URL | Read by the SDKs, propus migrate and propus-generate |
Test scripts
See testing.md. tests/all.sh runs everything with a summary.