BackendDatabases
PostgreSQL
Connect to PostgreSQL databases.
Connect to a PostgreSQL database and get full CRUD through a direct pg driver connection.
import { createEngine } from '@superapp/backend'
const engine = createEngine({
connections: {
main: process.env.PG_URL!,
},
})Connection URL Format
Standard PostgreSQL connection string:
postgres://user:password@host:5432/database?sslmode=require| Parameter | Description |
|---|---|
user | Database user |
password | Database password |
host | Server hostname or IP |
5432 | Port (default: 5432) |
database | Database name |
sslmode | disable, require, verify-ca, verify-full |
How It Works
When the engine starts, it detects the postgres:// protocol and initializes a connection pool using the pg driver. All tables in the target database become available under the main namespace. Queries are executed directly against Postgres with no intermediary.
Capabilities
| Operation | Supported |
|---|---|
findMany / findOne | Yes |
create | Yes |
update | Yes |
delete | Yes |
count / aggregate | Yes |
| Transactions | Yes |
Full Example
import { createEngine } from '@superapp/backend'
import { betterAuthProvider } from '@superapp/backend/auth/better-auth'
import { createHonoMiddleware } from '@superapp/backend/adapters/hono'
import { Hono } from 'hono'
import { serve } from '@hono/node-server'
const engine = createEngine({
connections: {
main: process.env.PG_URL!,
},
auth: betterAuthProvider({
secret: process.env.AUTH_SECRET!,
userTable: {
table: 'main.users',
matchOn: { column: 'id', jwtField: 'id' },
columns: ['id', 'email', 'name'],
},
}),
permissions: {
orders: {
table: 'main.orders',
select: {
roles: ['viewer'],
columns: ['id', 'amount', 'status', 'customer_id', 'created_at'],
},
},
},
})
const app = new Hono()
app.route('/', createHonoMiddleware(engine))
serve({ fetch: app.fetch, port: 3001 })Multiple Postgres Connections
Attach several Postgres databases under different names:
const engine = createEngine({
connections: {
main: process.env.PG_URL!,
analytics: process.env.ANALYTICS_PG_URL!,
},
})Tables are namespaced: main.orders, analytics.events.
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
Connection refused | Postgres not reachable | Check host, port, and firewall rules |
password authentication failed | Wrong credentials | Verify user/password in connection URL |
SSL connection required | Server requires SSL | Add ?sslmode=require to the URL |
relation does not exist | Table not in target database | Check database name in the URL |
too many connections | Pool exhausted on Postgres side | Increase max_connections or use a connection pooler like PgBouncer |