Skip to content

ptkl ratchet

Manage Ratchet database connections and run queries against them from the command line.

Overview

Ratchet is the platform's managed external-database connector — it lets a project register a connection to an external database (and, per connection, a set of predefined saved queries), then run those queries (or ad-hoc ones) through the platform's gateway. ptkl ratchet exposes the full connection lifecycle plus query execution, mapping 1:1 onto the SDK Ratchet client (@ptkl/sdk/beta).

Subcommands

Subcommand Description
connection list List all database connections for the current project
connection get Get a database connection by ID
connection create Create a new database connection
connection update Update an existing database connection
connection delete Delete a database connection
test Test a connection configuration without saving it
query Execute a predefined (saved) query
inspect Run an ad-hoc query against a connection without saving it

ptkl ratchet connection list

List all database connections for the current project.

ptkl ratchet connection list

ptkl ratchet connection get

Get a database connection by ID.

ptkl ratchet connection get -i <id>

Options

Option Description
-i, --id <id> Connection ID (required)

Example

ptkl ratchet connection get --id my-postgres

ptkl ratchet connection create

Create a new database connection.

ptkl ratchet connection create -d <json>

Options

Option Description
-d, --data <json> Connection configuration as a JSON string (id, type, credentials) (required)

Example

ptkl ratchet connection create --data '{
  "id": "my-postgres",
  "type": "postgres",
  "credentials": { "host": "db.example.com", "port": 5432, "database": "app", "user": "app", "password": "***" }
}'

ptkl ratchet connection update

Update an existing database connection. This can also be used to add or edit the connection's saved queries.

ptkl ratchet connection update -d <json>

Options

Option Description
-d, --data <json> Connection configuration as a JSON string (id, type, credentials, queries) (required)

Example

ptkl ratchet connection update --data '{
  "id": "my-postgres",
  "queries": [
    { "id": "active-users", "sql": "SELECT * FROM users WHERE active = $1" }
  ]
}'

ptkl ratchet connection delete

Delete a database connection.

ptkl ratchet connection delete -i <id>

Options

Option Description
-i, --id <id> Connection ID (required)

Example

ptkl ratchet connection delete --id my-postgres

ptkl ratchet test

Test a database connection configuration without saving it. Useful for validating credentials before running connection create.

ptkl ratchet test -d <json>

Options

Option Description
-d, --data <json> Connection configuration as a JSON string (id, type, credentials) (required)

Example

ptkl ratchet test --data '{
  "id": "my-postgres",
  "type": "postgres",
  "credentials": { "host": "db.example.com", "port": 5432, "database": "app", "user": "app", "password": "***" }
}'

ptkl ratchet query

Execute a predefined (saved) query by its qualified name.

ptkl ratchet query -n <connectionId.queryId> [-p <json>]

Options

Option Description
-n, --name <name> Qualified query name, e.g. my-postgres.active-users (required)
-p, --params <json> Query params as a JSON array or object (default: [])

Example

ptkl ratchet query --name my-postgres.active-users --params '[true]'

ptkl ratchet inspect

Run an ad-hoc query against a connection without saving it first — useful while developing a query before promoting it to a saved query via connection update.

ptkl ratchet inspect -d <json>

Options

Option Description
-d, --data <json> Inspect request as a JSON string (name, query, params) (required)

Example

ptkl ratchet inspect --data '{
  "name": "my-postgres",
  "query": "SELECT * FROM users WHERE active = $1",
  "params": [true]
}'

Typical Workflow

# 1. Validate credentials before saving
ptkl ratchet test --data '{"id":"my-postgres","type":"postgres","credentials":{...}}'

# 2. Create the connection
ptkl ratchet connection create --data '{"id":"my-postgres","type":"postgres","credentials":{...}}'

# 3. Develop a query ad-hoc
ptkl ratchet inspect --data '{"name":"my-postgres","query":"SELECT 1","params":[]}'

# 4. Save it as a predefined query
ptkl ratchet connection update --data '{"id":"my-postgres","queries":[{"id":"ping","sql":"SELECT 1"}]}'

# 5. Run it
ptkl ratchet query --name my-postgres.ping

See Also