Skip to main content

​
Default limits

These are the defaults for a self-hosted server. Operators can change them (see the configuration reference), so a managed deployment may use different values.

​
Compatibility notes

  • SQL dialect: SQL runs on DuckDB. Most PostgreSQL queries work unchanged, but functions and some syntax follow DuckDB. See SQL support.
  • Extended query protocol: prepared statements work for common use. If a driver fails on complex prepared-statement flows, switch it to the simple query protocol (for example autocommit=True in psycopg2, or preferQueryMode=simple in JDBC).
  • System catalogs: pg_catalog queries are answered by a compatibility layer, so some tools show partial metadata.
  • Extensions: only allowlisted DuckDB extensions can be installed or loaded.
  • Revoked credentials: revoking a credential blocks new logins. Connections that are already open aren’t terminated.

​
Troubleshooting

The database name in your connection doesn’t match an existing Airhouse database. Check the dbname parameter (psql -d). With the control plane, create the database first with POST /admin/v1/tenants. Without it, the database is named airhouse unless the operator changed it.
The username or password is wrong, the user belongs to a different database, or a minted credential has expired or been revoked. Mint a new credential, or check the user with GET /admin/v1/tenants/{id}/users.
Your role doesn’t allow the statement. Readers can only query; writers can’t run CREATE, ALTER, or DROP. Ask an admin to run the DDL or to give you a different role. See Users, roles, and security.
You’re using a schema-scoped writer and the statement writes outside its schemas, uses an unqualified table name, or uses a statement scoped writers can’t run. Qualify the table as schema.table in an allowed schema. See Schema-scoped writers.
Airhouse closes a session when it can’t determine the session’s role, for example when the credential expired or was revoked between login and the first query. Reconnect with a valid credential.
The query ran longer than the server’s query timeout. Narrow the query with filters, aggregate before returning results, or ask the operator to raise query_timeout_secs.
You sent more queries per minute than your user’s or database’s limit. Retry with backoff, or batch work into fewer queries.
The server can’t reach its user registry, so it rejects logins rather than letting them through. Retry shortly. If it persists, contact the operator.
The table was created outside the lake catalog, for example in DuckDB’s memory or temp catalog, or after a USE statement switched the session away from lake. Create persistent tables with fully qualified names such as lake.main.my_table.
Call conn.set_session(autocommit=True) right after connecting. See Connect from code.
The extension isn’t on the server’s allowlist. Operators can add it to allowed_extensions.