Access separation
Create separate database identities for applications, developers, or automation within a branch.
Neon · Const
Role
A Neon role is a branch-scoped PostgreSQL role used for database access and ownership. Neon provides role management through the Console, CLI, API, or SQL, with different default privileges depending on the creation method.
How it works
A Neon project starts with a Postgres role named from its database, and roles are scoped to individual branches. Roles made through Neon management interfaces receive elevated neon_superuser membership, while SQL-created roles begin with limited public-schema access and need explicit grants.
Key points
- Neon uses standard PostgreSQL roles rather than a separate proprietary identity type.
- A new project receives an initial role whose name is derived from the database name.
- The initial database role owns the database on the project's default branch.
- Role creation is available on both the default branch and branches derived from it.
- The Console, CLI, and API support the main lifecycle operations for roles, including password resets.
Common mistakes
- A branch cannot contain more than 500 roles.
Example: Inspect the current Postgres role
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL!);
const result = await sql`SELECT current_user`;
console.log(result);Runs a query that returns the role used by the connection.
When to use it
Branch-specific environments
Use child branches for isolated development or testing while keeping role definitions branch-local.
Least-privilege access
Grant only the permissions an SQL-created application role needs instead of using broad administrative access.
Interview questions
QWhat is a Neon role, and how is the initial role named?
A Neon role is a PostgreSQL role associated with a branch. The initial role is named after the database, using a pattern such as neondb_owner, and owns the database on the default branch.
Follow-up: How would you restrict a role created through SQL? Grant only the required database, schema, table, and sequence privileges because SQL-created roles start with basic public-schema access.
QWhat is the scope and limit of a Neon role?
Roles are branch-scoped, so a role belongs to the branch where it is created. Neon limits each branch to 500 roles.
Follow-up: What design consequence follows? Role inventories must be managed independently per branch, especially when using many development or test branches.
QHow do management methods affect role privileges?
Roles can be managed through the Console, CLI, or API, and they can also be managed with SQL. Interface-created roles automatically receive neon_superuser membership, which includes capabilities such as CREATEDB, CREATEROLE, BYPASSRLS, and REPLICATION.
Follow-up: When is SQL preferable? Use SQL when you need narrowly controlled privileges, then explicitly grant the permissions required by the application.
Related
neon_superuserCREATEDBCREATEROLEBYPASSRLSREPLICATIONneon roles create