Database setup

Generated services target PostgreSQL-compatible data behavior through the selected framework ORM. Use PGlite for a low-setup local TypeScript workflow or connect the generated service to PostgreSQL.

Local PGlite

The TypeScript quickstart can run an embedded database in the Node.js process:

DATABASE_TYPE=pglite
DATABASE_SYNC=true
APP_PORT=3100

This is useful for generation checks and local CRUD development. Use apso migrate to test persisted schema changes through the migration sandbox.

Local PostgreSQL

Start PostgreSQL with Docker:

docker run --name apso-postgres \
  -e POSTGRES_USER=apso \
  -e POSTGRES_PASSWORD=apso \
  -e POSTGRES_DB=project_api \
  -p 5432:5432 \
  -d postgres:16

Configure the generated project using its framework convention:

DATABASE_TYPE=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=apso
DATABASE_PASSWORD=apso
DATABASE_NAME=project_api
DATABASE_SCHEMA=public
DATABASE_SYNC=false

DATABASE_TYPE=postgres
DATABASE_URL=postgresql+asyncpg://apso:apso@localhost:5432/project_api
DATABASE_SYNC=false

DATABASE_URL=postgresql://apso:apso@localhost:5432/project_api?sslmode=disable
DATABASE_SYNC=false

Use the generated .env.example and database configuration as the source for the project because template variables can change.

Synchronization and migrations

DATABASE_SYNC=true asks the local framework to synchronize models automatically. Limit it to disposable development data.

For reviewed schema changes:

apso schema validate
apso generate
apso migrate

Then run the language-native migration command included by the template.

Hosted service database

Apso Cloud provisions database resources for a hosted deployment. Manage application variables in the service Environment view and use the service operational views available for the selected plan. Do not copy production database credentials into a local .env unless the access is explicitly required and controlled.

Existing PostgreSQL data

When connecting to an existing database:

1. Back up the database through its provider.
2. Introspect and compare the existing schema with .apsorc.
3. Set an explicit table property when generated naming must preserve an existing table.
4. Run migration generation without applying it.
5. Review type conversions, defaults, nullability, indexes, and foreign keys.
6. Test against a restored non-production copy.

For Supabase PostgreSQL, apso import supabase can create a local .apsorc from a read-only schema inspection.

Diagnose connections

docker ps
pg_isready -h localhost -p 5432
psql "postgresql://apso:apso@localhost:5432/project_api" -c "select 1"

If the service still fails, compare the generated framework’s database variables with the active .env, confirm SSL requirements, and check that the process can resolve and reach the host.