Because SCHMA stores your content in your own PostgreSQL database, a valid, reachable database connection is required for workspace operation. If your database fails to connect or returns an error during setup, follow this structured diagnostic guide.

Quick diagnostic checklist

1. Confirm the active workspace: In the Studio top-left workspace picker, verify you have selected the intended workspace before testing credentials.
2. Verify database uptime: Log into your database provider (Neon, Supabase, AWS RDS, etc.) and ensure the database instance is running and not paused due to inactivity.
3. Check URL protocol: Ensure the URI begins with postgresql:// or postgres://.
4. Check SSL flag: Confirm ?sslmode=require is appended to the URI.
5. Confirm PostgreSQL 15+ & pgvector: Ensure your database is running PostgreSQL 15 or newer and has the pgvector extension available. Onboarding migrations require the database user to have permission to execute CREATE EXTENSION IF NOT EXISTS vector.
6. Complete setup: After the initial connection test succeeds, ensure you click Complete Setup so SCHMA can finish table provisioning.

Connection string syntax and password escaping

The single most common cause of authentication failure is special characters in database passwords that are not percent-encoded. The PostgreSQL connection parser interprets characters like @, :, /, ?, and # as URI delimiters.

SSL/TLS requirements and pooler configurations

Managed database providers require encrypted SSL connections over public networks. If your connection test hangs or reports SSL connection required, append ?sslmode=require to your connection string.

If you are using connection poolers (such as PgBouncer or Supabase connection pooling on port 6543), ensure the pooler is configured in Session mode or switch to the direct database connection (port 5432) during initial workspace setup. Transaction-mode poolers may disallow prepared statements or temporary DDL locks needed during schema migrations.

Network access and provider firewall rules

If your database server is protected behind a firewall or VPC network access list, external requests from SCHMA's cloud services will time out with ETIMEDOUT or Connection refused. Ensure your provider's network settings permit inbound connections from SCHMA or allow connections from 0.0.0.0/0 with SSL enforcement.

Database user permissions and table creation

The database user specified in your connection string must have privileges to create tables, schemas, and extensions (specifically pgvector) in the target database. PostgreSQL 15+ alone is insufficient if the user lacks permission to run CREATE EXTENSION IF NOT EXISTS vector. You can test your credentials locally with the psql command-line tool:

psql "postgresql://username:password@hostname:5432/databasename?sslmode=require"

If psql connects successfully from your terminal, check the Studio connection dialog for specific error codes or view our comprehensive diagnostic checks on the Troubleshooting hub.