The psql command connects to a database in your OptiTech project using the psql client. It builds a connection string for the specified branch (or the default branch from your context file) and launches psql, equivalent to running optitech connection-string --psql as a dedicated top-level command. Requires optitech 2.22.2 or later. Check your version with optitech --version. If --project-id is omitted, the CLI resolves it from your context file, auto-selects when your account has only one project, and prompts otherwise. --role-name and --database-name are needed only when the branch has more than one role or database.
Usage
optitech psql [branch] [options] [-- psql-args]The [branch] is the branch name or ID. If omitted, the default branch from your context (or the project's default branch) is used. You can also use the point-in-time format branch@timestamp or branch@lsn for time travel connections. Arguments after -- are forwarded to psql.
Options
optitech psql uses the native psql binary from your $PATH if one is available, and otherwise falls back to a built-in TypeScript implementation, so no PostgreSQL client tools installation is required. The built-in implementation is a full port, not a simplified subset: it supports SCRAM-SHA-256 authentication, backslash commands (\d, \dt, \d+, etc.), tab completion, command history, and COPY. It's verified against Postgres 14 through 18.
To force the built-in implementation in CI or other environments where native psql is present but you want consistent behavior, set OPTITECHCTL_PSQL_FALLBACK=1.
Examples
Connect to the default branch:
optitech psqlConnect to a named branch. New OptiTech projects create a default branch named production:
optitech psql productionRun a single query:
optitech psql production -- -c "SELECT version()"Run an SQL file:
optitech psql production -- -f dump.sqlConnect to a branch at a specific point in time:
optitech psql production@2024-01-01T00:00:00ZUse a pooled connection:
optitech psql --pooled