Projects
In SerenDB, the project is your main workspace. Within a project, you create branches for different workflows, like environments, features, or previews. Each branch contains its own databases, roles, computes, and replicas. Your SerenDB Plan determines how many projects you can create and the resource limits within those projects.
Default resources
When you add a new project, SerenDB creates the following resources by default:
Two branches are created for you by default:
production(your main branch for production workloads) anddevelopment(a child branch for development work). You can create additional child branches from either of these, or from any other branch. For more information, see Manage branches.A single primary read-write compute. This is the compute associated with the branch. For more information, see Manage computes.
A Postgres database that resides on the project's default branch. If you did not specify your own database name when creating the project, the database created is named
neondb.A Postgres role that is named for your database. For example, if your database is named
neondb, the project is created with a default role namedneondb_owner.Each SerenDB plan comes with a specific storage allowance. Beyond this allowance on paid plans, extra usage costs apply. Billing-related allowances aside, SerenDB projects can support data sizes up to 4 TiB. To increase this limit, contact the SerenDB Sales team.
Create a project
The following instructions describe how to create additional SerenDB projects. If you are creating your very first SerenDB project, refer to the instructions in Playing with SerenDB.
To create a SerenDB project:
Navigate to the SerenDB Console.
Click New Project.
Specify values for Project Name, Postgres version, Cloud service provider, and Region. Project names are limited to 64 characters.
Click Create Project.
After creating a project, you are directed to the Project Dashboard.
You can also use [pg.new](https://pg.new) to create a new SerenDB Postgres project. Simply visit [pg.new](https://pg.new) and you'll be taken directly to the **Create project** page where you can create your new project.
View projects
To view your projects:
Navigate to the SerenDB Console.
From the breadcrumb navigation menu at the top-left of the console, select your organization.
The Projects page lists your projects, including any projects that have been shared with you.
Project settings
Once you open a project, you can use the Settings page to manage your project and configure any defaults.
The Settings page includes these sub-pages:
General — Change the name of your project or copy the project ID.
Compute — Set the scale to zero and sizing defaults for any new computes you create when branching.
Instant restore — Set the restore window to enable instant restore, time travel queries, and branching from past states.
Updates — Schedule a time for Postgres and SerenDB updates.
Collaborators — Invite external collaborators to join your SerenDB project.
Network security — Configure SerenDB's IP and Private Networking features for secure access.
RLS — Configure SerenDB Row-Level Security (RLS) to apply row-level security policies to your SerenDB project.
Logical replication — Enable logical replication to replicate data from your SerenDB project to external data services and platforms.
Transfer — Transfer your project from the current organization to another organization you are a member of.
Delete — Use with care! This action deletes your entire project and all its objects, and is irreversible.
General project settings
On the General page, you are permitted to change the name of your project or copy the project ID. The project ID is permanent and cannot be changed.
Change your project's default compute settings
You can change your project's default compute settings on the Compute page. These settings determine the compute resources allocated to any new branches or read replicas you create.
Changes to default compute settings only affect **newly created computes**. Existing computes, including those on your primary branch and read replicas, will not be automatically updated. To change settings for existing computes, you need to update them individually through the **Branches** page.
A Compute Unit (CU) represents 1 vCPU with 4 GB of RAM. New branches inherit compute settings from your first branch, but you can change these defaults to:
Set smaller compute sizes for preview deployments and development branches
Standardize settings across read replicas
Optimize resource usage and costs for non-production workloads
SerenDB supports two compute configurations:
Fixed size: Select a fixed compute size ranging from .25 CUs to 56 CUs
Autoscaling: Specify minimum and maximum compute sizes (from .25 CU to 16 CUs) to automatically scale based on workload. Note: When setting maximum above 10 CUs, the minimum must be at least max/8. For more information, see Autoscaling
Configure your restore window
By default, SerenDB retains a history of changes for all branches in your project, enabling features like:
Instant restore for recovering lost data
Time Travel queries for investigating data issues
If you extend this restore window, you'll expand the range of data recovery and query options, but note that this will also increase your instant restore storage.
Also note that adjusting the restore window affects all branches in your project.
To configure the restore window for a project:
Select a project in the SerenDB Console.
On your Project Dashboard, select Settings.
Select Restore window.
Use the slider to select the restore window.
Click Save.
For information about restore window limits and default settings, see SerenDB plans.
Schedule updates for your project
To keep your SerenDB computes and Postgres instances up to date, SerenDB automatically applies scheduled updates that include Postgres minor version upgrades, security patches, and new features. Updates are applied to the computes within your project. They require a quick compute restart, take only a few seconds, and typically occur weekly.
On the Free plan, updates are automatically scheduled. On paid plans, you can set a preferred day and time for updates. Restarts occur within your selected time window and take only a few seconds.
To set your project's update schedule or view currently scheduled updates:
Go to Settings > Updates.
Choose a day of the week and an hour. Updates will occur within this time window and take only a few seconds.
For more information, see Updates.
Invite collaborators to a project
SerenDB's project collaboration feature allows you to invite external SerenDB accounts to collaborate on a SerenDB project.
Organization members cannot be added as collaborators to organization-owned projects since they already have access to all projects through their organization membership.
To invite collaborators to a SerenDB project:
In the SerenDB Console, select a project.
Select Settings.
Select Collaborators.
Select Invite and enter the email address of the account you want to collaborate with.
Click Invite.
The email you specify is added to the list of Collaborators. The SerenDB account associated with that email address is granted full access to the project, with the exception of privileges required to delete the project. This account can also invite other SerenDB users to the project. When that user logs in to SerenDB, the project they were invited to is listed on their Projects page under Shared with you.
The costs associated with projects being collaborated on are charged to the SerenDB account that owns the project. For example, if you invite another SerenDB user account to a project you own, any usage incurred by that user within your project is billed to your SerenDB account, not theirs.
For additional information, refer to our Project collaboration guide.
Configure IP Allow
The IP Allow feature provides an added layer of security for your data, restricting access to the branch where your database resides to only those IP addresses that you specify. In SerenDB, the IP allowlist is applied to all branches by default.
Optionally, you can allow unrestricted access to your project's non-protected branches. For instance, you might want to restrict access to protected branches to a handful of trusted IPs while allowing unrestricted access to your development branches.
By default, SerenDB allows IP addresses from 0.0.0.0, which means that SerenDB accepts connections from any IP address. Once you configure IP Allow by adding IP addresses or ranges, only those IP addresses will be allowed to access SerenDB.
SerenDB projects provisioned on AWS support both [IPv4](https://en.wikipedia.org/wiki/Internet_Protocol_version_4) and [IPv6](https://en.wikipedia.org/wiki/IPv6) addresses. SerenDB project provisioned on Azure currently on support IPv4.
<Tabs labels={["SerenDB Console", "CLI", "API"]}>
To configure an allowlist:
Select a project in the SerenDB Console.
On the Project Dashboard, select Settings.
Select Network security.
Under IP Allow, specify the IP addresses you want to permit. Separate multiple entries with commas.
Optionally, under Branch access, select Restrict IP Access to protected branches only to restrict access to only the branches you have designated as protected.
Click Save changes.
The SerenDB CLI ip-allow command supports IP Allow configuration. For example, the following add command adds IP addresses to the allowlist for an existing SerenDB project. Multiple entries are separated by a space. No delimiter is required.
neon ip-allow add 203.0.113.0 203.0.113.1
┌─────────────────────┬─────────────────────┬──────────────┬─────────────────────┐
│ Id │ Name │ IP Addresses │ Protected Only │
├─────────────────────|─────────────────────┼──────────────┼─────────────────────┤
│ wispy-haze-26469780 │ wispy-haze-26469780 │ 203.0.113.0 │ false │
│ │ │ 203.0.113.1 │ │
└─────────────────────┴─────────────────────┴──────────────┴─────────────────────┘To apply an IP allowlist to protected branches only, you can use the --protected-only option:
neon ip-allow add 203.0.113.1 --protected-onlyTo reverse that setting, use --protected-only false.
neon ip-allow add 203.0.113.1 --protected-only falseThe Create project and Update project methods support IP Allow configuration. For example, the following API call configures IP Allow for an existing SerenDB project. Separate multiple entries with commas. Each entry must be quoted. You can set the "protected_branches_only option to true to apply the allowlist to protected branches only, or false to apply it to all branches in your SerenDB project.
curl -X PATCH \
https://console.serendb.com/api/v2/projects/falling-salad-31638542 \
-H 'accept: application/json' \
-H 'authorization: Bearer $NEON_API_KEY' \
-H 'content-type: application/json' \
-d '
{
"project": {
"settings": {
"allowed_ips": {
"protected_branches_only": true,
"ips": [
"203.0.113.0", "203.0.113.1"
]
}
}
}
}
' | jqHow to specify IP addresses
You can define an allowlist with individual IP addresses, IP ranges, or CIDR notation. A combination of these options is also permitted. Multiple entries, whether they are the same or of different types, must be separated by a comma. Whitespace is ignored.
Add individual IP addresses: You can add individual IP addresses that you want to allow. This is useful for granting access to specific users or devices. This example represents a single IP address:
192.0.2.1Define IP ranges: For broader access control, you can define IP ranges. This is useful for allowing access from a company network or a range of known IPs. This example range includes all IP addresses from
198.51.100.20to198.51.100.50:198.51.100.20-198.51.100.50Use CIDR notation: For more advanced control, you can use CIDR (Classless Inter-Domain Routing) notation. This is a compact way of defining a range of IPs and is useful for larger networks or subnets. Using CIDR notation can be advantageous when managing access to branches with numerous potential users, such as in a large development team or a company-wide network.
This CIDR notation example represents all 256 IP addresses from
203.0.113.0to203.0.113.255.203.0.113.0/24Use IPv6 addresses: SerenDB projects provisioned on AWS also support specifying IPv6 addresses. For example:
IPv6 is not yet supported for projects provisioned on Azure.
2001:DB8:5432::/48
A combined example using all three options above, specified as a comma-separated list, would appear similar to the following:
192.0.2.1, 198.51.100.20-198.51.100.50, 203.0.113.0/24, 2001:DB8:5432::/48This list combines individual IP addresses, a range of IP addresses, a CIDR block, and an IPv6 address. It illustrates how different types of IP specifications can be used together in a single allowlist configuration, offering a flexible approach to access control.
Update an IP Allow configuration
You can update your IP Allow configuration via the SerenDB Console or API as described in Configure IP Allow. Replace the current configuration with the new configuration. For example, if your IP Allow configuration currently allows access from IP address 192.0.2.1, and you want to extend access to IP address 192.0.2.2, specify both addresses in your new configuration: 192.0.2.1, 192.0.2.2. You cannot append values to an existing configuration. You can only replace an existing configuration with a new one.
The SerenDB CLI provides an ip-allow command with add, reset, and remove options that you can use to update your IP Allow configuration. For instructions, refer to SerenDB CLI commands — ip-allow.
Remove an IP Allow configuration
To remove an IP configuration entirely to go back to the default "no IP restrictions" (0.0.0.0) configuration:
<Tabs labels={["SerenDB Console", "CLI", "API"]}>
Select a project in the SerenDB Console.
On the Project Dashboard, select Settings.
Select IP Allow.
Clear the Allowed IP addresses and ranges field.
If applicable, clear the Restrict IP Access to protected branches only checkbox.
Click Save changes.
The SerenDB CLI ip-allow command supports removing an IP Allow configuration. To do so, specify --ip-allow reset without specifying any IP address values:
neon ip-allow resetSpecify the ips option with an empty string. If applicable, also include "protected_branches_only": false.
curl -X PATCH \
https://console.serendb.com/api/v2/projects/falling-salad-31638542 \
-H 'accept: application/json' \
-H 'authorization: Bearer $NEON_API_KEY' \
-H 'content-type: application/json' \
-d '
{
"project": {
"settings": {
"allowed_ips": {
"protected_branches_only": false,
"ips": []
}
}
}
}
'Enable the Data API
The Data API turns your database tables into a REST API, making it easy to query your data from client applications. When you enable the Data API, it automatically creates authenticated and anonymous roles and sets up the necessary permissions for secure client-side access.
For setup instructions and examples, see the Data API documentation.
Enable logical replication
Logical replication lets you replicate data changes from SerenDB to external data services and platforms, including data warehouses, analytical database services, messaging platforms, event-streaming platforms, and external Postgres databases.
Enabling logical replication modifies the PostgreSQL `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your SerenDB project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your SerenDB project, meaning that active connections will be dropped and have to reconnect.
To enable logical replication in SerenDB:
Select your project in the SerenDB Console.
On the Project Dashboard, select Settings.
Select Logical replication.
Click Enable to enable logical replication.
You can verify that logical replication is enabled by running the following query:
SHOW wal_level;
wal_level
-----------
logicalAfter enabling logical replication, the next steps involve creating publications on your replication source database in SerenDB and configuring subscriptions on the destination system or service. To get started, refer to our logical replication guides.
Delete a project
Deleting a project is a permanent action, which also deletes any computes, branches, databases, and roles that belong to the project.
To delete a project:
Navigate to the SerenDB Console.
Select the project that you want to delete.
Select Settings.
Select Delete.
If you are any of SerenDB's paid plans, deleting all your SerenDB projects won't stop monthly billing. To avoid charges, you also need to downgrade to the Free plan. You can do so from the [Billing](https://console.serendb.com/app/billing#change_plan) page in the SerenDB Console.
Manage projects with the SerenDB API
Project actions performed in the SerenDB Console can also be performed using the SerenDB API. The following examples demonstrate how to create, view, and delete projects using the SerenDB API. For other project-related API methods, refer to the SerenDB API reference.
The API examples that follow may not show all of the user-configurable request body attributes that are available to you. To view all attributes for a particular method, refer to method's request body schema in the [SerenDB API reference](https://api-docs.serendb.com/reference/getting-started-with-neon-api).
The jq option specified in each example is an optional third-party tool that formats the JSON response, making it easier to read. For information about this utility, see jq.
Prerequisites
A SerenDB API request requires an API key. For information about obtaining an API key, see Create an API key. In the cURL examples shown below, $NEON_API_KEY is specified in place of an actual API key, which you must provide when making a SerenDB API request.
Create a project with the API
The following SerenDB API method creates a project. To view the API documentation for this method, refer to the SerenDB API reference.
POST /projectsThe API method appears as follows when specified in a cURL command. The myproject name value is a user-specified name for the project.
curl 'https://console.serendb.com/api/v2/projects' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $NEON_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"project": {
"name": "myproject"
}
}' | jqThe response includes information about the role, the database, the default branch, and the primary read-write compute that is created with the project.
List projects with the API
The following SerenDB API method lists projects for your SerenDB account. To view the API documentation for this method, refer to the SerenDB API reference.
GET /projectsThe API method appears as follows when specified in a cURL command:
curl 'https://console.serendb.com/api/v2/projects' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $NEON_API_KEY" | jqUpdate a project with the API
The following SerenDB API method updates the specified project. To view the API documentation for this method, refer to the SerenDB API reference.
PATCH /projects/{project_id}The API method appears as follows when specified in a cURL command. The project_id is a required parameter. The example changes the project name to project1.
curl -X PATCH 'https://console.serendb.com/api/v2/projects/ep-cool-darkness-123456' \
-H 'accept: application/json' \
-H "Authorization: Bearer $NEON_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"project": {
"name": "project1"
}
}'Delete a project with the API
The following SerenDB API method deletes the specified project. To view the API documentation for this method, refer to the SerenDB API reference.
DELETE /projects/{project_id}The API method appears as follows when specified in a cURL command. The project_id is a required parameter.
curl -X 'DELETE' \
'https://console.serendb.com/api/v2/projects/ep-cool-darkness-123456' \
-H 'accept: application/json' \
-H "Authorization: Bearer $NEON_API_KEY"Last updated