tcb db execute
Run one SQL statement in a PG mode or MySQL environment and return the result set. The parameters differ between the two modes.
Version
tcb db execute in PG mode has been available since v3.4.0.
Usage
tcb db execute --sql '<sql>' [options]
PG mode parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
-s, --sql <sql> | Yes | SQL statement to execute | — |
--role <role> | No | Role used to execute the statement, a valid custom role can be passed | — |
-e, --env-id <envId> | Yes | Environment ID | — |
--json | No | Output the result in JSON format | — |
PG mode examples
# Basic query
tcb db execute -e <envId> --sql "SELECT 1"
# List storage buckets
tcb db execute -e <envId> --sql "SELECT name, public FROM storage.buckets ORDER BY created_at"
# Run a query with a read-only role to avoid accidental writes
tcb db execute -e <envId> --role <readonly_role> --sql "SELECT name, public FROM storage.buckets"
# Create a storage bucket
tcb db execute -e <envId> --sql "INSERT INTO storage.buckets (id, name, public, created_at, updated_at) VALUES ('avatars', 'avatars', false, now(), now())"
MySQL mode parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
-s, --sql <sql> | Yes | SQL statement to execute | — |
--readOnly | No | Execute in read-only mode, suitable for queries and prevents accidental writes | false |
--instanceId <id> | No | Instance ID, required when an environment has multiple instances | — |
-e, --env-id <envId> | No | Environment ID | — |
--json | No | Output JSON | — |
# Query in read-only mode
tcb db execute --sql 'SELECT * FROM users LIMIT 10' --readOnly -e my-env-id
# Write operation
tcb db execute --sql "INSERT INTO orders (user_id, amount) VALUES (1, 99.9)" -e my-env-id
# Query a specific instance
tcb db execute --sql 'SHOW TABLES' --instanceId inst-xxx --readOnly -e my-env-id
Notes
--roleaccepts the application rolesanon,authenticated, or a custom role. Read-only execution needs a role without write permissions- Platform reserved roles are not exposed to users, passing one may fail with permission error
42501 - Statements run directly on the server with no local preview step, confirm the scope with a query before changing data
- The document database does not use this command, use
tcb db nosql execute
Related Commands
- Create a migration file: manage schema changes with migration files
- Declarative deployment: run migrations through
tcb deploy - PG mode storage: buckets and objects in the
storageschema