shipq.ini Reference

shipq.ini is the control plane for your ShipQ project. It lives at the project root and is read by every ShipQ command. This page documents every section and key.

File Format

Standard INI format with [section] headers, key = value pairs, and # or ; comments:

# This is a comment
; This is also a comment

[section_name]
key = value
another_key = another value

Keys and section names are case-insensitive. Values are trimmed of leading/trailing whitespace.

[db] — Database Configuration

The most important section. Controls database connectivity, dialect selection, and multi-tenant scoping.

Key	Type	Written by	Description
database_url	string	shipq db setup	Connection URL for the dev database. Determines which SQL dialect ShipQ uses for all code generation.
scope	string	Manual	Optional global scope column for multi-tenancy. When set, shipq migrate new auto-injects this column as a foreign key reference into every new table.

Supported database_url formats

Prefix	Dialect	Example
postgres:// or postgresql://	PostgreSQL	postgres://localhost:5432/myapp_dev?sslmode=disable
mysql://	MySQL	mysql://root:password@tcp(localhost:3306)/myapp_dev
sqlite://	SQLite	sqlite:///path/to/.shipq/data/myapp.db

Safety guard

For Postgres and MySQL, shipq db setup requires DATABASE_URL to point to localhost. This prevents accidental writes to production databases during development.

Scope example

[db]
database_url = postgres://localhost:5432/myapp_dev
scope = organization_id

When scope = organization_id is set:

• shipq migrate new injects organization_id:references:organizations into every new table (skip with --global)
• Generated queries include WHERE organization_id = ? automatically
• Generated handlers extract organization_id from the authenticated user’s context
• Generated tests include tenancy isolation verification

[auth] — Authentication

Created by shipq auth. Controls authentication behavior for handler generation.

Key	Type	Written by	Description
protect_by_default	bool	shipq auth	When true, all handlers generated by shipq resource require authentication. Pass --public to override per-resource.

[auth]
protect_by_default = true

[typescript] — TypeScript Client Codegen

Created by shipq init. Controls TypeScript client generation during shipq handler compile.

Key	Type	Written by	Description
framework	string	shipq init	Which framework helpers to generate alongside the base HTTP client. Options: react, svelte, or omit for plain TypeScript.
http_output	string	shipq init	Output directory for generated TypeScript files, relative to the project root.

[typescript]
framework = react
http_output = .

Framework options

Value	What gets generated
react	Base HTTP client + React hooks (query hooks, mutation hooks)
svelte	Base HTTP client + Svelte store-based helpers
(omitted or empty)	Base HTTP client only (zero framework dependencies)

[files] — File Uploads

Created by shipq files. Marks the file upload subsystem as enabled. Actual credentials are read from environment variables, not from the INI file.

Related environment variables

Variable	Description
S3_BUCKET	S3 bucket name
S3_REGION	AWS region (e.g., us-east-1)
S3_ENDPOINT	S3 endpoint URL. Empty for AWS S3; set for MinIO, R2, GCS.
AWS_ACCESS_KEY_ID	S3-compatible access key
AWS_SECRET_ACCESS_KEY	S3-compatible secret key

[workers] — Workers & Channels

Created by shipq workers. Configures the background job queue (Redis) and real-time WebSocket hub (Centrifugo).

Key	Type	Written by	Description
redis_url	string	shipq workers	Redis connection URL for the job queue.
centrifugo_url	string	shipq workers	Centrifugo HTTP API URL.
centrifugo_api_key	string	shipq workers	API key for server-to-Centrifugo authentication. Auto-generated.
centrifugo_secret	string	shipq workers	HMAC secret for signing Centrifugo WebSocket connection/subscription tokens (separate from the cookie-based HTTP auth system). Auto-generated.

[workers]
redis_url = redis://localhost:6379
centrifugo_url = http://localhost:8000
centrifugo_api_key = auto-generated-value
centrifugo_secret = auto-generated-value

[env] — Environment Variable Validation

Optional. Declare additional environment variables that must be present when running in production. ShipQ’s generated config loader validates these at startup and refuses to start if any are missing.

[env]
STRIPE_SECRET_KEY = required
SENDGRID_API_KEY = required
CUSTOM_FEATURE_FLAG = required

Each key under [env] is the name of an environment variable. The value should be required. At startup, the generated server checks that each declared variable is set and non-empty.

Section / Key Summary

Section	Key	Required	Written by
[db]	database_url	Yes	shipq db setup
[db]	scope	No	Manual
[auth]	protect_by_default	No	shipq auth
[typescript]	framework	No	shipq init
[typescript]	http_output	No	shipq init
[files]	(section presence)	No	shipq files
[workers]	redis_url	No	shipq workers
[workers]	centrifugo_url	No	shipq workers
[workers]	centrifugo_api_key	No	shipq workers
[workers]	centrifugo_secret	No	shipq workers
[env]	(any key)	No	Manual

Which Commands Read/Write What

Command	Reads	Writes
shipq init	—	[db], [typescript]
shipq db setup	DATABASE_URL env var	[db] database_url
shipq db compile	[db]	—
shipq migrate new	[db] scope	—
shipq migrate up	[db] database_url	—
shipq auth	[db]	[auth]
shipq signup	[db], [auth]	—
shipq files	[db]	[files]
shipq workers	[db], [auth]	[workers]
shipq workers compile	[db], [auth], [workers]	—
shipq resource	[db], [auth]	—
shipq handler compile	[auth], [typescript]	—
shipq docker	All sections	—

Best Practices

• Commit shipq.ini to version control. It’s build configuration, not secrets.
• Never store credentials in shipq.ini. Use environment variables for database passwords, API keys, S3 credentials, etc.
• Use shipq db setup to write database_url rather than editing it by hand.
• Set scope early — before creating any business-domain migrations.
• Declare production env vars in [env] so the generated server catches missing configuration at startup instead of at runtime.